Ingerir arquivos de SharePoint

:::note Conformidade

O conector gerenciado do SharePoint dá suporte aa uso em workspaces com as Configurar definições de segurança e conformidade aprimoradas ativado.

:::

Você pode ingerir arquivos estruturados, semi-estruturados e não estruturados de Microsoft SharePoint em tabelas Delta. O conector SharePoint dá suporte à ingestão incremental de arquivos do SharePoint usando APIs de streaming e lote, incluindo o Carregador Automático, spark.read e COPY INTO, tudo com governança do Catálogo do Unity.

Escolha o seu conector do SharePoint

O Lakeflow Connect oferece dois conectores SharePoint. Ambos acessam dados em SharePoint, mas diferem em seu nível de gerenciamento.

Características principais

O conector de SharePoint padrão 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 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.
• Opcional: habilite o recurso Excel Beta para analisar arquivos Excel. Consulte Ler e transmitir arquivos de Excel.

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 é compartilhado entre os conectores de SharePoint padrão e gerenciados.

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

Há algumas maneiras de ler arquivos usando o conector de SharePoint padrão.

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 de SharePoint (como PDFs, documentos Word ou arquivos PowerPoint) usando o conector de SharePoint padrão 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 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, 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 subsequentes sempre trabalham com representações atualizadas dos documentos.

Veja a ai_parse_document função 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. Para obter mais informações, consulte 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

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

• 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