Ingérer des fichiers à partir de Google Drive

:::note Conformité

Le connecteur Google Drive prend en charge l’utilisation dans les espaces de travail avec les paramètres de sécurité et de conformité améliorés activés .

:::

Le connecteur Google Drive standard dans Lakeflow Connect vous permet d’utiliser les fonctions Spark et SQL d'Azure Databricks (read_files, spark.read, COPY INTO et Auto Loader) pour créer des DataFrames Spark, des vues matérialisées et des tables de streaming directement à partir de fichiers sur Google Drive.

Avec cette approche, vous pouvez créer des pipelines personnalisés pour les cas d’utilisation courants de l’ingestion de fichiers :

• Ingestion de fichiers de streaming (non structurée) : ingestion de nombreux fichiers sources (par exemple, PDF, Google Docs et Google Slides) dans une table cible unique en tant que données binaires, idéale pour les pipelines RAG.
• Ingestion de fichiers de streaming (structurée) : fusion de nombreux fichiers sources (par exemple, fichiers CSV et JSON) dans une table cible unique et structurée.
• Ingestion de fichiers batch : ingestion d’un fichier spécifique unique (tel qu’une feuille Google) ou d’un lot de fichiers dans une table cible.

Ces interfaces sont prises en charge :

• Paquets d'Automatisation déclarative
• API Databricks
• Kits SDK Databricks
• Interface CLI de Databricks

Limites

• Le connecteur est uniquement API et ne prend pas en charge la création de pipelines dans l’interface utilisateur Azure Databricks.
• Vous pouvez utiliser l’option pathGlobFilter pour filtrer les fichiers par nom (par exemple, pathGlobFilter => '*.csv'). Les formats Google intégrés (par exemple, Google Docs ou Google Sheets) ne peuvent pas être filtrés à l’aide de cette option. Le filtrage des chemins d’accès aux dossiers n’est pas non plus pris en charge.
• Les formats non pris en charge incluent Google Forms, Google Sites, Google Jams et Google Vids. Le processus d’ingestion ignore les formats non pris en charge.
• Le paramètre recursiveFileLookup=false n’est pas pris en charge pour les lectures de lots Spark. L’utilisation recursiveFileLookup=false se comporte de la même façon que recursiveFileLookup=true.

Spécifications

Avant de commencer, vérifiez que vous disposez des éléments suivants :

• Un espace de travail avec catalogue Unity.
• CREATE CONNECTION privilèges pour créer une connexion Google Drive ou le privilège approprié pour utiliser un compte existant en fonction du mode d’accès de votre cluster :
  • Mode d’accès dédié : MANAGE CONNECTION.
  • Mode d’accès standard : USE CONNECTION.
• Databricks Runtime 17.3 ou version ultérieure.
• La fonctionnalité bêta du format de fichier Excel activée, si vous souhaitez ingérer des fichiers Google Sheets ou Excel. Voir Read Excel files.
• Un compte Google disposant des autorisations nécessaires pour créer un projet Google Cloud.

Configurer OAuth 2.0

Configurer un projet Google Cloud et activer l’API Google Drive

1. Accédez à la console Google Cloud.
2. Créez un projet. Vous pouvez être invité à configurer l’authentification à deux facteurs.
3. Accédez à la bibliothèque d’API &services>.
4. Recherchez « API Google Drive ».
5. Sélectionnez l’API Google Drive.
6. Sélectionnez Activer.

Configurer l’écran de consentement OAuth pour votre projet

1. Sur l’écran d’accueil de la console Google Cloud, accédez à l’écran de consentement OAuth des API et services>. Un message indiquant « Google Auth Platform n’est pas encore configuré ».
2. Sélectionnez Démarrer.
3. Renseignez la section Informations sur l’application . Entrez n’importe quel nom pour le nom de l’application (par exemple, Databricks connection). L’e-mail de support peut être n’importe quel e-mail de votre organisation.
4. Cliquez sur Suivant.
5. Dans la section Audience , sélectionnez Externe, puis Sélectionnez Suivant.
6. Renseignez la section Informations de contact , puis sélectionnez Suivant.
7. Passez en revue la stratégie de données utilisateur des services d’API Google, puis sélectionnez Créer.
8. Revenez à Google Auth Platform > Data Access.
9. Sélectionnez Ajouter ou supprimer des étendues.
10. Ajoutez l’étendue suivante dans la section Ajouter manuellement des étendues , sélectionnez Ajouter à la table, puis sélectionnez Mettre à jour : https://www.googleapis.com/auth/drive.readonly
11. Cliquez sur Enregistrer.

