Ingérer des fichiers à partir de SharePoint

Important

Cette fonctionnalité est en version bêta. Les administrateurs d’espace de travail peuvent contrôler l’accès à cette fonctionnalité à partir de la page Aperçus . Consultez les aperçus Manage Azure Databricks.

:::note Conformité

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

:::

Vous pouvez ingérer des fichiers structurés, semi-structurés et non structurés de Microsoft SharePoint dans des tables Delta. Le connecteur SharePoint prend en charge l’ingestion incrémentielle de fichiers SharePoint à l’aide d’API de traitement par lots et de diffusion en continu, notamment le chargeur automatique, spark.read et COPY INTO, tous avec la gouvernance du catalogue Unity.

Choose votre connecteur SharePoint

Lakeflow Connect offre deux connecteurs SharePoint. Ils accèdent tous deux aux données dans SharePoint, mais diffèrent dans leur niveau de gestion.

Connecteur Description
Connecteur SharePoint managé Connecteur complètement managé. Connecteur simple et à faible maintenance pour les applications d’entreprise qui ingère des données dans des tables Delta et les synchronise avec la source.
Connecteur SharePoint standard Créez des pipelines d’ingestion personnalisés avec des pipelines SQL, PySpark ou Lakeflow à l’aide d’API de traitement par lots et de diffusion en continu telles que read_files, spark.read, COPY INTOet le chargeur automatique. Offre la possibilité d’effectuer des transformations complexes pendant l’ingestion, tout en vous donnant une plus grande responsabilité pour la gestion et la maintenance de vos pipelines.

Tip

Databricks recommande le connecteur de SharePoint managé pour la plupart des cas d’usage. Il offre une expérience entièrement managée avec l’ingestion incrémentielle automatique, la prise en charge de format large et la sélection flexible de fichiers et de dossiers.

Fonctionnalités clés

Le connecteur SharePoint standard offre les fonctionnalités suivantes :

  • Ingestion de fichiers structurés, semi-structurés et non structurés
  • Ingestion granulaire : ingérer un site spécifique, un sous-site, une bibliothèque de documents, un dossier ou un seul fichier
  • Ingestion par lots et en flux à l'aide de spark.read, du chargeur automatique, et de COPY INTO
  • Inférence de schéma automatique et évolution pour les formats structurés et semi-structurés tels que CSV et Excel
  • Sécuriser le stockage des informations d’identification avec une connexion de catalogue Unity
  • Sélection de fichiers avec correspondance de modèle à l’aide de pathGlobFilter

Spécifications

Pour ingérer des fichiers à partir de SharePoint, vous devez disposer des éléments suivants :

  • Un espace de travail avec le catalogue Unity activé.
  • CREATE CONNECTION privilèges pour créer une connexion SharePoint, ou le privilège approprié pour utiliser une connexion existante en fonction de votre mode d'accès au cluster :
    • Mode d’accès dédié : MANAGE CONNECTION.
    • Mode d’accès standard : USE CONNECTION.
  • Calcul qui utilise Databricks Runtime version 17.3 LTS ou ultérieure.
  • L'authentification OAuth configurée avec l'étendue d'autorisation Sites.Read.All ou Sites.Selected.
  • La fonctionnalité bêta SharePoint est activée à partir de la page Previews. Consultez les aperçus Manage Azure Databricks.
  • Facultatif : activez la fonctionnalité Excel bêta pour l’analyse des fichiers Excel. Voir Lire et diffuser des fichiers Excel en continu.

Créer la connexion

Créez une connexion de catalogue Unity pour stocker vos informations d’identification SharePoint. Le processus d’installation de la connexion est partagé entre les connecteurs de SharePoint standard et gérés.

Pour obtenir des instructions complètes sur la configuration de la connexion, notamment les options d’authentification OAuth, consultez Aperçu de la configuration de l’ingestion de SharePoint.

Lire les fichiers de SharePoint

Pour lire des fichiers, transmettez la connexion que vous avez créée à l’aide de l’option databricks.connection et d’une URL qui pointe vers la ressource SharePoint auquel vous souhaitez accéder. L’URL que vous fournissez détermine l’étendue de l’ingestion.

Les types de chemins suivants sont pris en charge sur Databricks Runtime 17.3 LTS et versions ultérieures :

