Ingerir ficheiros do SharePoint

:::nota Conformidade

O conector SharePoint suporta a utilização em espaços de trabalho com o Configurar definições melhoradas de segurança e conformidade ativadas.

:::

Podes ingerir ficheiros estruturados, semi-estruturados e não estruturados de Microsoft SharePoint para tabelas Delta. O conector SharePoint suporta a ingestão incremental de ficheiros SharePoint usando APIs em lote e streaming, incluindo Auto Loader, spark.read e COPY INTO, todos com governação do Unity Catalog.

Escolha o seu conector SharePoint

O Lakeflow Connect oferece dois conectores SharePoint. Ambos acedem a dados no SharePoint, mas diferem no nível de gestão.

Principais características

O conector padrão do SharePoint oferece:

• Ingestão de ficheiros estruturados, semi-estruturados e não estruturados
• Ingestão granular: Ingerir um site específico, um sub-site, uma biblioteca de documentos, uma pasta ou um único ficheiro
• Ingestão de páginas do site SharePoint (.aspx) em Databricks Runtime 19 e superiores. Consulte Importar páginas do site SharePoint.
• Ingestão em lote e streaming usando spark.read, Auto Loader, e COPY INTO
• Inferência e evolução automática de esquemas para formatos estruturados e semi-estruturados, como CSV e Excel
• Armazenamento seguro de credenciais com uma ligação ao Unity Catalog
• Seleção de ficheiros com correspondência de padrões usando pathGlobFilter

Requerimentos

Para ingerir ficheiros do SharePoint, deve ter o seguinte:

• Um espaço de trabalho com o Unity Catalog ativado.
• CREATE CONNECTION privilégios para criar uma ligação SharePoint, ou o privilégio apropriado para usar uma existente com base no seu modo de acesso cluster:
  • Modo de Acesso Dedicado: MANAGE CONNECTION.
  • Modo de Acesso Padrão: USE CONNECTION.
• Compute que utiliza Databricks Runtime versão 17.3 LTS ou superior.
• Autenticação OAuth configurada com o âmbito de permissão Sites.Read.All ou Sites.Selected.
• Opcional: Ativa a funcionalidade Excel Beta para analisar ficheiros Excel. Veja Ler e transmitir ficheiros Excel.

Criar a ligação

Crie uma ligação ao Catálogo Unity para guardar as suas credenciais SharePoint. O processo de configuração da ligação é partilhado entre os conectores SharePoint padrão e geridos.

Para instruções completas de configuração da ligação, incluindo opções de autenticação OAuth, veja Visão geral da configuração de SharePoint ingestão.

Ler ficheiros de SharePoint

Para ler ficheiros, passa a ligação que criaste usando a opção databricks.connection e uma URL que aponte para o recurso SharePoint que queres aceder. O URL que forneces determina o âmbito da ingestão.

Os seguintes tipos de caminho são suportados no Databricks Runtime 17.3 LTS e superiores:

O Databricks Runtime 18 LTS e superiores adiciona suporte para os seguintes tipos de caminhos:

O Databricks Runtime 19 e superiores adiciona suporte para os seguintes tipos de caminho:

Examples

Existem algumas formas de ler ficheiros usando o conector SharePoint padrão.

Stream SharePoint ficheiros usando o Auto Loader

O Auto Loader oferece a forma mais eficiente de ingerir de forma incremental ficheiros estruturados do SharePoint. Deteta automaticamente novos ficheiros e processa-os assim que chegam. Também pode ingerir ficheiros estruturados e semi-estruturados, como CSV e JSON, com inferência e evolução automática de esquemas. Para obter detalhes sobre o uso do Auto Loader, consulte Padrões comuns de carregamento de dados.

# 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-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("cloudFiles.schemaLocation", "<path-to-schema-location>")
    .option("pathGlobFilter", "*.csv")
    .option("cloudFiles.inferColumnTypes", True)
    .option("header", True)
    .load("https://mytenant.sharepoint.com/sites/Engineering/Data/IoT_Logs")
)