Créer des informations d’identification client OAuth 2.0

1. Sur l’écran d’accueil de la console Google Cloud, accédez aux API et informations d’identification des services>.
2. Sélectionnez Créer des informations d'identification>ID client OAuth.
3. Choisissez Application web et définissez un nom personnalisé.
4. Dans les URI de redirection autorisés, sélectionnez Ajouter un URI.
5. Ajoutez un URI de redirection à <databricks-instance-url>/login/oauth/google.html, en remplaçant <databricks-instance-url> par l’URL de votre instance de Azure Databricks. Par exemple : https://instance-name.databricks.com/login/oauth/google.html
6. Cliquez sur Créer. Une boîte de dialogue contenant vos informations d’identification s’affiche.
7. Enregistrez les valeurs suivantes. Vous pouvez également télécharger le fichier JSON du client OAuth, qui contient ces informations :
   • ID client (format : 0123******-********************************.apps.googleusercontent.com)
   • Clé secrète client (format : ABCD**-****************************)

Ajouter des utilisateurs de test à votre projet

1. Accédez à Google Auth Platform > Audience.
2. Sous Utilisateurs de test, sélectionnez Ajouter des utilisateurs.
3. Ajoutez l’adresse e-mail du compte Google que vous utiliserez pour créer la connexion.

Créer une connexion

1. Dans l’espace de travail Azure Databricks, sélectionnez Catalog > Emplacements externes > Connexions > Créer une connexion.

2. Dans la page Informations de base de connexion de l’assistant Configurer la connexion, spécifiez un Nom de connexion unique.

3. Dans le menu déroulant Type de connexion , recherchez et sélectionnez Google Drive.

4. (Facultatif) Ajoutez un commentaire.

5. Cliquez sur Suivant.

6. Dans la page Authentification , entrez les éléments suivants :

   • Étendue OAuth : https://www.googleapis.com/auth/drive.readonly
   • Clé secrète client : la clé secrète client issue de la création des informations d’identification du client OAuth 2.0.
   • ID client : ID client à partir de créer des informations d’identification client OAuth 2.0.

7. Sélectionnez Se connecter avec Google et connectez-vous avec le compte Google à partir d’Ajouter des utilisateurs de test à votre projet.

8. Sélectionnez Continuer, puis Continuez à nouveau.

9. Une fois que vous êtes redirigé vers l'espace de travail Azure Databricks, sélectionnez Créer la connexion.

Ingérer des fichiers à partir de Google Drive

Ingérer des fichiers à partir de Google Drive à l’aide du connecteur et read_files (Databricks SQL), du chargeur automatique (.readStream avec cloudFiles), COPY INTOet spark.read. Vous devez fournir les valeurs suivantes :

• URL google drive comme chemin d’accès.
• Connexion au catalogue Unity en utilisant l’option de source de données databricks.connection.
• URL de la ressource Google Drive à laquelle vous souhaitez accéder. L’URL peut faire référence à un fichier spécifique, à un dossier ou à un lecteur entier. Par exemple:
  • https://docs.google.com/spreadsheets/d/12345/edit?random_query_params_here
  • https://drive.google.com/drive/u/0/folders/12345
  • https://docs.google.com/document/d/12345/edit
  • https://drive.google.com/file/d/1kiXnHmU4Y8X66ijULky5EPDNCGtT14Ps/view?usp=drive_link
  • https://drive.google.com/drive/
  • https://drive.google.com/drive/my-drive
  • https://drive.google.com/

Diffuser en continu des fichiers Google Drive à l’aide du chargeur automatique

Le chargeur automatique est le moyen le plus efficace d’ingérer de manière incrémentielle des fichiers structurés à partir de Google Drive. Il détecte automatiquement les nouveaux fichiers et les traite à mesure qu’ils arrivent. Il peut également ingérer des fichiers structurés et semi-structurés tels que CSV et JSON avec l’inférence et l’évolution automatiques du schéma. Pour plus d’informations sur l’utilisation du chargeur automatique, consultez Modèles de chargement de données courants.