Type de chemin d’accès Description
Site Copiez l’URL du site à partir de la barre d’adresses.
https://mytenant.sharepoint.com/sites/test-site
Sous-site Copiez l’URL du sous-site à partir de la barre d’adresses.
https://mytenant.sharepoint.com/sites/test-site/test-subsite
Bibliothèque de documents Ouvrez la bibliothèque à partir du contenu du site et copiez l’URL à partir de la barre d’adresses.
https://mytenant.sharepoint.com/sites/test-site/Shared%20Documents
https://mytenant.sharepoint.com/sites/test-site/custom-drive
Dossier Ouvrez le dossier à partir du contenu du site et copiez l’URL à partir de la barre d’adresses. Vous pouvez également ouvrir le volet Details du dossier dans SharePoint et cliquer sur l'icône de copie en regard de Path.
https://mytenant.sharepoint.com/sites/test-site/Shared%20Documents/Forms/AllItems.aspx?id=%2Fsites...
https://mytenant.sharepoint.com/sites/test-site/custom-drive/test-folder
Fichier Sélectionnez le fichier, cliquez sur le menu dépassement de capacité (...), puis sélectionnez Aperçu. Copiez l’URL de la barre d’adresse. Vous pouvez également ouvrir le volet Details du fichier dans SharePoint et cliquer sur l'icône de copie en regard de Path.
https://mytenant.sharepoint.com/sites/test-site/Shared%20Documents/Forms/AllItems.aspx?viewid=1a2b3c...
https://mytenant.sharepoint.com/sites/test-site/custom-drive/test-folder/test.csv

Databricks Runtime 18 LTS et versions ultérieures ajoute la prise en charge des types de chemins suivants :

Type de chemin d’accès Description
Sous-site imbriqué Copiez l’URL du sous-site à partir de la barre d’adresses.
https://mytenant.sharepoint.com/sites/test-site/subsite/nested-subsite/nested-nested-subsite
Partager le lien Sélectionnez le fichier ou le dossier, cliquez sur le menu dépassement de capacité (...), puis sélectionnez Copier le lien. Databricks recommande de définir le lien de partage pour ne jamais expirer.
https://mytenant.sharepoint.com/:i:/s/test-site/1A2B3C4D5E6F7G8H9I
Microsoft 365 pour le web (anciennement Office) Ouvrez le fichier dans Microsoft 365 pour le web et copiez l’URL à partir de la barre d’adresses.
https://mytenant.sharepoint.com/:x:/r/sites/test-site/_layouts/15/Doc.aspx?sourcedoc=%1A2B...

Databricks Runtime 19 et versions ultérieures ajoute la prise en charge des types de chemins suivants :

Type de chemin d’accès Description
Locataire Copiez l’URL racine du locataire à partir de la barre d’adresses.
https://mytenant.sharepoint.com

Examples

Il existe plusieurs façons de lire des fichiers à l’aide du connecteur SharePoint standard.

Diffusez des fichiers SharePoint à l’aide d’Auto Loader

Le chargeur automatique offre le moyen le plus efficace d’ingérer de manière incrémentielle des fichiers structurés à partir de SharePoint. 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_sharepoint_conn")
    .option("cloudFiles.schemaLocation", <path to a schema location>)
    .option("pathGlobFilter", "*.pdf")
    .load("https://mytenant.sharepoint.com/sites/Marketing/Shared%20Documents")
)

# Incrementally ingest CSV files with automatic schema inference and evolution
df = (spark.readStream.format("cloudFiles")
    .option("cloudFiles.format", "csv")
    .option("databricks.connection", "my_sharepoint_conn")
    .option("pathGlobFilter", "*.csv")
    .option("inferColumnTypes", True)
    .option("header", True)
    .load("https://mytenant.sharepoint.com/sites/Engineering/Data/IoT_Logs")
)

Lire les fichiers SharePoint à l'aide de la lecture en lots Spark

L’exemple suivant montre comment ingérer des fichiers SharePoint dans Python à l’aide de la fonction spark.read.

# Read unstructured data as binary files
df = (spark.read
        .format("binaryFile")
        .option("databricks.connection", "my_sharepoint_conn")
        .option("recursiveFileLookup", True)
        .option("pathGlobFilter", "*.pdf") # optional. Example: only ingest PDFs
        .load("https://mytenant.sharepoint.com/sites/Marketing/Shared%20Documents"))

# 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_sharepoint_conn")
        .option("pathGlobFilter", "*.csv")
        .option("recursiveFileLookup", True)
        .option("inferSchema", True)
        .option("header", True)
        .load("https://mytenant.sharepoint.com/sites/Engineering/Data/IoT_Logs"))

