Aller au contenu principal
Dernière mise à jour le

Ingérer des données depuis OneDrive

info

Bêta

Cette fonctionnalité est en bêta. Les administrateurs du Workspace peuvent contrôler l’accès à cette fonctionnalité depuis la page Aperçus en activant l’aperçu Lakeflow Connect for OneDrive For Business . Consultez Gérer les aperçus Databricks.

Cette page explique comment créer un pipeline d’ingestion géré Microsoft OneDrive à l’aide de Lakeflow Connect. Le pipeline ingère les fichiers de OneDrive dans des tables Delta et les maintient synchronisés avec la source.

Avant de commencer​

  • Pour créer le pipeline d’ingestion, vous devez d’abord satisfaire aux exigences suivantes :

    • Votre Workspace doit être activé pour Unity Catalog.

    • Le compute Serverless doit être activé pour votre Workspace. Consultez les exigences du compute Serverless.

    • Pour créer une nouvelle connexion, vous devez disposer des privilèges CREATE CONNECTION sur le métastore. Consultez Gérer les privilèges dans Unity Catalog.

      Si le connecteur prend en charge la création de pipelines via l’interface utilisateur, un administrateur peut créer la connexion et le pipeline en même temps en effectuant les étapes indiquées sur cette page. Toutefois, si les utilisateurs qui créent des pipelines utilisent la création de pipelines via l’API ou ne sont pas administrateurs, un administrateur doit d’abord créer la connexion dans l’Explorateur de catalogues. Consultez Connecter des sources d’ingestion gérées.

    • Pour utiliser une connexion existante, vous devez disposer des privilèges USE CONNECTION ou de ALL PRIVILEGES sur l’objet de connexion.

    • Vous devez disposer des privilèges USE CATALOG sur le catalogue cible.

    • Vous devez disposer des privilèges USE SCHEMA et CREATE TABLE sur un schéma existant, ou des privilèges CREATE SCHEMA sur le catalogue cible.

  • Utilisez Databricks Runtime 19 ou une version ultérieure. Dans une définition de pipeline API ou Declarative Automation Bundles, définissez channel sur PREVIEW.

  • Pour utiliser les bundles d'automatisation déclarative, utilisez la version 1.23.0 ou supérieure de Databricks CLI. Les versions précédentes suppriment onedrive_options de la définition du pipeline.

  • Pour ingérer des données depuis OneDrive, vous devez d’abord configurer une méthode d’authentification prise en charge et créer une connexion. Consultez Créer une connexion OneDrive.

Créer un pipeline d’ingestion​

Pour obtenir la liste des formats de fichiers pris en charge, consultez les paramètres file_ingestion_options. Pour connaître les limitations propres à chaque connecteur, consultez les limitations du connecteur Microsoft OneDrive.

Utilisez les Declarative Automation Bundles pour gérer les pipelines OneDrive en tant que code. Les bundles peuvent contenir des définitions YAML de Jobs et de tâches, sont gérés à l'aide de la CLI Databricks et peuvent être partagés et exécutés dans différents Workspace cibles (tels que le développement, la pré-production et la production). Consultez Que sont les Declarative Automation Bundles ?.

  1. Créer un bundle à l’aide de la CLI Databricks :

    Bash
    databricks bundle init

  2. Ajoutez deux nouveaux fichiers de ressources au bundle :

  3. Déployez le pipeline à l’aide du CLI Databricks :

    Bash
    databricks bundle deploy

Le déploiement du bundle crée le pipeline et le job. Le job exécute le pipeline selon la planification dans la définition du job.

Choisissez une URL source​

Chaque objet d’une définition de pipeline spécifie sa source dans connector_options.onedrive_options.url. L’URL doit aboutir à l’une des ressources suivantes dans un lecteur Mes fichiers OneDrive for Business :

  • La racine du lecteur
  • Un dossier
  • Un fichier
  • Un Link de partage valide

L’URL doit utiliser un hôte OneDrive personnel, tel que <tenant>-my.sharepoint.com. Les URL suivantes ne sont pas prises en charge :

  • URL de sites SharePoint (/sites/...)
  • URL OneDrive grand public, telles que onedrive.live.com ou 1drv.ms
  • URL d’hôtes seuls
  • Chemins en dehors d’un lecteur personnel