# Incrementally ingest new PDF files
df = (spark.readStream.format("cloudFiles")
    .option("cloudFiles.format", "binaryFile")
    .option("databricks.connection", "my_gdrive_conn")
    .option("cloudFiles.schemaLocation", <path to a schema location>)
    .option("pathGlobFilter", "*.pdf")
    .load("https://drive.google.com/drive/folders/1a2b3c4d...")
    .select("*", "_metadata")
)

# Incrementally ingest CSV files with automatic schema inference and evolution
df = (spark.readStream.format("cloudFiles")
    .option("cloudFiles.format", "csv")
    .option("databricks.connection", "my_gdrive_conn")
    .option("pathGlobFilter", "*.csv")
    .option("inferColumnTypes", True)
    .option("header", True)
    .load("https://drive.google.com/drive/folders/1a2b3c4d...")
)

Lire des fichiers Google Drive à l’aide de la lecture par lots Spark

L’exemple suivant montre comment ingérer des fichiers Google Drive dans Python à l’aide de la fonction spark.read. Pour obtenir la liste des formats de fichiers pris en charge et des options de lecteur Spark, consultez les options de source de fichiers génériques dans la documentation Apache Spark.

Le paramètre recursiveFileLookup=false n’est pas pris en charge pour les lectures de lots Spark. L’utilisation recursiveFileLookup=false se comporte de la même façon que recursiveFileLookup=true.

# Read unstructured data as binary files
df = (spark.read
        .format("binaryFile")
        .option("databricks.connection", "my_gdrive_conn")
        .option("recursiveFileLookup", True)
        .option("pathGlobFilter", "*.pdf")
        .load("https://drive.google.com/drive/folders/1a2b3c4d..."))

# Read a batch of CSV files, infer the schema, and load the data into a DataFrame
df = (spark.read
        .format("csv")
        .option("databricks.connection", "my_gdrive_conn")
        .option("pathGlobFilter", "*.csv")
        .option("recursiveFileLookup", True)
        .option("inferSchema", True)
        .option("header", True)
        .load("https://drive.google.com/drive/folders/1a2b3c4d..."))

Lire un seul fichier Google Drive structuré

L’exemple suivant lit un seul onglet d’une feuille Google et le charge dans un DataFrame. Il illustre quelques options d’analyse courantes.

Pour voir la liste complète des options d'analyse syntaxique prises en charge pour les fichiers Excel et Google Sheets, consultez Lire les fichiers Excel. Pour obtenir la liste complète de tous les autres formats de fichiers pris en charge et options de lecteur Spark, consultez les options de source de fichier générique dans la documentation Apache Spark.

df = (spark.read
  .format("excel")  # use 'excel' for Google Sheets
  .option("databricks.connection", "my_gdrive_conn")
  .option("headerRows", 1) # optional
  .option("inferColumns", True) # optional
  .option("dataAddress", "Sheet1!A1:Z10")  # optional
  .load("https://docs.google.com/spreadsheets/d/9k8j7i6f..."))

Lire des fichiers Google Drive à l’aide de Spark SQL

L'exemple suivant montre comment ingérer des fichiers depuis Google Drive dans SQL à l’aide de la fonction table-valorisée read_files. Pour plus d’informations sur read_files l’utilisation, consultez read_files la fonction valeur de table.

-- Read pdf files
CREATE TABLE my_table AS
SELECT * FROM read_files(
  "https://drive.google.com/drive/folders/1a2b3c4d...",
  `databricks.connection` => "my_gdrive_conn",
  format => "binaryFile",
  pathGlobFilter => "*.pdf", -- optional. Example: only ingest PDFs
  schemaEvolutionMode => "none"
);

-- Read a Google Sheet and range
CREATE TABLE my_sheet_table AS
SELECT * FROM read_files(
  "https://docs.google.com/spreadsheets/d/9k8j7i6f...",
  `databricks.connection` => "my_gdrive_conn",
  format => "excel",
  headerRows => 1,  -- optional
  dataAddress => "Sheet1!A2:D10", -- optional
  schemaEvolutionMode => "none"
);

Ingérer des fichiers Google Drive à l’aide de pipelines déclaratifs Spark Lakeflow

