Ingestování souborů z SharePoint

Důležité

Tato funkce je v beta verzi. Správci pracovního prostoru můžou řídit přístup k této funkci ze stránky Previews . Viz Manage Azure Databricks preview.

:::Poznámka Dodržování předpisů

Konektor SharePoint podporuje použití v pracovních prostorech s povoleným nastavením Konfigurujte rozšířené nastavení zabezpečení a dodržování předpisů.

:::

Do tabulek Delta můžete ingestovat strukturované, částečně strukturované a nestrukturované soubory z Microsoft SharePoint. Konektor SharePoint podporuje přírůstkový příjem souborů SharePoint pomocí dávkových a streamovacích API, včetně Auto Loader, spark.read a COPY INTO, to vše se zásadami správy katalogu Unity.

Choose váš konektor SharePoint

Lakeflow Connect nabízí dva konektory SharePoint. Oba přistupují k datům v SharePoint, ale liší se ve své úrovni správy.

Connector Description
Spravovaný konektor SharePoint Plně spravovaný konektor. Jednoduchý konektor s nízkou údržbou pro podnikové aplikace, který ingestuje data do tabulek Delta a udržuje je synchronizovaný se zdrojem.
Standardní konektor SharePoint Vytvářejte vlastní ingestní kanály pomocí SQL, PySparku nebo kanálů Lakeflow s využitím rozhraní API pro dávkové a streamovací zpracování, jako jsou read_files, spark.read, COPY INTO a Auto Loader. Nabízí flexibilitu při provádění složitých transformací během příjmu dat a poskytuje větší odpovědnost za správu a údržbu kanálů.

Tip

Databricks doporučuje spravovaný konektor SharePoint pro většinu případů použití. Poskytuje plně spravované prostředí s automatickým přírůstkovým příjmem dat, podporou širokého formátu a flexibilním výběrem souborů a složek.

Klíčové funkce

Standardní konektor SharePoint nabízí:

  • Příjem strukturovaných, částečně strukturovaných a nestrukturovaných souborů
  • Granulární zpracování: Zpracování konkrétního webu, dílčího webu, knihovny dokumentů, složky nebo jednoho souboru
  • Příjem dávek a streamování pomocí spark.read, Auto Loader a COPY INTO
  • Automatické odvozování schématu a vývoj strukturovaných a částečně strukturovaných formátů, jako jsou CSV a Excel
  • Zabezpečení úložiště přihlašovacích údajů pomocí připojení katalogu Unity
  • Výběr souborů s porovnáváním vzorů pomocí pathGlobFilter

Požadavky

Pokud chcete ingestovat soubory z SharePoint, musíte mít následující:

  • Pracovní prostor s aktivovaným katalogem Unity.
  • oprávnění k vytvoření připojení SharePoint nebo příslušné oprávnění pro použití existujícího připojení na základě vašeho režimu přístupu ke clusteru :
    • Režim vyhrazeného přístupu: MANAGE CONNECTION.
    • Standardní režim přístupu: USE CONNECTION.
  • Výpočetní prostředky, které používají Databricks Runtime verze 17.3 LTS nebo novější.
  • Ověřování OAuth nastavené s oborem oprávnění Sites.Read.All nebo Sites.Selected.
  • Funkce SharePoint Beta je povolená na stránce Previews. Viz Manage Azure Databricks preview.
  • Volitelné: Povolte funkci Excel Beta pro analýzu souborů Excel. Viz Čtení a streamování Excel souborů.

Vytvoření připojení

Vytvořte připojení katalogu Unity k uložení přihlašovacích údajů SharePoint. Proces nastavení připojení se sdílí mezi standardními i spravovanými konektory SharePoint.

Úplné pokyny k nastavení připojení, včetně možností ověřování OAuth, najdete v tématu Přehled nastavení příjmu dat SharePoint.

Číst soubory z SharePoint

Pokud chcete číst soubory, předejte připojení, které jste vytvořili pomocí možnosti databricks.connection, a adresu URL, která odkazuje na prostředek SharePoint, ke kterému chcete získat přístup. Zadaná adresa URL určuje rozsah příjmu dat.

V Databricks Runtime 17.3 LTS a novějších verzích se podporují následující typy cest:

Typ cesty Description
Site Zkopírujte adresu URL webu z adresního řádku.
https://mytenant.sharepoint.com/sites/test-site
Podstránka Zkopírujte adresu URL podřízeného webu z adresního řádku.
https://mytenant.sharepoint.com/sites/test-site/test-subsite
Knihovna dokumentů Otevřete knihovnu z obsahu webu a zkopírujte adresu URL z adresního řádku.
https://mytenant.sharepoint.com/sites/test-site/Shared%20Documents
https://mytenant.sharepoint.com/sites/test-site/custom-drive
Folder Otevřete složku z obsahu webu a zkopírujte adresu URL z adresního řádku. Případně otevřete podokno složky Details v SharePoint a klikněte na ikonu kopírování vedle 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
Soubor Vyberte soubor, klikněte na nabídku přetečení (...) a vyberte Náhled. Zkopírujte adresu URL z panelu adresy. Případně otevřete podokno Podrobnosti souboru v SharePointu a klikněte na ikonu kopírování vedle Cesta.
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 a novější přidává podporu pro následující typy cest:

Typ cesty Description
Vnořená podstránka Zkopírujte adresu URL podřízeného webu z adresního řádku.
https://mytenant.sharepoint.com/sites/test-site/subsite/nested-subsite/nested-nested-subsite
Sdílet odkaz Vyberte soubor nebo složku, klikněte na ikonu rozbalovací nabídky (...) a vyberte Kopírovat odkaz. Databricks doporučuje nastavit odkaz na sdílenou složku tak, aby nikdy nevyprší platnost.
https://mytenant.sharepoint.com/:i:/s/test-site/1A2B3C4D5E6F7G8H9I
Microsoft 365 pro web (dříve Office) Otevřete soubor v Microsoft 365 webu a zkopírujte adresu URL z adresního řádku.
https://mytenant.sharepoint.com/:x:/r/sites/test-site/_layouts/15/Doc.aspx?sourcedoc=%1A2B...

Databricks Runtime 19 a novější přidává podporu pro následující typy cest:

Typ cesty Description
Tenant Zkopírujte kořenovou adresu URL tenanta z adresního řádku.
https://mytenant.sharepoint.com

Examples

Soubory můžete číst několika způsoby pomocí standardního konektoru SharePoint.

Streamujte soubory SharePoint pomocí Automatického zavaděče

Auto Loader poskytuje nejefektivnější způsob, jak přírůstkově vkládat strukturované soubory ze SharePoint. Automaticky rozpozná nové soubory a zpracuje je při jejich doručení. Může také ingestovat strukturované a částečně strukturované soubory, jako jsou CSV a JSON, s automatickým odvozováním schématu a vývojem. Podrobnosti o použití Auto Loaderu najdete v části Běžné vzorce načítání dat.

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

Soubory SharePoint číst pomocí dávkového čtení ve Sparku

Následující příklad ukazuje, jak ingestovat soubory SharePoint v Python pomocí funkce 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"))

Čtení sharepointových souborů pomocí Spark SQL

Následující příklad ukazuje, jak importovat soubory SharePoint v SQL pomocí funkce read_files table-valued. Podrobnosti o read_files využití najdete v tabulkovéread_files funkci.

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

Přírůstkové ingestování s využitím COPY INTO

COPY INTO poskytuje idempotentní přírůstkové načítání souborů do tabulky Delta. Podrobnosti o využití najdete v COPY INTO tématu Běžné vzory načítání dat pomocí 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');

Ingestování souborů SharePoint v kanálech Lakeflow

Poznámka:

Konektor SharePoint vyžaduje Databricks Runtime 17.3 nebo novější. Pokud chcete konektor použít, nastavte "CHANNEL" = "PREVIEW" v nastavení kanálu. Další informace o náhledech najdete v referenčních informacích o vlastnostech kanálu.

Následující příklady ukazují, jak číst soubory služby SharePoint pomocí Auto Loaderu v kanálech Lakeflow Pipelines.

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

Analýza nestrukturovaných souborů

Při ingestování nestrukturovaných souborů ze SharePoint (například souborů PDF, Word dokumentů nebo souborů PowerPoint) pomocí standardního konektoru SharePoint s formátem binaryFile se obsah souboru uloží jako nezpracovaná binární data. Pokud chcete tyto soubory připravit na úlohy AI, jako je RAG, vyhledávání, klasifikace nebo porozumění dokumentům, můžete binární obsah analyzovat do strukturovaného, dotazovatelného výstupu pomocí ai_parse_document.

Následující příklad ukazuje, jak parsovat nestrukturované dokumenty uložené v bronzové tabulce Delta s názvem documents, přidání nového sloupce s analyzovaným obsahem:

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;

Sloupec parsed_content obsahuje extrahovaný text, tabulky, informace o rozložení a metadata, která je možné použít přímo pro podřízené kanály AI.

Přírůstková analýza pomocí kanálů Lakeflow

Můžete také použít ai_parse_document v pipelinech Lakeflow k umožnění přírůstkového parsování. Když nové soubory přicházejí ze SharePointu, automaticky se zpracovávají při aktualizaci vašeho datového toku.

Můžete například definovat materializované zobrazení, které průběžně parsuje nově ingestované dokumenty:

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;

Tento přístup zajišťuje, že:

  • Nově ingestované SharePoint soubory se analyzují automaticky při každé aktualizaci materializovaného zobrazení.
  • Analyzované výstupy zůstanou synchronizované s příchozími daty
  • Následné AI kanály vždy fungují na aktuálních reprezentacích dokumentů.

Další informace: Podívejte se na ai_parse_document pro podporované formáty a rozšířené možnosti.

sloupec metadat SharePoint

Důležité