Pour obtenir des exemples d’URL et des instructions pour copier une URL depuis OneDrive, consultez Lire des fichiers depuis OneDrive.

Exemples​

Utilisez ces exemples pour configurer votre pipeline. Remplacez chaque espace réservé par les valeurs correspondant à votre environnement.

Ingérer les fichiers en tant que données non structurées​

Ingérez les fichiers de OneDrive en tant que contenu binaire. Chaque fichier devient une ligne contenant ses octets et ses métadonnées. Utilisez cette approche pour les PDF, les documents Office, les images et les autres fichiers que vous prévoyez de traiter en aval, par exemple pour des applications RAG.

remarque

Disponible en version bêta, le type FILE stocke une référence gouvernée vers chaque fichier et ses métadonnées au lieu des octets du fichier, ce qui améliore les performances de lecture. Pour ingérer les fichiers en tant que type FILE plutôt que BINARYFILE, consultez Ingérer des fichiers en tant que type FILE (bêta).

YAML
resources:
  pipelines:
    onedrive_binary_pipeline:
      name: onedrive_binary_pipeline
      catalog: main
      schema: ingest_destination_schema
      channel: PREVIEW
      ingestion_definition:
        connection_name: <onedrive-connection>
        objects:
          - table:
              destination_catalog: main
              destination_schema: ingest_destination_schema
              destination_table: drive_files
              connector_options:
                onedrive_options:
                  entity_type: FILE
                  url: https://mytenant-my.sharepoint.com/personal/user_mytenant_onmicrosoft_com/Documents
                  file_ingestion_options:
                    format: BINARYFILE
                    schema_evolution_mode: NONE

Ingérer des fichiers en tant que type FILE (bêta)​

info

Bêta

Cette fonctionnalité est en Bêta.

Ingérez les fichiers en tant que type FILE afin de copier chaque fichier source dans un volume Unity Catalog et de stocker une référence gouvernée à chaque fichier ainsi que ses métadonnées dans la table de destination. La table de destination expose une colonne file que vous pouvez transmettre à des fonctions telles que ai_parse_document et aux fonctions définies par l’utilisateur (UDF).

Pour utiliser le type FILE, configurez les éléments suivants dans votre pipeline :

  • Définissez le pipeline channel sur PREVIEW.
  • Définissez file_ingestion_options.format sur FILE.
  • Définissez la propriété de table databricks.filespace-preview pour déclarer le volume qu’Unity Catalog utilise comme stockage géré.

Pour connaître les exigences et le comportement de FILE, consultez Ingérer des fichiers en tant que type FILE.

YAML
resources:
  pipelines:
    onedrive_file_pipeline:
      name: onedrive_file_pipeline
      catalog: <catalog>
      schema: <schema>
      channel: PREVIEW
      ingestion_definition:
        connection_name: <onedrive-connection>
        objects:
          - table:
              destination_catalog: <catalog>
              destination_schema: <schema>
              destination_table: <destination-table>
              table_configuration:
                table_properties:
                  databricks.filespace-preview: /Volumes/<catalog>/<schema>/<volume>/
              connector_options:
                onedrive_options:
                  entity_type: FILE
                  url: https://mytenant-my.sharepoint.com/personal/user_mytenant_onmicrosoft_com/Documents
                  file_ingestion_options:
                    format: FILE
                    schema_evolution_mode: NONE

Ingérer des fichiers structurés​

Ingérer des fichiers structurés, par exemple des fichiers JSON, depuis un dossier OneDrive. Chaque ligne des fichiers sources devient une ligne dans la table de destination.

YAML
resources:
  pipelines:
    onedrive_json_pipeline:
      name: onedrive_json_pipeline
      catalog: main
      schema: ingest_destination_schema
      channel: PREVIEW
      ingestion_definition:
        connection_name: <onedrive-connection>
        objects:
          - table:
              destination_catalog: main
              destination_schema: ingest_destination_schema
              destination_table: json_files
              connector_options:
                onedrive_options:
                  entity_type: FILE
                  url: https://mytenant-my.sharepoint.com/personal/user_mytenant_onmicrosoft_com/Documents/json_folder
                  file_ingestion_options:
                    format: JSON
                    schema_evolution_mode: NONE