Cet exemple montre comment lire des fichiers Google Drive à l’aide du chargeur automatique dans les pipelines déclaratifs Spark Lakeflow. Pour plus d’informations, consultez Pipelines déclaratifs Spark Lakeflow

SQL

-- Incrementally ingest new PDF files
CREATE OR REFRESH STREAMING TABLE gdrive_pdf_table
AS SELECT * FROM STREAM read_files(
  "https://drive.google.com/drive/folders/1a2b3c4d...",
  format => "binaryFile",
  `databricks.connection` => "my_gdrive_conn",
  pathGlobFilter => "*.pdf");

-- Incrementally ingest CSV files with automatic schema inference and evolution
CREATE OR REFRESH STREAMING TABLE gdrive_csv_table
AS SELECT * FROM STREAM read_files(
  "https://drive.google.com/drive/folders/1a2b3c4d...",
  format => "csv",
  `databricks.connection` => "my_gdrive_conn",
  pathGlobFilter => "*.csv",
  "header", "true");

-- Read a specific Excel file from Google Drive in a materialized view
CREATE OR REFRESH MATERIALIZED VIEW gdrive_excel_table
AS SELECT * FROM read_files(
  "https://docs.google.com/spreadsheets/d/9k8j7i6f...",
  `databricks.connection` => "my_gdrive_conn",
  format => "excel",
  headerRows => 1,  -- optional
  dataAddress => "Sheet1!A2:D10", -- optional
  `cloudFiles.schemaEvolutionMode` => "none"
);

Python

from pyspark import pipelines as dp

# Incrementally ingest new PDF files
@dp.table
def gdrive_pdf_table():
  return (spark.readStream.format("cloudFiles")
    .option("cloudFiles.format", "binaryFile")
    .option("databricks.connection", "my_gdrive_conn")
    .option("pathGlobFilter", "*.pdf")
    .load("https://drive.google.com/drive/folders/1a2b3c4d...")
  )

# Incrementally ingest CSV files with automatic schema inference and evolution
@dp.table
def gdrive_csv_table():
  return (spark.readStream.format("cloudFiles")
      .option("cloudFiles.format", "csv")
      .option("databricks.connection", "my_gdrive_conn")
      .option("pathGlobFilter", "*.csv")
      .option("inferColumnTypes", True)
      .option("header", True)
      .load("https://drive.google.com/drive/folders/1a2b3c4d...")
  )

# Read a specific Excel file from Google Drive in a materialized view
@dp.table
def gdrive_excel_table():
  return (spark.read.format("excel")
    .option("databricks.connection", "my_gdrive_conn")
    .option("headerRows", 1) # optional
    .option("inferColumnTypes", True) # optional
    .option("dataAddress", "Sheet1!A1:M20") # optional
    .load("https://docs.google.com/spreadsheets/d/9k8j7i6f..."))

Analyser des fichiers non structurés avec ai_parse_document

Lorsque vous ingérez des fichiers non structurés à partir de Google Drive (par exemple, des fichiers PDF, des documents Word ou des fichiers PowerPoint) à l’aide du connecteur Google Drive standard avec binaryFile format, le contenu du fichier est stocké sous forme de données binaires brutes. Pour préparer ces fichiers pour les charges de travail IA, telles que RAG, la recherche, la classification ou la compréhension des documents, vous pouvez analyser le contenu binaire en sortie structurée et interrogeable à l’aide ai_parse_documentde .

L’exemple suivant montre comment analyser des documents non structurés stockés dans une table Delta bronze nommée documents, en ajoutant une nouvelle colonne avec du contenu analysé :

CREATE TABLE documents AS
SELECT *, _metadata FROM read_files(
  "https://drive.google.com/drive/folders/1a2b3c4d...",
  `databricks.connection` => "my_gdrive_conn",
  format => "binaryFile",
  pathGlobFilter => "*.{pdf,jpeg}"
);
SELECT *, ai_parse_document(content) AS parsed_content
FROM documents;

La parsed_content colonne contient du texte extrait, des tables, des informations de disposition et des métadonnées qui peuvent être utilisées directement pour les pipelines IA en aval.

Analyse incrémentielle avec les pipelines déclaratifs de Lakeflow Spark

