Inserire file da SharePoint

Importante

Questa funzionalità è in versione beta. Gli amministratori dell'area di lavoro possono controllare l'accesso a questa funzionalità dalla pagina Anteprime . Consulta Gestisci anteprime Azure Databricks.

:::nota Conformità

Il connettore SharePoint supporta l'uso nelle aree di lavoro con Configurare le impostazioni di sicurezza e conformità avanzate abilitate.

:::

È possibile inserire file strutturati, semistrutturati e non strutturati da Microsoft SharePoint in tabelle Delta. Il connettore SharePoint supporta l'inserimento incrementale di file di SharePoint tramite API batch e di streaming, tra cui il caricatore automatico, spark.read e COPY INTO, tutto con la governance del catalogo Unity.

Scegliere il connettore di SharePoint

Lakeflow Connect offre due connettori di SharePoint complementari. Entrambi accedono ai dati in SharePoint, ma supportano obiettivi distinti.

Considerazione Connettore di SharePoint gestito Connettore SharePoint Standard
Gestione e personalizzazione Connettore completamente gestito.
Connettori semplici e a bassa manutenzione per applicazioni aziendali che inseriscono i dati nelle tabelle Delta e li mantengono sincronizzati con l'origine. Vedi Connettori gestiti in Lakeflow Connect.
Creare pipeline di inserimento personalizzate con pipeline dichiarative SQL, PySpark o Lakeflow Spark usando API batch e di streaming, ad esempio read_files, spark.read, COPY INTO, e Caricatore automatico.
Offre la flessibilità necessaria per eseguire trasformazioni complesse durante l'inserimento, offrendo al tempo stesso una maggiore responsabilità per la gestione e la manutenzione delle pipeline.
Formato di output Tabella di contenuto binario uniforme. Inserisce ogni file in formato binario (un file per riga), insieme ai metadati dei file in
colonne aggiuntive.
Tabelle Delta strutturate. Inserisce file strutturati(ad esempio CSV e Excel) come tabelle Delta. Può essere usato anche per inserire
file non strutturati in formato binario.
Granularità, filtro e selezione Nessuna selezione a livello di sottocartella o di file oggi. Nessun filtro basato su pattern.
Inserisce tutti i file nella raccolta documenti specificata SharePoint.
Granulare e personalizzato.
Selezione basata su URL per l'inserimento da raccolte documenti, sottocartelle o singoli file. Supporta anche il filtro basato su criteri usando l'opzione pathGlobFilter .

Funzionalità principali

Il connettore SharePoint standard offre:

  • Inserimento di file strutturati, semistrutturati e non strutturati
  • Inserimento granulare: inserire un sito specifico, un sito secondario, una raccolta documenti, una cartella o un singolo file
  • Inserimento in batch e streaming utilizzando spark.read, Auto Loader e COPY INTO
  • Inferenza e evoluzione automatica dello schema per formati strutturati e semistrutturati, ad esempio CSV e Excel
  • Proteggere l'archiviazione delle credenziali con una connessione al catalogo Unity
  • Selezione di file con corrispondenza di pattern tramite pathGlobFilter

Requisiti

Per inserire file da SharePoint, è necessario disporre degli elementi seguenti:

  • Un'area di lavoro con il catalogo Unity abilitato.
  • CREATE CONNECTION privilegi per creare una connessione SharePoint o il privilegio appropriato per utilizzare un'esistente in base alla modalità di accesso del cluster:
    • Modalità di accesso dedicato: MANAGE CONNECTION.
    • Modalità di accesso standard: USE CONNECTION.
  • Calcolo che usa Databricks Runtime versione 17.3 LTS o successiva.
  • Configurazione dell'autenticazione OAuth con l'ambito di autorizzazione Sites.Read.All o Sites.Selected.
  • La funzionalità SharePoint Beta è abilitata dalla pagina Previews. Consulta Gestisci anteprime Azure Databricks.
  • Facoltativo: abilitare la funzionalità Excel Beta per l'analisi dei file Excel. Vedere Read Excel files.