Read SharePoint ficheiros usando leitura em lote do Spark

O exemplo seguinte mostra como ingerir ficheiros SharePoint em Python usando a função spark.read. Defina a opção recursiveFileLookup como true para ler ficheiros em estruturas aninhadas, como bibliotecas de documentos de um site, pastas de uma biblioteca de documentos ou subsites de um site.

# 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 ficheiros usando Spark SQL

O exemplo seguinte mostra como ingerir ficheiros de SharePoint em SQL usando a função de valores de tabela read_files. Para detalhes do uso de read_files, veja read_files função com valores de tabela.

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

Ingestão incremental com COPY INTO

COPY INTO fornece carregamento incremental idempotente de ficheiros numa tabela Delta. Para mais detalhes sobre COPY INTO uso, consulte Padrões comuns de carregamento de dados usando 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');

Ingir ficheiros SharePoint em pipelines Lakeflow

Os exemplos seguintes mostram como ler ficheiros SharePoint usando o Auto Loader nos 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("cloudFiles.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"
);

Analisar ficheiros não estruturados

Ao ingerir ficheiros não estruturados de SharePoint (como PDFs, documentos Word ou ficheiros PowerPoint) usando o conector SharePoint padrão com formato binaryFile, o conteúdo do ficheiro é armazenado como dados binários brutos. Para preparar estes ficheiros para cargas de trabalho de IA — como RAG, pesquisa, classificação ou compreensão de documentos — pode analisar o conteúdo binário em saída estruturada e consultável usando ai_parse_document.

O exemplo seguinte mostra como analisar documentos não estruturados armazenados numa tabela Delta bronze chamada documents, adicionando uma nova coluna com conteúdo analisado:

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, map('version', '2.0')) AS parsed_content
FROM documents;

A parsed_content coluna contém texto extraído, tabelas, informações de layout e metadados que podem ser usados diretamente em fluxos de IA subsequentes.

Análise sintática incremental com pipelines Lakeflow

Também podes usar ai_parse_document dentro dos pipelines Lakeflow para permitir análise sintática incremental. À medida que novos ficheiros entram do SharePoint, são automaticamente analisados à medida que o seu pipeline é atualizado.

Por exemplo, podes definir uma tabela de streaming bronze que ingere os ficheiros binários brutos, depois uma segunda tabela de streaming que coloca o conteúdo analisado numa nova coluna:

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 STREAMING TABLE documents_parsed
AS SELECT
  *,
  ai_parse_document(content, map('version', '2.0')) AS parsed_content
FROM STREAM sharepoint_documents_table;

Esta abordagem garante que:

• Os ficheiros SharePoint recém-ingeridos são analisados automaticamente sempre que o pipeline atualiza.
• As saídas analisadas mantêm-se sincronizadas com os dados recebidos.
• As cadeias de processamento de IA a jusante operam sempre com representações dos documentos atualizadas.

Consulte a ai_parse_document função para os formatos suportados e opções avançadas, incluindo a opção version que fixa o esquema de saída.

Coluna de metadados do SharePoint

A coluna _sharepoint_metadata é uma coluna oculta de metadados que dá acesso a propriedades específicas de SharePoint dos ficheiros ingeridos, proveniente do recurso driveItem do Microsoft Graph. Requer o Databricks Runtime 18 LTS ou posterior e está disponível para todos os formatos de ficheiro na leitura a partir do SharePoint. Para incluir a _sharepoint_metadata coluna no DataFrame devolvido, deve selecioná-la explicitamente na consulta de leitura.

Se a fonte de dados contiver uma coluna chamada _sharepoint_metadata, a coluna de metadados SharePoint é renomeada para __sharepoint_metadata (com um sublinhado inicial extra) para desduplicar. São adicionados sublinhados adicionais até que o nome seja único.

Metadados comuns de ficheiros, como o caminho ou o tamanho do ficheiro, podem ser consultados usando a _metadata coluna. Para obter mais informações, consulte Coluna de metadados de arquivo.

Esquema