Vous pouvez également utiliser ai_parse_document dans les pipelines déclaratifs Spark Lakeflow pour activer l’analyse incrémentielle. À mesure que les nouveaux fichiers arrivent de Google Drive, ils sont automatiquement analysés lorsque votre flux de travaux se met à jour.

Par exemple, vous pouvez définir une vue matérialisée qui analyse en continu les documents nouvellement ingérés :

CREATE OR REFRESH STREAMING TABLE documents
AS SELECT *, "_metadata" FROM STREAM read_files(
  "https://drive.google.com/drive/folders/1a2b3c4d...",
  format => "binaryFile",
  `databricks.connection` => "my_gdrive_conn",
  pathGlobFilter => "*.{pdf,jpeg}");

CREATE OR REFRESH MATERIALIZED VIEW documents_parsed
AS
SELECT *, ai_parse_document(content) AS parsed_content
FROM documents;

Cette approche garantit que :

• Les fichiers Google Drive récemment ingérés sont analysés automatiquement chaque fois que l’affichage matérialisé est actualisé
• Les sorties analysées restent synchronisées avec les données entrantes
• Les pipelines IA en aval fonctionnent toujours sur des représentations de documents à jour

Pour connaître les formats pris en charge et les options avancées, consultez ai_parse_document la fonction.

Comment les formats Google intégrés sont gérés

Vous n’avez pas besoin d’exporter manuellement vos fichiers Google intégrés (Docs, Sheets). Le connecteur les exporte automatiquement dans un format ouvert pendant l’ingestion.

Configuration du format d’exportation Google Drive

Vous pouvez configurer la façon dont les fichiers natifs Google Drive sont exportés en définissant des configurations Spark à l’aide de spark.conf.set(). Ces configurations déterminent le type utilisé lors de l’exportation MIME de Google Docs, Feuilles, Diapositives et Dessins.

Clés de configuration :

• fs.gdrive.format.document.export: Format d’exportation Google Docs.
• fs.gdrive.format.spreadsheet.export: Format d’exportation Google Sheets.
• fs.gdrive.format.presentation.export: Format d’exportation Google Slides.
• fs.gdrive.format.drawing.export: Format d’exportation des dessins Google.

Pour obtenir la liste complète des formats d’exportation pris en charge, consultez Exporter des types MIME pour les documents Google Workspace dans la documentation Google Workspace.

L’exemple suivant exporte un fichier Google Docs en tant que TXT.

spark.conf.set("fs.gdrive.format.document.export", "text/plain")
df = spark.read.text("https://docs.google.com/document/d/1a2b3c4d...")

L’exemple suivant exporte un fichier Google Sheets au format CSV.

spark.conf.set("fs.gdrive.format.spreadsheet.export", "text/csv")
df = spark.read.option("header", "true").csv("https://docs.google.com/spreadsheets/d/1a2b3c4d...")

Schemas

format de fichier binaire

Lorsque vous utilisez format => 'binaryFile', la table résultante a le schéma suivant :

• path (chaîne) : URL complète du fichier.
• modificationTime (horodatage) : heure de la dernière modification du fichier.
• length (long) : taille du fichier en octets.
• content (binaire) : contenu binaire brut du fichier.

colonne _metadata

Vous pouvez obtenir des informations de métadonnées pour les fichiers d’entrée avec la _metadata colonne telle que file_name, , file_pathfile_size, et file_modification_time. La _metadata colonne est une colonne masquée et est disponible pour tous les formats de fichier d’entrée. Pour inclure la _metadata colonne dans le DataFrame retourné, vous devez la sélectionner explicitement dans la requête de lecture où vous spécifiez la source. Pour plus d’informations, consultez Colonne de métadonnées de fichier.

Pour les fichiers natifs Google Drive (tels que Google Docs, Google Sheets et Google Slides), le file_size champ fait référence à la taille du fichier stocké sur Google Drive, et non à la taille du fichier au format exporté (par exemple, DOCX, XLSX ou PPTX).

Exemple de sélection _metadata:

SELECT *, _metadata FROM read_files(
  "https://drive.google.com/",
  `databricks.connection` => "my_connection",
  format => "binaryFile"
);

Colonne de métadonnées Google Drive

