Ingerir ficheiros do SharePoint

Importante

O conector padrão do SharePoint está em Beta. Os administradores do espaço de trabalho podem controlar o acesso a esse recurso na página Visualizações . Consulte Gerenciar visualizações do Azure Databricks.

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

Escolha o seu conector SharePoint

O Lakeflow Connect oferece dois conectores SharePoint complementares. Ambos acedem a dados no SharePoint, mas apoiam objetivos distintos.

Consideração	Conector SharePoint Gerido	Conector SharePoint padrão
Gestão e personalização	Um conector totalmente gerido. Conectores simples e de baixa manutenção para aplicações empresariais que ingerem dados em tabelas Delta e os mantêm sincronizados com a fonte. Consulte Conectores gerenciados no Lakeflow Connect.	Construa pipelines de ingestão personalizados com SQL, PySpark ou Lakeflow Spark Declarative Pipelines usando APIs batch e de streaming como `read_files`, `spark.read`, `COPY INTO`, e Auto Loader. Oferece flexibilidade para realizar transformações complexas durante a ingestão, ao mesmo tempo que lhe dá maior responsabilidade na gestão e manutenção dos seus oleodutos.
Formato de saída	Tabela uniforme de conteúdo binário. Ingere cada ficheiro em formato binário (um ficheiro por linha), juntamente com os metadados do ficheiro em colunas adicionais.	Tabelas Delta estruturadas. Ingere ficheiros estruturados (como CSV e Excel) como tabelas Delta. Também pode ser usado para ingerir ficheiros não estruturados em formato binário.
Granularidade, filtragem e seleção	Hoje não há seleção de subpasta ou nível de ficheiro. Sem filtragem baseada em padrões. Ingere todos os ficheiros na biblioteca de documentos SharePoint especificada.	Granular e personalizado. Seleção baseada em URL para ingerir a partir de bibliotecas de documentos, subpastas ou ficheiros individuais. Também suporta filtragem baseada em padrões usando a `pathGlobFilter` opçã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 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 USE CONNECTION para usar uma existente)
Computação que utiliza Databricks Runtime versão 17.3 LTS ou superior
Autenticação OAuth configurada com o Sites.Read.All âmbito de permissões
A funcionalidade Beta do SharePoint está ativada a partir da página de Pré-visualizações . Veja Gerir Vistos Preliminares do Azure Databricks
Opcional: Ativar a funcionalidade Beta do Excel para analisar ficheiros Excel. Ver Ler ficheiros Excel

Criar a conexão

Crie uma ligação ao Unity Catalog para guardar as suas credenciais do SharePoint. O processo de estabelecimento 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, consulte Visão Geral da configuração da ingestão do SharePoint.

Leia ficheiros do SharePoint

Para ler ficheiros do SharePoint usando o Spark, especifique a ligação que criou no passo anterior usando a databricks.connection opção de fonte de dados e forneça a URL do recurso SharePoint a que pretende aceder. Este URL pode referir-se a um ficheiro específico, uma pasta, uma biblioteca de documentos (drive) ou um site inteiro. Os exemplos incluem:

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

Examples

Encontre exemplos de código para ler ficheiros usando o conector padrão do SharePoint.

Transmitir ficheiros SharePoint 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 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")
)

Leia ficheiros SharePoint usando leitura em lote do Spark

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

Leia ficheiros SharePoint usando Spark SQL

O exemplo seguinte mostra como ingerir ficheiros SharePoint em SQL usando read_files a função de valores de tabela. 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');

Ingerir ficheiros do SharePoint em pipelines declarativos do Lakeflow Spark

Observação

O SharePoint Connector requer Databricks Runtime 17.3 ou superior. Isto ainda não está disponível na versão Lakeflow Spark Declarative Pipelines. Para ver as versões do Databricks Runtime usadas com uma versão do Lakeflow Spark Declarative Pipelines, consulte as notas de versão dessa versão.

Os seguintes exemplos mostram como utilizar o Auto Loader para ler ficheiros do SharePoint nos Pipelines Declarativos do 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"
);

Analisar ficheiros não estruturados

Ao ingerir ficheiros não estruturados do SharePoint (como PDFs, documentos Word ou PowerPoint) usando o conector SharePoint padrão com binaryFile formato, o conteúdo dos ficheiros é 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) 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 de sintaxe incremental com Pipelines Declarativos do Lakeflow Spark

Também pode usar ai_parse_document dentro do Lakeflow Spark Declarative Pipelines para permitir a análise sintática incremental. À medida que novos ficheiros chegam do SharePoint, são automaticamente analisados à medida que o seu pipeline é atualizado.

Por exemplo, pode definir uma Visualização Materializada que analisa continuamente documentos recém-ingeridos:

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;

Esta abordagem garante que:

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

Saiba mais: Consulte ai_parse_document para formatos suportados e opções avançadas.

Limitações

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

Impossibilidade de ingestão multi-site: Não pode processar múltiplos sites com a mesma consulta. Para obter dados de dois sites, deve escrever duas consultas separadas.
Filtragem: Pode usar a pathGlobFilter opção de filtrar ficheiros por nome. A filtragem baseada em caminhos de pasta não é suportada.
Formatos não suportados: Listas SharePoint e páginas .aspx site não são suportados. Apenas os ficheiros nas Bibliotecas de Documentos são suportados.
Escrever de volta num servidor SharePoint não é suportado.
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 os Pipelines Declarativos Spark Lakeflow para construir pipelines de dados de ponta a ponta com transformações

Feedback

Esta página foi útil?

Last updated on 2025-12-19