A coluna _sharepoint_metadata é um STRUCT que contém os seguintes campos. Todos os campos são anuláveis.

Exemplos

Os exemplos seguintes mostram como incluir a _sharepoint_metadata coluna numa consulta de leitura, selecionar campos específicos da coluna e extrair valores do 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"
);

Selecione campos específicos da _sharepoint_metadata estrutura:

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

Extrair valores do campo additional_metadataVARIANT usando o operador de conversão ::.

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

Importar páginas do site do SharePoint

O SharePoint armazena as Páginas do Site como ficheiros .aspx na biblioteca Páginas do Site de um site, separados das suas bibliotecas de documentos. A ingestão de páginas do site requer o Databricks Runtime 19 ou superior. Para mais informações sobre as Páginas do Site, consulte as páginas do SharePoint e o modelo da página.

Pode importar páginas do site das seguintes formas:

Ingerir as Páginas do Site como qualquer outro ficheiro:

Python

# Read a single Site Page
df = (spark.read
        .format("binaryFile")
        .option("databricks.connection", "my_sharepoint_conn")
        .load("https://mytenant.sharepoint.com/sites/test-site/SitePages/my-news-post.aspx"))

# Read a site's Site Pages library
df = (spark.read
        .format("binaryFile")
        .option("databricks.connection", "my_sharepoint_conn")
        .option("pathGlobFilter", "*.aspx") # optional. Example: only ingest Site Page files
        .load("https://mytenant.sharepoint.com/sites/test-site/SitePages"))

# Read all Site Pages from a site
df = (spark.read
        .format("binaryFile")
        .option("databricks.connection", "my_sharepoint_conn")
        .option("recursiveFileLookup", True)
        .option("pathGlobFilter", "*.aspx") # optional. Example: only ingest Site Page files
        .load("https://mytenant.sharepoint.com/sites/test-site"))

SQL

-- Read a single Site Page
CREATE TABLE site_page AS
SELECT * FROM read_files(
  "https://mytenant.sharepoint.com/sites/test-site/SitePages/my-news-post.aspx",
  `databricks.connection` => "my_sharepoint_conn",
  format => "binaryFile"
);

-- Read a site's Site Pages library
CREATE TABLE site_pages AS
SELECT * FROM read_files(
  "https://mytenant.sharepoint.com/sites/test-site/SitePages",
  `databricks.connection` => "my_sharepoint_conn",
  format => "binaryFile",
  pathGlobFilter => "*.aspx" -- optional. Example: only ingest Site Page files
);

-- Read all Site Pages from a site
CREATE TABLE site_with_pages AS
SELECT * FROM read_files(
  "https://mytenant.sharepoint.com/sites/test-site",
  `databricks.connection` => "my_sharepoint_conn",
  format => "binaryFile",
  recursiveFileLookup => true,
  pathGlobFilter => "*.aspx" -- optional. Example: only ingest Site Page files
);

O Auto Loader e COPY INTOoutras interfaces funcionam com as Páginas do Site da mesma forma que qualquer outro ficheiro. Veja Exemplos para exemplos de ingestão.

Limitações

O conector SharePoint padrão tem as seguintes limitações.

• Não é possível importar múltiplos sites com a mesma consulta. Para obter dados de dois sites, deve escrever duas consultas separadas.
• Podes usar a pathGlobFilter opção de filtrar ficheiros por nome. A filtragem baseada em caminhos de pasta não é suportada.
• Listas SharePoint não são suportadas.
• A escrita de retorno para um servidor SharePoint não é suportada.
• O Auto Loader cleanSource (apagar ou arquivar ficheiros na origem após a ingestão) não é suportado.

Próximos passos

• Saiba mais sobre o Auto Loader para padrões avançados de ingestão de streaming
• Explore o COPY INTO para cargas incrementais idempotentes
• Compare com os padrões de ingestão de armazenamento de objetos na cloud
• Configure o agendamento de tarefas para automatizar os seus fluxos de ingestão de dados
• Utilize Lakeflow pipelines para criar pipelines de dados de ponta a ponta com transformações