Ingerir arquivos de SharePoint

Importante

Esse recurso está em Beta. Os administradores do workspace podem controlar o acesso a esse recurso na página Visualizações . Consulte Gerenciar versões de pré-visualização do Azure Databricks.

:::note Conformidade

O conector SharePoint dá suporte ao uso em workspaces com as configurações de segurança e conformidade aprimoradas do Configure habilitadas.

:::

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 SharePoint usando APIs de streaming e batch, incluindo o Auto Loader, spark.read e COPY INTO, tudo com governança do Unity Catalog.

Escolha o seu conector do SharePoint

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

Consideração Conector de SharePoint gerenciado Conector de SharePoint Padrão
Gerenciamento e personalização Um conector totalmente gerenciado.
Conectores simples e de baixa manutenção para aplicativos empresariais que ingerem dados em tabelas Delta e os mantêm sincronizados com a origem. Consulte Conectores gerenciados no Lakeflow Connect.
Crie pipelines de ingestão personalizados com SQL, PySpark ou Pipelines Declarativos do Lakeflow Spark, usando APIs para lote e streaming, como read_files, spark.read, COPY INTO e Carregador Automático.
Oferece a flexibilidade para executar transformações complexas durante a ingestão, ao mesmo tempo em que oferece maior responsabilidade pelo gerenciamento e manutenção de seus pipelines.
Formato da saída Tabela de conteúdo binário uniforme. Ingere cada arquivo no formato binário (um arquivo por linha), juntamente com metadados de arquivo em
colunas adicionais.
Tabelas Delta estruturadas. Ingere arquivos estruturados (como CSV e Excel) como tabelas Delta. Também pode ser usado para ingerir
arquivos não estruturados no formato binário.
Granularidade, filtragem e seleção Nenhuma subpasta ou seleção de nível de arquivo hoje. Nenhuma filtragem baseada em padrão.
Ingere todos os arquivos na biblioteca de documentos SharePoint especificada.
Granular e personalizado.
Seleção baseada em URL a ser ingerida de bibliotecas de documentos, subpastas ou arquivos individuais. Também dá suporte à filtragem baseada em padrões usando a opção pathGlobFilter .

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 lote e streaming usando spark.read, Auto Loader 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.
  • CREATE CONNECTION privilégios para criar uma conexão 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 usa o Databricks Runtime versão 17.3 LTS ou posterior.
  • Autenticação OAuth configurada com o escopo de permissão Sites.Read.All ou Sites.Selected.
  • O recurso SharePoint Beta está habilitado na página Previews. Consulte Gerenciar versões de pré-visualização do Azure Databricks.
  • Opcional: habilite o recurso Excel Beta para analisar arquivos Excel. Consulte Read Excel files.

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 têm suporte no Databricks Runtime 17.3 LTS e posterior:

Tipo de caminho Descrição
Site Copie a URL do site da barra de endereços.
https://mytenant.sharepoint.com/sites/test-site
Subsite Copie a URL do subsite da barra de endereços.
https://mytenant.sharepoint.com/sites/test-site/test-subsite
Biblioteca de documentos Abra a biblioteca do conteúdo do site e copie a URL da barra de endereços .
https://mytenant.sharepoint.com/sites/test-site/Shared%20Documents
https://mytenant.sharepoint.com/sites/test-site/custom-drive
Pasta Abra a pasta do conteúdo do site e copie a URL da barra de endereços . Como alternativa, abra o painel Details da pasta no SharePoint e clique no ícone de cópia ao lado de Path.
https://mytenant.sharepoint.com/sites/test-site/Shared%20Documents/Forms/AllItems.aspx?id=%2Fsites...
https://mytenant.sharepoint.com/sites/test-site/custom-drive/test-folder
File Selecione o arquivo, clique no menu de mais opções (...) e selecione Visualizar. Copie a URL da barra de endereços. Como alternativa, abra o painel Details do arquivo no SharePoint e clique no ícone de cópia ao lado de Path.
https://mytenant.sharepoint.com/sites/test-site/Shared%20Documents/Forms/AllItems.aspx?viewid=1a2b3c...
https://mytenant.sharepoint.com/sites/test-site/custom-drive/test-folder/test.csv

O Databricks Runtime 18.3 e posterior adiciona suporte para os seguintes tipos de caminho:

