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 d’API, définissez channel sur PREVIEW.

  • 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.

  1. Importez le Notebook suivant dans votre Workspace Databricks :
Ouvrir le notebook dans un nouvel ongletOuvrir dans Databricks

  1. Ne modifiez pas la cellule deux.

  2. Modifiez la cellule trois avec les informations de configuration de votre pipeline. Voir la référence du connecteur Microsoft OneDrive et les exemples.

  3. Cliquez sur Tout exécuter .

L’exécution du Notebook crée le pipeline, mais ne le start pas. Pour start et planifier le pipeline, consultez Tâches courantes de maintenance du pipeline.

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).

Python
pipeline_spec = {
  "name": "onedrive_binary_pipeline",
  "catalog": "main",
  "schema": "ingest_destination_schema",
  "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"
              }
            }
          }
        }
      }
    ]
  },
  "channel": "PREVIEW"
}

json_payload = json.dumps(pipeline_spec, indent=2)
create_pipeline(json_payload)

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.

Python
pipeline_spec = {
  "name": "onedrive_file_pipeline",
  "catalog": "<catalog>",
  "schema": "<schema>",
  "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"
              }
            }
          }
        }
      }
    ]
  },
  "channel": "PREVIEW"
}

json_payload = json.dumps(pipeline_spec, indent=2)
create_pipeline(json_payload)

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.

Python
pipeline_spec = {
  "name": "onedrive_json_pipeline",
  "catalog": "main",
  "schema": "ingest_destination_schema",
  "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"
              }
            }
          }
        }
      }
    ]
  },
  "channel": "PREVIEW"
}

json_payload = json.dumps(pipeline_spec, indent=2)
create_pipeline(json_payload)

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.

Python
pipeline_spec = {
  "name": "onedrive_metadata_pipeline",
  "catalog": "main",
  "schema": "ingest_destination_schema",
  "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"
              }
            }
          }
        }
      }
    ]
  },
  "channel": "PREVIEW"
}

json_payload = json.dumps(pipeline_spec, indent=2)
create_pipeline(json_payload)

Configurer les options d’ingestion de fichiers​

Le bloc file_ingestion_options contrôle le traitement des fichiers. 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 montrent le fragment file_ingestion_options d’une définition de pipeline. Pour connaître tous les parameters, consultez file_ingestion_options parameters.

Filtres de fichiers​

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

JSON
"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.

JSON
"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:

JSON
"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