Creare la connessione

Creare una connessione al catalogo Unity per archiviare le credenziali di SharePoint. Il processo di configurazione della connessione viene condiviso tra i connettori standard e gestiti SharePoint.

Per istruzioni complete sull'installazione della connessione, incluse le opzioni di autenticazione OAuth, vedere Panoramica della configurazione di inserimento SharePoint.

Leggi i file da SharePoint

Per leggere i file, passare la connessione creata usando l'opzione databricks.connection e un URL che punta alla risorsa SharePoint a cui si vuole accedere. L'URL fornito determina l'ambito dell'acquisizione.

I tipi di percorso seguenti sono supportati in Databricks Runtime 17.3 LTS e versioni successive:

Tipo di percorso Descrizione
Site Copiare l'URL del sito dalla barra degli indirizzi.
https://mytenant.sharepoint.com/sites/test-site
Secondario Copiare l'URL del sito secondario dalla barra degli indirizzi.
https://mytenant.sharepoint.com/sites/test-site/test-subsite
Raccolta documenti Aprire la raccolta dal contenuto del sito e copiare l'URL dalla barra degli indirizzi.
https://mytenant.sharepoint.com/sites/test-site/Shared%20Documents
https://mytenant.sharepoint.com/sites/test-site/custom-drive
Cartella Aprire la cartella dal contenuto del sito e copiare l'URL dalla barra degli indirizzi. In alternativa, aprire il riquadro Details della cartella in SharePoint e fare clic sull'icona di copia accanto a 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
File Selezionare il file, fare clic sul menu di overflow (...) e selezionare Anteprima. Copia l'URL dalla barra degli indirizzi. In alternativa, aprire il riquadro Details del file in SharePoint e fare clic sull'icona di copia accanto a 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.3 e versioni successive aggiunge il supporto per i tipi di percorso seguenti:

Tipo di percorso Descrizione
Tenant Copiare l'URL radice del tenant dalla barra degli indirizzi.
https://mytenant.sharepoint.com
Sito secondario annidato Copiare l'URL del sito secondario dalla barra degli indirizzi.
https://mytenant.sharepoint.com/sites/test-site/subsite/nested-subsite/nested-nested-subsite
Condividi link Selezionare il file o la cartella, fare clic sul menu di overflow (...) e selezionare Copia collegamento. Databricks consiglia di impostare il collegamento di condivisione in modo che non scada mai.
https://mytenant.sharepoint.com/:i:/s/test-site/1A2B3C4D5E6F7G8H9I
Microsoft 365 per il Web (in precedenza Office) Aprire il file in Microsoft 365 per il Web e copiare l'URL dalla barra degli indirizzi.
https://mytenant.sharepoint.com/:x:/r/sites/test-site/_layouts/15/Doc.aspx?sourcedoc=%1A2B...

Esempi

Esistono alcuni modi per leggere i file usando il connettore SharePoint standard.

Stream file di SharePoint con Auto Loader

Il caricatore automatico offre il modo più efficiente per inserire in modo incrementale file strutturati da SharePoint. Rileva automaticamente nuovi file e li elabora man mano che arrivano. Può anche inserire file strutturati e semistrutturati, ad esempio CSV e JSON con inferenza ed evoluzione automatica dello schema. Per informazioni dettagliate sull'utilizzo del caricatore automatico, vedere Modelli di caricamento dei dati comuni.

# 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")
)

Leggere i file di SharePoint utilizzando la lettura batch di Spark

Nell'esempio seguente viene illustrato come inserire file SharePoint in Python usando la funzione 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"))

Read SharePoint file con Spark SQL

Nell'esempio seguente viene illustrato come inserire file SharePoint in SQL usando la funzione con valori di tabella read_files. Per informazioni dettagliate sull'utilizzo read_files , vedere read_files funzione con valori di tabella.

-- 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"
);