Tato funkce je ve verzi Private Preview. Pokud ji chcete vyzkoušet, obraťte se na svou kontaktní osobu pro Azure Databricks.

Sloupec _sharepoint_metadata je skrytý sloupec metadat, který poskytuje přístup k vlastnostem specifickým pro SharePoint zpracovaných souborů, pocházejících ze zdroje Microsoft Graph prostředku driveItem. Vyžaduje Databricks Runtime 18 nebo novější a je k dispozici pro všechny formáty souborů při čtení z SharePoint. Pokud chcete do vráceného datového rámce zahrnout _sharepoint_metadata sloupec, musíte ho explicitně vybrat v dotazu pro čtení.

Pokud zdroj dat obsahuje sloupec s názvem _sharepoint_metadata, sloupec metadat SharePoint se přejmenuje na __sharepoint_metadata (s nadbytečným úvodním podtržítkem) pro odstranění duplicit. Další podtržítka se přidají, dokud nebude název jedinečný.

Běžná metadata souborů, jako je cesta k souboru nebo velikost, lze dotazovat pomocí sloupce _metadata. Další informace najdete ve sloupci Metadata souboru.

Schéma

Sloupec _sharepoint_metadata je STRUCT obsahující následující pole. Všechna pole mají hodnotu null.

Název Typ Description Příklad
item_id STRING ID položky driveItem 01OMQ3MNLH42C5J675CBEI5CRK7SPKQUTZ
site_id STRING ID webu SharePoint, který obsahuje položku. mytenant.sharepoint.com,69dc7b12-f92c-498d-9514-596b793a1f77,c6c1db8d-2b8d-48a1-a549-394b63d74725
drive_id STRING ID disku, který obsahuje položku. b!EnvcaSz5jUmVFFlreTofd43bwcaNK6FIpUk5S2PXRyWTvQraaWQkSpwQEgThHDS-
drive_type STRING Typ jednotky, například documentLibrary pro knihovny SharePoint nebo business pro OneDrive pro firmy. documentLibrary
parent_id STRING ID driveItem nadřazené složky. 01OMQ3MNN6Y2GOVW7725BZO354PWSELRRZ
parent_name STRING Název nadřazené složky. Shared Documents
parent_path STRING Relativní cesta jednotky nadřazené složky. /drives/b!EnvcaSz5.../root:
web_url STRING Adresa URL prohlížeče položky v SharePoint. https://mytenant.sharepoint.com/sites/TestSite/_layouts/15/Doc.aspx?sourcedoc=...
Typ MIME STRING Typ MIME položky. application/vnd.ms-excel
created_by_email STRING E-mail uživatele, který položku vytvořil. alice@example.onmicrosoft.com
created_by_name STRING Zobrazované jméno uživatele, který položku vytvořil. Alice Example
created_timestamp TIMESTAMP Čas vytvoření položky 2025-12-03 13:33:12
e_mail_osoby_ktera_provedla_posledni_zmenu STRING E-mail uživatele, který položku naposledy upravil alice@example.onmicrosoft.com
jméno uživatele, který provedl poslední úpravu STRING Zobrazované jméno uživatele, který položku naposledy upravil. Alice Example
etag STRING ETag položky. Změní se, když se položka nebo některá z jejích metadat změní. "{D485E667-FDFB-4810-8E8A-2AFC9EA85279},1"
ctag STRING Značka změny položky. Změní se jenom v případech, kdy se obsah položky změní. "c:{D485E667-FDFB-4810-8E8A-2AFC9EA85279},1"
description STRING Popis položky, pokud je nastaven. Q4 financial report
additional_metadata VARIANT Všechna ostatní pole driveItem vrácená Microsoft Graph, ale neextrahovaná výše. {"shared":{"scope":"users"},...}

Poznámka:

Pole additional_metadata se vrátí jako VARIANT. Viz typ VARIANT.

Příklad

Následující příklady ukazují, jak zahrnout _sharepoint_metadata sloupec do dotazu pro čtení, vybrat konkrétní pole ze sloupce a extrahovat hodnoty z additional_metadataVARIANT pole.

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

Vyberte konkrétní pole ze _sharepoint_metadata struktury:

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

Extrahujte hodnoty z polí additional_metadataVARIANT pomocí operátoru přetypování ::.

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

Omezení

Standardní konektor SharePoint má následující omezení.

  • Nelze ingestovat více webů se stejným dotazem. Pokud chcete ingestovat ze dvou lokalit, musíte napsat dva samostatné dotazy.
  • Tuto možnost můžete použít pathGlobFilter k filtrování souborů podle názvu. Filtrování na základě cesty ke složce není podporováno.
  • SharePoint Seznamy a stránky webu .aspx nejsou podporovány. Podporují se jenom soubory v knihovnách dokumentů.
  • Zpětný zápis na server SharePoint se nepodporuje.
  • Automatický zavaděč cleanSource (odstranění nebo archivace souborů ve zdroji po příjmu dat) se nepodporuje.

Další kroky