Inserire file da SharePoint

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

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 da SharePoint usando Spark, specificare la connessione creata nel passaggio precedente usando l'opzione databricks.connection origine dati e specificare l'URL della risorsa SharePoint a cui si vuole accedere. Questo URL può fare riferimento a un file specifico, a una cartella, a una raccolta documenti (unità) o a un intero sito. Gli esempi includono:

• https://mytenant.sharepoint.com/sites/test-site/
• https://mytenant.sharepoint.com/sites/test-site/test-subsite
• https://mytenant.sharepoint.com/sites/test-site/test-drive
• https://mytenant.sharepoint.com/sites/test-site/Shared%20Documents/Forms/AllItems.aspx
• https://mytenant.sharepoint.com/sites/test-site/test-drive/test-folder
• https://mytenant.sharepoint.com/sites/test-site/test-drive/test-folder/test.csv
• https://mytenant.sharepoint.com/sites/test-site/another-subsite/another-drive/test.csv

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

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.

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

• Informazioni su Auto Loader per modelli avanzati di inserimento in streaming
• Esplora COPY INTO per i caricamenti incrementali idempotenti
• Confrontare con i modelli di inserimento dell'archiviazione di oggetti cloud
• Configurare la pianificazione dei lavori per automatizzare i flussi di lavoro di inserimento
• Usare le pipeline dichiarative di Lakeflow Spark per creare pipeline di dati end-to-end con trasformazioni