Inserimento incrementale con COPY INTO

COPY INTO fornisce il caricamento incrementale idempotente dei file in una tabella Delta. Per informazioni dettagliate sull'utilizzo COPY INTO , vedere Modelli comuni di caricamento dei dati con 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');

Ingerire i file di SharePoint nelle pipeline dichiarative di Lakeflow Spark

Annotazioni

Il connettore SharePoint richiede Databricks Runtime 17.3 o versione successiva. Per usare il connettore, impostare "CHANNEL" = "PREVIEW" nelle impostazioni della pipeline. Per ulteriori informazioni sulle anteprime, consultare il riferimento sulle proprietà della pipeline.

Gli esempi seguenti illustrano come leggere SharePoint file usando il caricatore automatico nelle pipeline dichiarative di Lakeflow Spark.

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"
);

Analizzare i file non strutturati

Quando si inseriscono file non strutturati da SharePoint (ad esempio pdf, documenti Word o file di PowerPoint) usando il connettore SharePoint standard con formato binaryFile, il contenuto del file viene archiviato come dati binari non elaborati. Per preparare questi file per i carichi di lavoro di intelligenza artificiale, ad esempio RAG, ricerca, classificazione o comprensione dei documenti, è possibile analizzare il contenuto binario in un output strutturato e su cui è possibile eseguire query usando ai_parse_document.

L'esempio seguente illustra come analizzare i documenti non strutturati archiviati in una tabella Delta bronze denominata documents, aggiungendo una nuova colonna con contenuto analizzato:

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 colonna contiene testo, tabelle, informazioni sul layout e metadati estratti che possono essere usati direttamente per le pipeline di intelligenza artificiale downstream.

Analisi incrementale con pipeline dichiarative di Lakeflow Spark

È anche possibile usare ai_parse_document nelle pipeline dichiarative di Lakeflow Spark per abilitare l'analisi incrementale. Man mano che i nuovi file vengono trasmessi da SharePoint, vengono analizzati automaticamente come aggiornamenti della pipeline.

Ad esempio, è possibile definire una vista materializzata che analizza continuamente i documenti appena inseriti:

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;

Questo approccio garantisce che:

  • I file SharePoint appena inseriti vengono analizzati automaticamente ogni volta che la vista materializzata viene aggiornata
  • Gli output analizzati rimangono sincronizzati con i dati in ingresso
  • Le pipeline di intelligenza artificiale downstream operano sempre su rappresentazioni di documenti up-to-date

Altre informazioni: vedere ai_parse_document per i formati supportati e le opzioni avanzate.

SharePoint colonna di metadati

Importante

Questa funzionalità è in anteprima privata. Per provarlo, contattare il contatto di Azure Databricks.

La colonna _sharepoint_metadata è una colonna di metadati nascosta che consente di accedere alle proprietà specifiche SharePoint dei file inseriti, originate dalla risorsa driveItem Microsoft Graph. Richiede Databricks Runtime 18.1 o versione successiva ed è disponibile per tutti i formati di file durante la lettura da SharePoint. Per includere la _sharepoint_metadata colonna nel dataframe restituito, è necessario selezionarla in modo esplicito nella query di lettura.

Se l'origine dati contiene una colonna denominata _sharepoint_metadata, la colonna dei metadati SharePoint viene rinominata in __sharepoint_metadata (con un carattere di sottolineatura iniziale aggiuntivo) per deduplicare. Vengono aggiunti caratteri di sottolineatura aggiuntivi fino a quando il nome non è univoco.

È possibile eseguire query sui metadati di file comuni, ad esempio il percorso o le dimensioni del file, usando la _metadata colonna . Per ulteriori informazioni, consultare la colonna metadati del file.

Schema

La _sharepoint_metadata colonna è un oggetto STRUCT contenente i campi seguenti. Tutti i campi possono essere nulli.