Tipo de caminho Descrição
Inquilino Copie a URL raiz do tenant da barra de endereços.
https://mytenant.sharepoint.com
Subsite aninhado Copie a URL do subsite da barra de endereços.
https://mytenant.sharepoint.com/sites/test-site/subsite/nested-subsite/nested-nested-subsite
Compartilhar link Selecione o arquivo ou pasta, clique no menu de opções (...) e selecione Copiar link. O Databricks recomenda definir o link de compartilhamento para nunca expirar.
https://mytenant.sharepoint.com/:i:/s/test-site/1A2B3C4D5E6F7G8H9I
Microsoft 365 para a Web (antigo Office) Abra o arquivo em Microsoft 365 da Web e copie a URL da barra de endereços.
https://mytenant.sharepoint.com/:x:/r/sites/test-site/_layouts/15/Doc.aspx?sourcedoc=%1A2B...

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

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.

# 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 Declarativos do Lakeflow Spark

Observação

O conector SharePoint requer o Databricks Runtime 17.3 ou posterior. Para usar o conector, configure "CHANNEL" = "PREVIEW" em suas configurações de pipeline. Para obter mais informações sobre visualizações, consulte a referência de propriedades do Pipeline.

Os exemplos a seguir mostram como ler arquivos 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 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) 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 chegam do SharePoint, eles são analisados automaticamente à medida que o pipeline atualiza.

Por exemplo, você pode definir uma exibiçã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;

Essa abordagem garante que:

  • Os arquivos de SharePoint recém-ingeridos 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.

SharePoint coluna de metadados

Importante

Este recurso está em Versão prévia privada. Para experimentá-lo, entre em contato com o representante do Azure Databricks.

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 requer o Databricks Runtime 18.1 ou superior e está disponível para todos os formatos de arquivo ao ler de 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.

Nome Tipo Descrição Exemplo Versão Mínima do Databricks Runtime
item_id STRING O ID driveItem do item. 01OMQ3MNLH42C5J675CBEI5CRK7SPKQUTZ 18.1
site_id STRING A ID do site SharePoint que contém o item. mytenant.sharepoint.com,69dc7b12-f92c-498d-9514-596b793a1f77,c6c1db8d-2b8d-48a1-a549-394b63d74725 18.1
drive_id STRING O ID da unidade que contém o item. b!EnvcaSz5jUmVFFlreTofd43bwcaNK6FIpUk5S2PXRyWTvQraaWQkSpwQEgThHDS- 18.1
drive_type STRING O tipo de unidade, por exemplo, documentLibrary para bibliotecas de SharePoint ou business para OneDrive for Business. documentLibrary 18.1
parent_id STRING O ID do driveItem da pasta-mãe. 01OMQ3MNN6Y2GOVW7725BZO354PWSELRRZ 18.1
Parent_name STRING O nome da pasta pai. Shared Documents 18.1
parent_path STRING O caminho relativo da unidade da pasta pai. /drives/b!EnvcaSz5.../root: 18.1
web_url STRING A URL do navegador do item no SharePoint. https://mytenant.sharepoint.com/sites/TestSite/_layouts/15/Doc.aspx?sourcedoc=... 18.1
mime_type STRING O tipo MIME do item. application/vnd.ms-excel 18.1
created_by_email STRING O email do usuário que criou o item. alice@example.onmicrosoft.com 18.1
created_by_name STRING O nome de exibição do usuário que criou o item. Alice Example 18.1
created_timestamp TIMESTAMP A hora em que o item foi criado. 2025-12-03 13:33:12 18.1
last_modified_by_email STRING O email do usuário que modificou o item pela última vez. alice@example.onmicrosoft.com 18.1
última_modificação_por_nome STRING O nome de exibição do usuário que modificou o item pela última vez. Alice Example 18.1
etag STRING ETag do item Alterações quando o item ou qualquer um de seus metadados é alterado. "{D485E667-FDFB-4810-8E8A-2AFC9EA85279},1" 18.1
ctag STRING Tag de alteração do item. Muda somente quando o conteúdo do item é alterado. "c:{D485E667-FDFB-4810-8E8A-2AFC9EA85279},1" 18.1
descrição STRING A descrição do item, se definida. Q4 financial report 18.1
additional_metadata VARIANT Qualquer outro campo driveItem retornado pelo Microsoft Graph, mas não extraído acima. {"shared":{"scope":"users"},...} 18.1

Observação

O additional_metadata campo é retornado como VARIANT. Consulte VARIANT tipo.

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

Limitações

O conector de SharePoint padrão 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 não suportados: listas do SharePoint e páginas de site .aspx não são suportados. Há suporte apenas para arquivos em Bibliotecas de Documentos.
  • 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