Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
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 eCOPY 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 CONNECTIONprivilé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.
- Modo de Acesso Dedicado:
- 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.AllouSites.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%20Documentshttps://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
pathGlobFilterpara 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
cleanSourceAutomá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