Nome Tipo Descrizione Esempio Versione minima di Databricks Runtime
item_id STRING ID driveItem dell'elemento. 01OMQ3MNLH42C5J675CBEI5CRK7SPKQUTZ 18.1
site_id STRING ID del sito SharePoint che contiene l'elemento. mytenant.sharepoint.com,69dc7b12-f92c-498d-9514-596b793a1f77,c6c1db8d-2b8d-48a1-a549-394b63d74725 18.1
drive_id STRING ID dell'unità che contiene l'elemento. b!EnvcaSz5jUmVFFlreTofd43bwcaNK6FIpUk5S2PXRyWTvQraaWQkSpwQEgThHDS- 18.1
drive_type STRING Tipo di unità, ad esempio documentLibrary per le librerie di SharePoint o business per OneDrive for Business. documentLibrary 18.1
parent_id STRING ID dell'elemento drive della cartella padre. 01OMQ3MNN6Y2GOVW7725BZO354PWSELRRZ 18.1
parent_name STRING Nome della cartella padre. Shared Documents 18.1
parent_path STRING Percorso relativo rispetto all'unità della cartella principale. /drives/b!EnvcaSz5.../root: 18.1
web_url STRING URL dell'elemento nel browser su SharePoint. https://mytenant.sharepoint.com/sites/TestSite/_layouts/15/Doc.aspx?sourcedoc=... 18.1
mime_type STRING Tipo MIME dell'elemento. application/vnd.ms-excel 18.1
creato_per_email STRING Messaggio di posta elettronica dell'utente che ha creato l'elemento. alice@example.onmicrosoft.com 18.1
created_by_name STRING Nome visualizzato dell'utente che ha creato l'elemento. Alice Example 18.1
created_timestamp TIMESTAMP Ora di creazione dell'elemento. 2025-12-03 13:33:12 18.1
ultimo_modificato_da_email STRING Indirizzo di posta elettronica dell'utente che ha modificato l'ultimo elemento. alice@example.onmicrosoft.com 18.1
ultima_modifica_da_nome STRING Nome visualizzato dell'utente che ha modificato l'ultimo elemento. Alice Example 18.1
Etag STRING ETag dell'elemento. Cambia quando l'elemento o uno dei relativi metadati cambia. "{D485E667-FDFB-4810-8E8A-2AFC9EA85279},1" 18.1
ctag STRING Tag di modifica dell'elemento. Cambia solo quando il contenuto dell'elemento cambia. "c:{D485E667-FDFB-4810-8E8A-2AFC9EA85279},1" 18.1
descrizione STRING Descrizione dell'elemento, se impostata. Q4 financial report 18.1
additional_metadata VARIANT Qualsiasi altro campo di driveItem restituito da Microsoft Graph ma non estratto sopra. {"shared":{"scope":"users"},...} 18.1

Annotazioni

Il additional_metadata campo viene restituito come VARIANT. Vedere VARIANT tipo.

Esempi

Negli esempi seguenti viene illustrato come includere la _sharepoint_metadata colonna in una query di lettura, selezionare campi specifici dalla colonna ed estrarre i valori dal additional_metadataVARIANT campo.

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"
);

Selezionare campi specifici dallo _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"))

Estrarre valori dal additional_metadataVARIANT campo usando l'operatore :: cast:

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"
);

Limitazioni

Il connettore SharePoint standard presenta le limitazioni seguenti.

  • Nessun inserimento multisito: non è possibile inserire più siti con la stessa query. Per inserire da due siti, è necessario scrivere due query separate.
  • Filtro: è possibile usare l'opzione pathGlobFilter per filtrare i file in base al nome. Il filtro basato sul percorso della cartella non è supportato.
  • Formati non supportati: elenchi di SharePoint e pagine del sito .aspx non sono supportate. Sono supportati solo i file nelle Raccolte Documenti.
  • La scrittura in un server SharePoint non è supportata.
  • Il caricatore cleanSource automatico (eliminazione o archiviazione di file nell'origine dopo l'inserimento) non è supportato.

Passaggi successivi