La _gdrive_metadata colonne est une colonne de métadonnées masquée qui permet d’accéder aux propriétés spécifiques à Google Drive des fichiers ingérés, provenant de la ressource Google Drivefiles. Il nécessite Databricks Runtime 18.1 ou version ultérieure et est disponible pour tous les formats de fichier lors de la lecture à partir de Google Drive. Pour inclure la _gdrive_metadata colonne dans le DataFrame retourné, vous devez la sélectionner explicitement dans la requête de lecture.

Si la source de données contient une colonne nommée _gdrive_metadata, la colonne de métadonnées Google Drive est renommée __gdrive_metadata en (avec un trait de soulignement de début supplémentaire) pour dédupliquer. Des traits de soulignement supplémentaires sont ajoutés jusqu’à ce que le nom soit unique.

Les métadonnées de fichier courantes telles que le chemin d’accès ou la taille du fichier peuvent être interrogées à l’aide de la _metadata colonne. Pour plus d’informations, consultez Colonne de métadonnées de fichier.

Schéma

La colonne _gdrive_metadata est une STRUCT contenant les champs suivants. Tous les champs sont nullables.

Exemples

Les exemples suivants montrent comment inclure la _gdrive_metadata colonne dans une requête de lecture, sélectionner des champs spécifiques dans la colonne et extraire des valeurs à partir de VARIANT champs.

Python

df = (spark.read
  .format("binaryFile")
  .option("databricks.connection", "my_gdrive_conn")
  .load("https://drive.google.com/drive/folders/1a2b3c4d...")
  .select("*", "_metadata", "_gdrive_metadata"))

SQL

SELECT *, _gdrive_metadata
FROM read_files(
  "https://drive.google.com/drive/folders/1a2b3c4d...",
  `databricks.connection` => "my_gdrive_conn",
  format => "binaryFile"
);

Sélectionnez des champs spécifiques dans le _gdrive_metadata struct :

df = (spark.read
  .format("binaryFile")
  .option("databricks.connection", "my_gdrive_conn")
  .load("https://drive.google.com/drive/folders/1a2b3c4d...")
  .select("_gdrive_metadata.id", "_gdrive_metadata.md5_checksum"))

Extrayez des valeurs des champs properties ou additional_metadataVARIANT à l’aide de l’opérateur de transtypage ::.

SELECT
  *,
  _gdrive_metadata.properties:department::STRING AS department
FROM read_files(
  "https://drive.google.com/drive/folders/1a2b3c4d...",
  `databricks.connection` => "my_gdrive_conn",
  format => "binaryFile"
);

Questions fréquentes (FAQ)

J’ai un dossier de plusieurs fichiers structurés (par exemple, plusieurs Google Sheets). Comment charger chaque feuille ou fichier en tant que propre table Delta ?

Vous devez créer une requête d’ingestion pour chaque fichier à ingérer dans sa propre table Delta.

Mes fichiers nécessitent une analyse personnalisée. Comment fournir ces paramètres d’analyse pour vérifier que mes fichiers sont lus correctement ?

Le connecteur prend en charge toutes les options de format de fichier disponibles dans le chargeur automatique, COPY INTOet Spark. Pour plus d’informations, consultez les rubriques suivantes :

• Options du chargeur automatique
• Options de base
• Sources de données - Spark

Les fichiers dans les sous-dossiers sont-ils ingérés de manière récursive ?

Lorsque vous utilisez les API du chargeur automatique (spark.readStream et read_files), tous les sous-dossiers sont détectés et ingérés de manière récursive. Cela est également vrai pour le traitement par lots spark.read, où les fichiers du chemin d’accès du dossier fourni sont toujours lus de manière récursive.

Ma feuille Google a de nombreuses irrégularités et nécessite une analyse et une extraction spécifiques de plages de cellules (par exemple, plusieurs tableaux par feuille). Le schéma ne peut pas être déduit automatiquement. Comment gérer cela ?

Vous pouvez utiliser les options d'analyse de format de fichier Excel pour analyser votre fichier de feuille Google au format souhaité. Voir Read Excel files.

Vous pouvez également désactiver l’inférence de schéma sur le chargeur automatique, PySpark ou read_files. La table résultante a des noms de colonnes par défaut, tous les types de données sont convertis en chaîne et la table peut être éparse. Vous pouvez ensuite effectuer toutes les transformations nécessaires en aval.

Étapes suivantes

• Explorer les modèles de chargement de données courants
• Vérifier ai_parse_document la fonction