# Read a specific Excel file from SharePoint, infer the schema, and load the data into a DataFrame
df = (spark.read
        .format("excel")
        .option("databricks.connection", "my_sharepoint_conn")
        .option("headerRows", 1)                   # optional
        .option("dataAddress", "Sheet1!A1:M20")  # optional
        .load("https://mytenant.sharepoint.com/sites/Finance/Shared%20Documents/Monthly/Report-Oct.xlsx"))

Lire les fichiers SharePoint à l’aide de Spark SQL.

L’exemple suivant montre comment ingérer des fichiers SharePoint dans SQL à l’aide de la fonction table read_files. Pour plus d’informations sur l’utilisation de read_files, consultez la read_files fonction valeur de table.

-- Read pdf files
CREATE TABLE my_table AS
SELECT * FROM read_files(
  "https://mytenant.sharepoint.com/sites/Marketing/Shared%20Documents",
  `databricks.connection` => "my_sharepoint_conn",
  format => "binaryFile",
  pathGlobFilter => "*.pdf", -- optional. Example: only ingest PDFs
  schemaEvolutionMode => "none"
);

-- Read a specific Excel sheet and range
CREATE TABLE my_sheet_table AS
SELECT * FROM read_files(
  "https://mytenant.sharepoint.com/sites/Finance/Shared%20Documents/Monthly/Report-Oct.xlsx",
  `databricks.connection` => "my_sharepoint_conn",
  format => "excel",
  headerRows => 1,  -- optional
  dataAddress => "Sheet1!A2:D10", -- optional
  schemaEvolutionMode => "none"
);

Ingestion incrémentielle avec COPY INTO

COPY INTO fournit un chargement incrémentiel idempotent de fichiers dans une table Delta. Pour plus d'informations sur l'utilisation de COPY INTO, consultez Modèles de chargement de données courants à l'aide de COPY INTO.

CREATE TABLE IF NOT EXISTS sharepoint_pdf_table;
CREATE TABLE IF NOT EXISTS sharepoint_csv_table;
CREATE TABLE IF NOT EXISTS sharepoint_excel_table;

# Incrementally ingest new PDF files
COPY INTO sharepoint_pdf_table
  FROM "https://mytenant.sharepoint.com/sites/Marketing/Shared%20Documents"
  FILEFORMAT = BINARYFILE
  PATTERN = '*.pdf'
  FORMAT_OPTIONS ('databricks.connection' = 'my_sharepoint_conn')
  COPY_OPTIONS ('mergeSchema' = 'true');

# Incrementally ingest CSV files with automatic schema inference and evolution
COPY INTO sharepoint_csv_table
  FROM "https://mytenant.sharepoint.com/sites/Engineering/Data/IoT_Logs"
  FILEFORMAT = CSV
  PATTERN = '*.csv'
  FORMAT_OPTIONS ('databricks.connection' = 'my_sharepoint_conn', 'header' = 'true', 'inferSchema' = 'true')
  COPY_OPTIONS ('mergeSchema' = 'true');

# Ingest a single Excel file
COPY INTO sharepoint_excel_table
  FROM "https://mytenant.sharepoint.com/sites/Finance/Shared%20Documents/Monthly/Report-Oct.xlsx"
  FILEFORMAT = EXCEL
  FORMAT_OPTIONS ('databricks.connection' = 'my_sharepoint_conn', 'headerRows' = '1')
  COPY_OPTIONS ('mergeSchema' = 'true');

Ingérer des fichiers SharePoint dans des pipelines Lakeflow

Note

Le connecteur SharePoint nécessite Databricks Runtime 17.3 ou version ultérieure. Pour utiliser le connecteur, définissez "CHANNEL" = "PREVIEW" dans les paramètres de votre pipeline. Pour plus d’informations sur les préversions, consultez Référence des propriétés de pipeline.

Les exemples suivants montrent comment lire des fichiers SharePoint à l’aide du chargeur automatique dans des pipelines Lakeflow.

Python

from pyspark import pipelines as dp

# Incrementally ingest new PDF files
@dp.table
def sharepoint_pdf_table():
  return (spark.readStream.format("cloudFiles")
    .option("cloudFiles.format", "binaryFile")
    .option("databricks.connection", "my_sharepoint_conn")
    .option("pathGlobFilter", "*.pdf")
    .load("https://mytenant.sharepoint.com/sites/Marketing/Shared%20Documents")
  )

# Incrementally ingest CSV files with automatic schema inference and evolution
@dp.table
def sharepoint_csv_table():
  return (spark.readStream.format("cloudFiles")
      .option("cloudFiles.format", "csv")
      .option("databricks.connection", "my_sharepoint_conn")
      .option("pathGlobFilter", "*.csv")
      .option("inferColumnTypes", True)
      .option("header", True)
      .load("https://mytenant.sharepoint.com/sites/Engineering/Data/IoT_Logs")
  )

