Ingerir arquivos de SharePoint

Você pode ingerir arquivos estruturados, semi-estruturados e não estruturados de Microsoft SharePoint em tabelas Delta. APIs SQL e Spark suportam a ingestão incremental de arquivos SharePoint usando APIs em lote e streaming, incluindo Auto Loader spark.read e COPY INTO, todas com governança do Unity Catalog.

Escolha como ingerir do SharePoint

O Lakeflow Connect oferece duas formas de ingerir do SharePoint. Ambos acessam dados em SharePoint, mas diferem em seu nível de gerenciamento.

Características principais

As APIs SQL e Spark oferecem:

• 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 Páginas de Site do SharePoint (.aspx) no Databricks Runtime 19 e versões posteriores. Veja Importar Páginas de Site do SharePoint.
• Ingestão de lote e streaming usando spark.read, Carregador Automático e COPY INTO
• Inferência e evolução de esquema automático 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 de SharePoint, você deve ter o seguinte:

• Um espaço de trabalho com o Catálogo do Unity habilitado.
• Privilégios CREATE CONNECTION para criar uma conexão do SharePoint ou os privilégios adequados para usar uma conexão existente com base no modo de acesso do cluster:
  • Modo de Acesso Dedicado: MANAGE CONNECTION.
  • Modo de Acesso Padrão: USE CONNECTION.
• Computação que utiliza Databricks Runtime versão 17.3 LTS ou superior.
• Autenticação OAuth configurada com o escopo de permissão Sites.Read.All ou Sites.Selected.

Criar a conexão

Crie uma conexão do Catálogo do Unity para armazenar suas credenciais de SharePoint. O processo de configuração de conexão é o mesmo, seja usando APIs SQL e Spark ou o conector SharePoint gerenciado.

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, passe a conexão que você criou usando a opção databricks.connection e uma URL que aponta para o recurso SharePoint que você deseja acessar. A URL fornecida determina o escopo 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 caminho:

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

Exemplos

Existem algumas maneiras de ler arquivos do SharePoint usando APIs SQL e Spark.

Arquivos Stream SharePoint usando o Carregador Automático

O Carregador Automático fornece a maneira mais eficiente de ingerir arquivos estruturados de forma incremental de 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-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")
)

Lendo arquivos do SharePoint usando a leitura em lote do Spark

O exemplo a seguir mostra como ingerir arquivos SharePoint em Python usando a função spark.read. Defina a opção recursiveFileLookup como true para ler arquivos em estruturas aninhadas, como bibliotecas de documentos em um site, pastas em 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"))

Ler arquivos SharePoint usando o Spark SQL

O exemplo a seguir mostra como ingerir arquivos SharePoint no SQL usando a função read_files 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');

Importar arquivos do SharePoint em pipelines do Lakeflow

Os exemplos a seguir mostram como ler arquivos do SharePoint usando o Auto Loader em pipelines do 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 arquivos não estruturados

Ao ingerir arquivos não estruturados do SharePoint (como PDFs, documentos Word ou arquivos PowerPoint) usando APIs SQL e Spark com o formato binaryFile, o conteúdo do arquivo é armazenado como dados binários brutos. Para preparar esses arquivos para cargas de trabalho de IA, como geração aumentada por recuperação (RAG), busca, classificação ou compreensão de documentos, você pode fazer o parse do conteúdo binário para gerar 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, 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 para pipelines de IA downstream.

Análise incremental nos pipelines do Lakeflow

Você também pode usar ai_parse_document nos pipelines do Lakeflow para ativar a análise incremental. À medida que novos arquivos chegam do SharePoint, eles são analisados automaticamente à medida que o pipeline atualiza.

Por exemplo, você pode definir uma tabela de streaming bronze que ingere os arquivos binários brutos, depois uma segunda tabela de streaming que coloca o conteúdo analisado em uma 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;

Essa abordagem garante que:

• Arquivos SharePoint recém-ingeridos são analisados automaticamente sempre que o pipeline é atualizado.
• As saídas analisadas permanecem sincronizadas com os dados recebidos.
• Os pipelines de IA downstream sempre operam em representações de documentos atualizadas.

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

SharePoint coluna de metadados

A coluna _sharepoint_metadata é uma coluna de metadados oculta que fornece acesso a propriedades específicas SharePoint de arquivos ingeridos, provenientes do recurso driveItem Microsoft Graph. Ele exige o Databricks Runtime 18 LTS ou superior e está disponível para todos os formatos de arquivo ao ler a partir do SharePoint. Para incluir a _sharepoint_metadata coluna no DataFrame retornado, você deve selecioná-la explicitamente na consulta de leitura.

Se a fonte de dados contiver uma coluna chamada _sharepoint_metadata, a coluna de metadados SharePoint será renomeada para __sharepoint_metadata (com um sublinhado adicional à esquerda) para eliminação de duplicação. Sublinhados adicionais são adicionados até que o nome seja exclusivo.

Metadados de arquivo comuns, como o caminho ou o tamanho do arquivo, podem ser consultados usando a _metadata coluna. Confira Coluna de metadados de arquivo.

Esquema

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

Exemplos

Os exemplos a seguir mostram como incluir a _sharepoint_metadata coluna em uma 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 struct.

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

Extraia valores do campo additional_metadataVARIANT usando o operador de tipo ::.

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

Ingir páginas do site SharePoint

O SharePoint armazena as Páginas do Site como .aspx arquivos na biblioteca de Páginas do Site, separadas de suas bibliotecas de documentos. A ingestão de páginas do site requer o Databricks Runtime 19 ou posterior. Para mais informações sobre as Páginas do Site, veja Páginas do SharePoint e o modelo de página.

Você pode ingerir as Páginas do Site das seguintes formas:

Ingire as Páginas do Site como qualquer outro arquivo:

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, COPY INTO, e outras interfaces funcionam com as Páginas do Site da mesma forma que qualquer outro arquivo. Veja Exemplos para exemplos de ingestão.

Limitações

As APIs SQL e Spark apresentam as seguintes limitações.

• As seguintes implantações nacionais de nuvem do Microsoft 365 não são suportadas:
  • GCC High (Nuvem da Comunidade Governamental Alta):.sharepoint.us
  • Departamento de Defesa (DoD): .sharepoint-mil.us
  • Microsoft 365 operado pela 21Vianet na China:.sharepoint.cn
• Você não pode importar vários sites com a mesma consulta. Para ingerir de dois sites, você deve escrever duas consultas separadas.
• Você pode usar a opção pathGlobFilter para filtrar arquivos por nome. Não há suporte para filtragem baseada em caminho de pasta.
• Listas SharePoint não são suportadas.
• Não há suporte para gravar novamente em um servidor 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
• Configure o agendamento de trabalho para automatizar fluxos de trabalho de ingestão
• Usar pipelines do Lakeflow para criar pipelines de dados de ponta a ponta com transformações