Ingerir arquivos do SharePoint

Saiba como ingerir arquivos estruturados, semi-estruturados e não estruturados do Microsoft SharePoint em tabelas Delta. O conector do SharePoint oferece suporte à ingestão incremental de arquivos do SharePoint usando APIs de lote e streaming, incluindo Auto Loader, spark.read e COPY INTO, tudo com governança pelo Unity Catalog.

Escolha seu conector do SharePoint

O Lakeflow Connect oferece dois conectores complementares do SharePoint. Ambos acessam dados no SharePoint, mas dão suporte a metas distintas.

Características principais

O conector padrão do SharePoint oferece:

• Ingestão de arquivos estruturados, semiestruturados e não estruturados
• Ingestão granular: ingerir um site específico, um sub-site, uma biblioteca de documentos, uma pasta ou um único arquivo
• Ingestão de lote e streaming usando spark.read, Auto Loader e COPY INTO
• Inferência e evolução automáticas de esquema para formatos estruturados e semiestruturados, como CSV e Excel
• Armazenamento seguro de credenciais com uma conexão do Unity Catalog
• Seleção de arquivo com correspondência de padrões usando pathGlobFilter

Requirements

Para ingerir arquivos do SharePoint, você deve ter o seguinte:

• Um workspace com o Catálogo do Unity habilitado
• CREATE CONNECTION privilégios para criar uma conexão do SharePoint (ou USE CONNECTION para usar uma existente)
• Computação que usa o Databricks Runtime versão 17.3 LTS ou superior
• Autenticação OAuth configurada com o escopo de permissão Sites.Read.All
• O recurso Beta do SharePoint está habilitado na página Visualizações . Consulte Gerenciar visualizações do Azure Databricks
• Opcional: habilite o recurso Beta do Excel para analisar arquivos do Excel. Consulte ler arquivos do Excel

Criar a conexão

Crie uma conexão do Catálogo do Unity para armazenar suas credenciais do SharePoint. O processo de configuração de conexão é compartilhado entre os conectores padrão e gerenciados do SharePoint.

Para obter instruções completas de configuração de conexão, incluindo opções de autenticação OAuth, consulte Visão geral da configuração de ingestão do SharePoint.

Ler arquivos do SharePoint

Para ler arquivos do SharePoint usando o Spark, especifique a conexão criada na etapa anterior usando a opção databricks.connection de fonte de dados e forneça a URL do recurso do SharePoint que você deseja acessar. Essa URL pode se referir a um arquivo específico, uma pasta, uma biblioteca de documentos (unidade) 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

Exemplos

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

Transmitir arquivos do SharePoint usando o Carregador Automático

O Carregador Automático fornece a maneira mais eficiente de ingerir arquivos estruturados incrementalmente do SharePoint. Ele detecta automaticamente novos arquivos e os processa conforme eles chegam. Ele também pode ingerir arquivos estruturados e semiestruturados, como CSV e JSON, com inferência e evolução automáticas de esquema. Para obter detalhes sobre o uso do Carregador Automático, 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")
)

Ler arquivos do SharePoint usando a 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"))

Ler arquivos do SharePoint usando o SPARK SQL

O exemplo a seguir mostra como ingerir arquivos do SharePoint no SQL usando read_files a função com valor de tabela. Para obter detalhes sobre o uso de read_files, consulte read_files função valorada em tabelas.

-- 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 de arquivos idempotente em uma tabela Delta. Para obter detalhes sobre o uso de COPY INTO, consulte os padrões comuns de uso de COPY INTO para carregamento de dados.

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 arquivos do SharePoint em Pipelines Declarativos do Lakeflow Spark

Os exemplos a seguir mostram como ler arquivos do SharePoint usando o Carregador Automático no Lakeflow Spark Declarative 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"
);

Analisar arquivos não estruturados

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

O exemplo a seguir mostra como analisar documentos não estruturados armazenados em uma tabela Delta de 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 para pipelines de IA downstream.

Análise incremental com pipelines declarativos do Lakeflow Spark

Você também pode usar ai_parse_document no Lakeflow Spark Declarative Pipelines para habilitar a análise incremental. À medida que novos arquivos são transmitidos do SharePoint, eles são analisados automaticamente conforme o pipeline é atualizado.

Por exemplo, você pode definir uma Visão Materializada que processa 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;

Essa abordagem garante que:

• Arquivos do SharePoint ingeridos recentemente são analisados automaticamente sempre que a Exibição Materializada é atualizada
• As saídas analisadas permanecem em sincronia com os dados de entrada
• Os pipelines de IA downstream sempre operam em representações de documentos atualizadas.

Saiba mais: consulte ai_parse_document para ver formatos com suporte e opções avançadas.

Limitações

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

• Nenhuma ingestão de vários sites: você não pode ingerir vários sites com a mesma consulta. Para ingerir de dois sites, você deve escrever duas consultas separadas.
• Filtragem: você pode usar a opção pathGlobFilter para filtrar arquivos por nome. Não há suporte para filtragem baseada em caminho de pasta.
• Formatos sem suporte: não há suporte para listas do SharePoint e .aspx páginas do site. Há suporte apenas para arquivos em Bibliotecas de Documentos.
• Não há suporte para gravar novamente em um servidor do SharePoint.
• Não há suporte para o Carregador cleanSource Automático (excluindo ou arquivando arquivos na origem após a ingestão).

Próximas etapas

• Saiba mais sobre o Carregador Automático para padrões avançados de ingestão de streaming
• Explore COPY INTO para cargas incrementais idempotentes
• Comparar com padrões de ingestão de armazenamento de objetos na nuvem
• Configurar o agendamento de trabalho para automatizar seus fluxos de trabalho de ingestão
• Use Lakeflow Spark Declarative Pipelines para criar pipelines de dados completos com transformações