# Read a specific Excel file from SharePoint in a materialized view
@dp.table
def sharepoint_excel_table():
  return (spark.read.format("excel")
    .option("databricks.connection", "my_sharepoint_conn")
    .option("headerRows", 1)                   # optional
    .option("inferColumnTypes", True)            # optional
    .option("dataAddress", "Sheet1!A1:M20")  # optional
    .load("https://mytenant.sharepoint.com/sites/Finance/Shared%20Documents/Monthly/Report-Oct.xlsx")

SQL

-- Incrementally ingest new PDF files
CREATE OR REFRESH STREAMING TABLE sharepoint_pdf_table
AS SELECT * FROM STREAM read_files(
  "https://mytenant.sharepoint.com/sites/Marketing/Shared%20Documents",
  format => "binaryFile",
  `databricks.connection` => "my_sharepoint_conn",
  pathGlobFilter => "*.pdf");

-- Incrementally ingest CSV files with automatic schema inference and evolution
CREATE OR REFRESH STREAMING TABLE sharepoint_csv_table
AS SELECT * FROM STREAM read_files(
  "https://mytenant.sharepoint.com/sites/Engineering/Data/IoT_Logs",
  format => "csv",
  `databricks.connection` => "my_sharepoint_conn",
  pathGlobFilter => "*.csv",
  "header", "true");

-- Read a specific Excel file from SharePoint in a materialized view
CREATE OR REFRESH MATERIALIZED VIEW sharepoint_excel_table
AS SELECT * FROM read_files(
  "https://mytenant.sharepoint.com/sites/Finance/Shared%20Documents/Monthly/Report-Oct.xlsx",
  `databricks.connection` => "my_sharepoint_conn",
  format => "excel",
  headerRows => 1,  -- optional
  dataAddress => "Sheet1!A2:D10", -- optional
  `cloudFiles.schemaEvolutionMode` => "none"
);

Analyser des fichiers non structurés

Lors de l’ingestion de fichiers non structurés à partir de SharePoint (par exemple, des fichiers PDF, des documents Word ou des fichiers PowerPoint) à l’aide du connecteur standard SharePoint au format binaryFile, 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 * FROM read_files(
  "https://mytenant.sharepoint.com/sites/Marketing/Shared%20Documents",
  `databricks.connection` => "my_sharepoint_conn",
  format => "binaryFile",
  pathGlobFilter => "*.{pdf,docx}",
  schemaEvolutionMode => "none"
);
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 syntaxique incrémentielle avec les pipelines Lakeflow

Vous pouvez également utiliser ai_parse_document dans les pipelines Lakeflow pour activer l’analyse incrémentielle. À mesure que les nouveaux fichiers sont transmis à partir de SharePoint, ils sont automatiquement analysés en tant que mises à jour de votre pipeline.

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 sharepoint_documents_table
AS SELECT * FROM STREAM read_files(
  "https://mytenant.sharepoint.com/sites/Marketing/Shared%20Documents",
  format => "binaryFile",
  `databricks.connection` => "my_sharepoint_conn",
  pathGlobFilter => "*.{pdf,docx}");

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

Cette approche garantit que :

  • Les fichiers SharePoint 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

En savoir plus : consultez ai_parse_document pour connaître les formats pris en charge et les options avancées.

colonne de métadonnées SharePoint

Important

Cette fonctionnalité est en préversion privée. Pour l’essayer, contactez votre Azure Databricks contact.

La colonne _sharepoint_metadata est une colonne de métadonnées masquée qui fournit l’accès aux propriétés spécifiques à SharePoint des fichiers ingérés, provenant de la ressource Microsoft Graph driveItem. Il nécessite Databricks Runtime 18 LTS ou versions ultérieures et est disponible pour tous les formats de fichier lors de la lecture à partir de SharePoint. Pour inclure la _sharepoint_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 _sharepoint_metadata, la colonne de métadonnées SharePoint est renommée __sharepoint_metadata (avec un trait de soulignement 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 _sharepoint_metadata est une STRUCT contenant les champs suivants. Tous les champs sont nullables.

Nom Catégorie Description Example
item_id STRING ID driveItem de l’élément. 01OMQ3MNLH42C5J675CBEI5CRK7SPKQUTZ
site_id STRING ID du site SharePoint qui contient l’élément. mytenant.sharepoint.com,69dc7b12-f92c-498d-9514-596b793a1f77,c6c1db8d-2b8d-48a1-a549-394b63d74725
drive_id STRING ID du lecteur qui contient l’élément. b!EnvcaSz5jUmVFFlreTofd43bwcaNK6FIpUk5S2PXRyWTvQraaWQkSpwQEgThHDS-
drive_type STRING Type de lecteur, par exemple documentLibrary pour les bibliothèques SharePoint ou business pour OneDrive Entreprise. documentLibrary
parent_id STRING L'ID du driveItem du dossier parent. 01OMQ3MNN6Y2GOVW7725BZO354PWSELRRZ
parent_name STRING Nom du dossier parent. Shared Documents
parent_path STRING Chemin d’accès du dossier parent, relatif au lecteur. /drives/b!EnvcaSz5.../root:
web_url STRING URL du navigateur de l’élément sur SharePoint. https://mytenant.sharepoint.com/sites/TestSite/_layouts/15/Doc.aspx?sourcedoc=...
mime_type STRING Type MIME de l’élément. application/vnd.ms-excel
créé_par_e-mail STRING E-mail de l’utilisateur qui a créé l’élément. alice@example.onmicrosoft.com
created_by_name STRING Nom complet de l’utilisateur qui a créé l’élément. Alice Example
horodatage_de_création TIMESTAMP Heure de création de l’élément. 2025-12-03 13:33:12
last_modified_by_email STRING E-mail de l’utilisateur qui a modifié l’élément pour la dernière fois. alice@example.onmicrosoft.com
last_modified_by_name STRING Nom complet de l’utilisateur qui a modifié l’élément pour la dernière fois. Alice Example
etag STRING ETag de l’élément. Change lorsque l’élément ou l’une de ses métadonnées change. "{D485E667-FDFB-4810-8E8A-2AFC9EA85279},1"
ctag STRING Balise de modification de l’élément. Change uniquement lorsque le contenu de l’élément change. "c:{D485E667-FDFB-4810-8E8A-2AFC9EA85279},1"
description STRING Description de l’élément, si elle est définie. Q4 financial report
métadonnées_supplémentaires VARIANT Tous les autres champs driveItem retournés par Microsoft Graph mais pas extraits ci-dessus. {"shared":{"scope":"users"},...}

Note

Le additional_metadata champ est retourné en tant que VARIANT. Consultez VARIANT type.

Exemples

Les exemples suivants montrent comment inclure la _sharepoint_metadata colonne dans une requête de lecture, sélectionner des champs spécifiques dans la colonne et extraire des valeurs du additional_metadataVARIANT champ.

Python

df = (spark.read
        .format("binaryFile")
        .option("databricks.connection", "my_sharepoint_conn")
        .load("https://mytenant.sharepoint.com/sites/Marketing/Shared%20Documents")
        .select("*", "_metadata", "_sharepoint_metadata"))

SQL

SELECT *, _sharepoint_metadata
FROM read_files(
  "https://mytenant.sharepoint.com/sites/Marketing/Shared%20Documents",
  `databricks.connection` => "my_sharepoint_conn",
  format => "binaryFile"
);

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

df = (spark.read
        .format("binaryFile")
        .option("databricks.connection", "my_sharepoint_conn")
        .load("https://mytenant.sharepoint.com/sites/Marketing/Shared%20Documents")
        .select("_sharepoint_metadata.item_id", "_sharepoint_metadata.etag"))

Extrayez des valeurs du champ additional_metadataVARIANT en utilisant l’opérateur de conversion ::.

SELECT
  *,
  _sharepoint_metadata.additional_metadata:shared:scope::STRING AS shared_scope
FROM read_files(
  "https://mytenant.sharepoint.com/sites/Marketing/Shared%20Documents",
  `databricks.connection` => "my_sharepoint_conn",
  format => "binaryFile"
);

Limites

Le connecteur SharePoint standard présente les limitations suivantes.

  • Vous ne pouvez pas ingérer plusieurs sites avec la même requête. Pour ingérer à partir de deux sites, vous devez écrire deux requêtes distinctes.
  • Vous pouvez utiliser l’option pathGlobFilter pour filtrer les fichiers par nom. Le filtrage basé sur le chemin d’accès au dossier n’est pas pris en charge.
  • SharePoint Les listes et les pages de site .aspx ne sont pas prises en charge. Seuls les fichiers des bibliothèques de documents sont pris en charge.
  • La réécriture vers un serveur SharePoint n’est pas prise en charge.
  • Le chargeur cleanSource automatique (suppression ou archivage de fichiers à la source après l’ingestion) n’est pas pris en charge.

Étapes suivantes