Ingérer uniquement les métadonnées de fichier​

Ingérer les métadonnées des fichiers (nom, taille, Timestamp, chemin) sans effectuer le download du contenu des fichiers. Utilisez cette approche lorsque vous avez besoin d’un inventaire des fichiers sans la surcharge liée à l’ingestion de leur contenu.

Définissez entity_type sur FILE_METADATA. L’ingestion de FILE_METADATA doit utiliser le format BINARYFILE. Les formats structurés et semi-structurés ne sont pas pris en charge pour l’ingestion des métadonnées uniquement.

YAML
resources:
  pipelines:
    onedrive_metadata_pipeline:
      name: onedrive_metadata_pipeline
      catalog: main
      schema: ingest_destination_schema
      channel: PREVIEW
      ingestion_definition:
        connection_name: <onedrive-connection>
        objects:
          - table:
              destination_catalog: main
              destination_schema: ingest_destination_schema
              destination_table: file_metadata
              connector_options:
                onedrive_options:
                  entity_type: FILE_METADATA
                  url: https://mytenant-my.sharepoint.com/personal/user_mytenant_onmicrosoft_com/Documents
                  file_ingestion_options:
                    format: BINARYFILE
                    schema_evolution_mode: NONE

Fichier de définition de job Declarative Automation Bundles​

Cet exemple de fichier de définition de job exécute le pipeline chaque jour. Il refresh le pipeline à partir de Ingérer des fichiers en tant que données non structurées. Pour refresh un pipeline différent, remplacez onedrive_binary_pipeline par la clé de ressource de ce pipeline.

YAML
resources:
  jobs:
    onedrive_job:
      name: onedrive_job

      trigger:
        periodic:
          interval: 1
          unit: DAYS

      email_notifications:
        on_failure:
          - <email-address>

      tasks:
        - task_key: refresh_pipeline
          pipeline_task:
            pipeline_id: ${resources.pipelines.onedrive_binary_pipeline.id}

Configurer les options d’ingestion de fichiers​

Le bloc file_ingestion_options contrôle la manière dont les fichiers sont traités. Toutes les options sont définies dans le bloc connector_options.onedrive_options.file_ingestion_options de la définition du pipeline. Les extraits suivants utilisent la syntaxe YAML de Declarative Automation Bundles. Dans une définition de pipeline de notebook ou d’API, utilisez les mêmes clés en JSON. Pour tous les parameters, voir parameters file_ingestion_options.

Filtres de fichiers​

Utilisez file_filters pour limiter les fichiers ingérés depuis l’URL source :

YAML
file_ingestion_options:
  format: CSV
  file_filters:
    - path_filter: invoices/*.csv
    - modified_after: 2026-01-01T00:00:00

Évolution des schémas et indications de schéma​

Définissez schema_evolution_mode pour contrôler la façon dont les nouvelles colonnes des fichiers entrants sont gérées. Remplacez les types de colonnes déduits à l’aide de schema_hints.

L’évolution des schémas s’applique uniquement à CSV, JSON, XML, PARQUET et AVRO. Pour les autres formats (BINARYFILE, FILE, EXCEL et ORC), définissez schema_evolution_mode sur NONE.

YAML
file_ingestion_options:
  format: CSV
  schema_evolution_mode: ADD_NEW_COLUMNS_WITH_TYPE_WIDENING
  schema_hints: order_id INT, amount DOUBLE, ts TIMESTAMP

Pour plus d’informations sur l’évolution des schémas et les conseils, consultez Configurer l’inférence et l’évolution des schémas dans Auto Loader.

Options spécifiques au format​

Transmettre les options spécifiques au format à l’aide de format_options:

YAML
file_ingestion_options:
  format: CSV
  format_options:
    header: 'true'
    sep: ','

Les clés prises en charge sont les options de format standard d’Auto Loader. Voir les options de source de données Spark.

Modèles courants​

Pour les configurations avancées des pipelines, consultez Modèles courants pour les pipelines d’ingestion gérés.

Étapes suivantes​

Start, planifier et configurer des alertes sur votre pipeline. Consultez les tâches courantes de maintenance du pipeline.

Ressources supplémentaires​

Sur cette page