Ingerir arquivos do OneDrive

info

Beta

Esse recurso está em Beta. Os administradores do workspace podem ativá-lo na página Pré-visualizações optando pela prévia do Lakeflow Connect for OneDrive For Business . Consulte Gerenciar prévias do Databricks.

:::note Compliance

O conector do OneDrive oferece suporte ao uso em Workspace com as Configurações de segurança e compliance aprimoradas habilitadas.

:::

O senhor pode ingerir arquivos estruturados, semiestruturados e não estruturados do Microsoft OneDrive for Business de um usuário (a unidade pessoal My files ) em tabelas Delta. O conector padrão do OneDrive oferece suporte à ingestão incremental de arquivos do OneDrive usando APIs de lotes e transmissão, incluindo Auto Loader, spark.read e COPY INTO, tudo com governança do Unity Catalog. Use estas APIs para criar DataFrames do Spark, views materializadas e tabelas de transmissão diretamente de arquivos no OneDrive.

O conector do OneDrive ingere arquivos da unidade pessoal de um usuário individual. Para ingerir de sites do SharePoint, sites de equipe ou bibliotecas de documentos compartilhados, use o conector do SharePoint.

Principais recursos

O conector padrão do OneDrive oferece:

• Ingestão de arquivos estruturados, semiestruturados e não estruturados do OneDrive pessoal de um usuário.
• Ingestão granular: ingira uma unidade inteira, uma pasta ou um único arquivo.
• Ingestão em lotes e de transmissão usando spark.read, Auto Loader e COPY INTO.
• Inferência e evolução automática de esquema para formatos estruturados e semiestruturados, como CSV.
• Armazenamento de credenciais seguro com uma conexão do Unity Catalog.
• Seleção de arquivos com correspondência de padrão usando pathGlobFilter.

Requisitos

Para ingerir arquivos do OneDrive, o senhor deve ter o seguinte:

• Um workspace com o Unity Catalog habilitado.

• CREATE CONNECTION privilégios para criar uma conexão com o OneDrive, ou o privilégio apropriado para usar uma existente com base no seu modo de acesso ao cluster:

  • Modo de acesso dedicado: MANAGE CONNECTION.
  • Mode de acesso Padrão: USE CONNECTION.

• Compute que usa a versão 19 ou superior do Databricks Runtime.

• Autenticação OAuth configurada com o escopo de permissão Files.Read.All.

Criar a conexão

Crie uma conexão do Unity Catalog para armazenar suas credenciais do OneDrive. O conector do OneDrive usa autorização OAuth user-to-machine (U2M) com o Microsoft Entra ID (Azure AD) e o Microsoft Graph.

1. No workspace do Databricks, selecione Catalog > External locations > Connections > Create connection .
2. Na página Noções básicas de conexão do assistente Configurar conexão , especifique um Nome da conexão exclusivo.
3. No menu suspenso Connection type , pesquise e selecione OneDrive .
4. (Opcional) Adicione um comentário.
5. Selecione Avançar .
6. Na página Autenticação , entre com a conta Microsoft da qual você deseja ler o OneDrive e conceda consentimento às permissões solicitadas do Microsoft Graph (Files.Read.All e offline_access).
7. Após ser redirecionado de volta ao workspace do Databricks, selecione Create connection .

A conexão lê arquivos como o usuário conectado, portanto, o conector pode acessar apenas os arquivos que esse usuário pode acessar em seu OneDrive.

Ler arquivos do OneDrive

Para ler arquivos, passe a conexão que você criou usando a opção databricks.connection e uma URL que aponte para o recurso do OneDrive que você deseja acessar. A URL que você fornece determina o escopo da ingestão.

Os seguintes tipos de caminho são suportados:

Tipo de caminho	Descrição
Unidade inteira	Copie o URL raiz do seu OneDrive na barra de endereços. https://mytenant-my.sharepoint.com/personal/user_mytenant_onmicrosoft_com/Documents
Pasta	Abra a pasta no OneDrive e copie o URL da barra de endereços. https://mytenant-my.sharepoint.com/personal/user_mytenant_onmicrosoft_com/_layouts/15/onedrive.aspx?id=%2Fpersonal%2Fuser%2FDocuments%2FReports
Arquivo	Selecione o arquivo, clique no menu flutuante ( ... ) e selecione Open in browser ou Details , em seguida, copie a URL. https://mytenant-my.sharepoint.com/personal/user_mytenant_onmicrosoft_com/Documents/Reports/report.csv
Compartilhar link	Selecione o arquivo ou pasta, clique em Compartilhar ou Copiar link e use o link resultante. O Databricks recomenda configurar o link de compartilhamento para nunca expirar. https://mytenant-my.sharepoint.com/:x:/g/personal/user_mytenant_onmicrosoft_com/Eab12...

Tipo de caminho	Descrição
Unidade inteira	Copie o URL raiz do seu OneDrive na barra de endereços. https://mytenant-my.sharepoint.com/personal/user_mytenant_onmicrosoft_com/Documents
Pasta	Abra a pasta no OneDrive e copie o URL da barra de endereços. https://mytenant-my.sharepoint.com/personal/user_mytenant_onmicrosoft_com/_layouts/15/onedrive.aspx?id=%2Fpersonal%2Fuser%2FDocuments%2FReports
Arquivo	Selecione o arquivo, clique no menu flutuante ( ... ) e selecione Open in browser ou Details , em seguida, copie a URL. https://mytenant-my.sharepoint.com/personal/user_mytenant_onmicrosoft_com/Documents/Reports/report.csv
Compartilhar link	Selecione o arquivo ou pasta, clique em Compartilhar ou Copiar link e use o link resultante. O Databricks recomenda configurar o link de compartilhamento para nunca expirar. https://mytenant-my.sharepoint.com/:x:/g/personal/user_mytenant_onmicrosoft_com/Eab12...

nota

As URLs do OneDrive usam o host pessoal -my (por exemplo, mytenant-my.sharepoint.com), que é distinto do host do SharePoint (mytenant.sharepoint.com). Links de compartilhamento para sites do SharePoint não são aceitos pelo conector do OneDrive -- use o conector do SharePoint para esses casos.

A URL deve ser resolvida para seu drive pessoal, uma pasta ou arquivo dentro dele, ou um link de compartilhamento. Uma URL de host simples (por exemplo, https://mytenant-my.sharepoint.com/) ou um caminho que não aponte para seu drive (por exemplo, https://mytenant-my.sharepoint.com/shared) não é suportado.

Exemplos

Existem algumas maneiras de ler arquivos usando o conector padrão do OneDrive.

Transmissão de arquivos do OneDrive usando o Auto Loader

O Auto Loader oferece a maneira mais eficiente de ingerir arquivos de forma incremental do OneDrive. Ele detecta automaticamente novos arquivos e os processa à medida que chegam. Ele também pode ingerir arquivos estruturados e semiestruturados, como CSV e JSON, com inferência e evolução automática de esquema. Para obter detalhes sobre o uso do Auto Loader, consulte Padrões comuns de carregamento de dados.

Python

# Incrementally ingest new PDF files
df = (spark.readStream.format("cloudFiles")
    .option("cloudFiles.format", "binaryFile")
    .option("databricks.connection", "my_onedrive_conn")
    .option("cloudFiles.schemaLocation", <path to a schema location>)
    .option("pathGlobFilter", "*.pdf")
    .load("https://mytenant-my.sharepoint.com/personal/user_mytenant_onmicrosoft_com/Documents")
)

# Incrementally ingest CSV files with automatic schema inference and evolution
df = (spark.readStream.format("cloudFiles")
    .option("cloudFiles.format", "csv")
    .option("databricks.connection", "my_onedrive_conn")
    .option("cloudFiles.schemaLocation", <path to a schema location>)
    .option("pathGlobFilter", "*.csv")
    .option("cloudFiles.inferColumnTypes", True)
    .option("header", True)
    .load("https://mytenant-my.sharepoint.com/personal/user_mytenant_onmicrosoft_com/Documents/IoT_Logs")
)

Ler arquivos do OneDrive usando leitura em lote do Spark

O exemplo a seguir mostra como ingerir arquivos do OneDrive em Python usando a função spark.read. Defina a opção recursiveFileLookup como true para ler arquivos de pastas aninhadas no seu OneDrive.

Python

# Read unstructured data as binary files
df = (spark.read
        .format("binaryFile")
        .option("databricks.connection", "my_onedrive_conn")
        .option("recursiveFileLookup", True)
        .option("pathGlobFilter", "*.pdf") # optional. Example: only ingest PDFs
        .load("https://mytenant-my.sharepoint.com/personal/user_mytenant_onmicrosoft_com/Documents"))

# 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_onedrive_conn")
        .option("pathGlobFilter", "*.csv")
        .option("recursiveFileLookup", True)
        .option("inferSchema", True)
        .option("header", True)
        .load("https://mytenant-my.sharepoint.com/personal/user_mytenant_onmicrosoft_com/Documents/IoT_Logs"))

Ler arquivos do OneDrive usando Spark SQL

O exemplo a seguir mostra como ingerir arquivos do OneDrive em SQL usando a função table-valued read_files. Para obter detalhes sobre o uso de read_files, consulte a função table-valuedread_files.

SQL

-- Read pdf files
CREATE TABLE my_table AS
SELECT * FROM read_files(
  "https://mytenant-my.sharepoint.com/personal/user_mytenant_onmicrosoft_com/Documents",
  `databricks.connection` => "my_onedrive_conn",
  format => "binaryFile",
  pathGlobFilter => "*.pdf", -- optional. Example: only ingest PDFs
  schemaEvolutionMode => "none"
);

-- Read CSV files with automatic schema inference
CREATE TABLE my_csv_table AS
SELECT * FROM read_files(
  "https://mytenant-my.sharepoint.com/personal/user_mytenant_onmicrosoft_com/Documents/IoT_Logs",
  `databricks.connection` => "my_onedrive_conn",
  format => "csv",
  header => true,
  schemaEvolutionMode => "none"
);

Ingerir arquivos do OneDrive em LakeFlow Pipelines

nota

O conector OneDrive requer o Databricks Runtime 19 ou posterior. Para usar o conector, defina "CHANNEL" = "PREVIEW" nas configurações do seu pipeline. Para mais informações sobre pré-lançamentos, consulte Referência de propriedades do pipeline.

Os exemplos a seguir mostram como ler arquivos do OneDrive usando o Auto Loader em LakeFlow Pipelines.

Python

Python

from pyspark import pipelines as dp

# Incrementally ingest new PDF files
@dp.table
def onedrive_pdf_table():
  return (spark.readStream.format("cloudFiles")
    .option("cloudFiles.format", "binaryFile")
    .option("databricks.connection", "my_onedrive_conn")
    .option("pathGlobFilter", "*.pdf")
    .load("https://mytenant-my.sharepoint.com/personal/user_mytenant_onmicrosoft_com/Documents")
  )

# Incrementally ingest CSV files with automatic schema inference and evolution
@dp.table
def onedrive_csv_table():
  return (spark.readStream.format("cloudFiles")
      .option("cloudFiles.format", "csv")
      .option("databricks.connection", "my_onedrive_conn")
      .option("pathGlobFilter", "*.csv")
      .option("cloudFiles.inferColumnTypes", True)
      .option("header", True)
      .load("https://mytenant-my.sharepoint.com/personal/user_mytenant_onmicrosoft_com/Documents/IoT_Logs")
  )

SQL

SQL

-- Incrementally ingest new PDF files
CREATE OR REFRESH STREAMING TABLE onedrive_pdf_table
AS SELECT * FROM STREAM read_files(
  "https://mytenant-my.sharepoint.com/personal/user_mytenant_onmicrosoft_com/Documents",
  format => "binaryFile",
  `databricks.connection` => "my_onedrive_conn",
  pathGlobFilter => "*.pdf");

-- Incrementally ingest CSV files with automatic schema inference and evolution
CREATE OR REFRESH STREAMING TABLE onedrive_csv_table
AS SELECT * FROM STREAM read_files(
  "https://mytenant-my.sharepoint.com/personal/user_mytenant_onmicrosoft_com/Documents/IoT_Logs",
  format => "csv",
  `databricks.connection` => "my_onedrive_conn",
  pathGlobFilter => "*.csv",
  header => "true");

Ingestão incremental com COPY INTO

COPY INTO fornece carregamento incremental idempotente de arquivos em uma tabela Delta. Para obter detalhes sobre o uso de COPY INTO, consulte Padrões comuns de carregamento de dados usando COPY INTO.

SQL

CREATE TABLE IF NOT EXISTS onedrive_pdf_table;
CREATE TABLE IF NOT EXISTS onedrive_csv_table;

-- Incrementally ingest new PDF files
COPY INTO onedrive_pdf_table
  FROM "https://mytenant-my.sharepoint.com/personal/user_mytenant_onmicrosoft_com/Documents"
  FILEFORMAT = BINARYFILE
  PATTERN = '*.pdf'
  FORMAT_OPTIONS ('databricks.connection' = 'my_onedrive_conn')
  COPY_OPTIONS ('mergeSchema' = 'true');

-- Incrementally ingest CSV files with automatic schema inference and evolution
COPY INTO onedrive_csv_table
  FROM "https://mytenant-my.sharepoint.com/personal/user_mytenant_onmicrosoft_com/Documents/IoT_Logs"
  FILEFORMAT = CSV
  PATTERN = '*.csv'
  FORMAT_OPTIONS ('databricks.connection' = 'my_onedrive_conn', 'header' = 'true', 'inferSchema' = 'true')
  COPY_OPTIONS ('mergeSchema' = 'true');

Ingestão incremental eficiente com acompanhamento de alterações

Por default, o Auto Loader descobre novos arquivos no OneDrive listando a unidade a cada atualização. Para unidades grandes, você pode, em vez disso, rastrear alterações usando o feed de alterações do Microsoft Graph, que retorna apenas os arquivos que foram adicionados ou modificados desde a atualização anterior, em vez de listar novamente a unidade inteira. Para habilitá-lo, defina a opção cloudFiles.readChangeFeed para true.

Python

df = (spark.readStream.format("cloudFiles")
    .option("cloudFiles.format", "binaryFile")
    .option("cloudFiles.readChangeFeed", "true")
    .option("databricks.connection", "my_onedrive_conn")
    .option("cloudFiles.schemaLocation", <path to a schema location>)
    .load("https://mytenant-my.sharepoint.com/personal/user_mytenant_onmicrosoft_com/Documents")
)

Ao usar cloudFiles.readChangeFeed, observe o seguinte:

• O formato binaryFile é obrigatório. O acompanhamento de alterações não está disponível para outros formatos.
• O caminho de carregamento deve ser resolvido para uma unidade ou um diretório dentro de uma unidade. Um site pessoal simples ou uma raiz de tenant não são suportados.
• Você não pode fornecer um esquema explícito. O esquema de saída é determinado automaticamente pelo formato do arquivo.

Analisar arquivos não estruturados

Ao ingerir arquivos não estruturados do OneDrive (como PDFs, documentos do Word ou arquivos do PowerPoint) usando o conector padrão do OneDrive com o formato binaryFile, o conteúdo do arquivo é armazenado como dados binários brutos. Para preparar esses arquivos para cargas de trabalho de AI — 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 bronze chamada documents, adicionando uma nova coluna com o conteúdo analisado:

SQL

CREATE TABLE documents AS
SELECT * FROM read_files(
  "https://mytenant-my.sharepoint.com/personal/user_mytenant_onmicrosoft_com/Documents",
  `databricks.connection` => "my_onedrive_conn",
  format => "binaryFile",
  pathGlobFilter => "*.{pdf,docx}",
  schemaEvolutionMode => "none"
);
SELECT *, ai_parse_document(content, map('version', '2.0')) AS parsed_content
FROM documents;

Você também pode usar ai_parse_document dentro de um Lakeflow pipeline para habilitar a análise incremental. Por exemplo, você pode definir uma tabela de transmissão bronze que ingere os arquivos binários brutos e, em seguida, uma segunda tabela de transmissão que coloca o conteúdo analisado em uma nova coluna:

SQL

-- Bronze: incrementally ingest the raw documents as binary
CREATE OR REFRESH STREAMING TABLE onedrive_documents
AS SELECT * FROM STREAM read_files(
  "https://mytenant-my.sharepoint.com/personal/user_mytenant_onmicrosoft_com/Documents",
  `databricks.connection` => "my_onedrive_conn",
  format => "binaryFile",
  pathGlobFilter => "*.{pdf,docx}");

-- Silver: land the parsed content in a new column
CREATE OR REFRESH STREAMING TABLE onedrive_documents_parsed
AS SELECT
  *,
  ai_parse_document(content, map('version', '2.0')) AS parsed_content
FROM STREAM onedrive_documents;

A coluna parsed_content contém texto extraído, tabelas, informações de disposição e metadados que podem ser usados diretamente para pipelines de AI downstream.

Como ambas as tabelas são tabelas de transmissão, os arquivos do OneDrive recém-ingeridos são analisados automaticamente sempre que o pipeline é atualizado, e a saída analisada permanece sincronizada com os dados recebidos.

Saiba mais: Consulte ai_parse_document para formatos suportados e opções avançadas, incluindo a opção version que pin o esquema de saída.

Limitações

O conector padrão do OneDrive tem as seguintes limitações.

• O conector ingere dados do OneDrive pessoal de um único usuário ( Meus arquivos ). Sites do SharePoint, sites de equipe e bibliotecas de documentos compartilhados não são suportados. Use o conector do SharePoint para esses casos.
• URLs de host simples e caminhos que não sejam de unidade não são suportados.
• Listas e páginas de site do OneDrive não são suportadas. O conector ingere apenas os arquivos armazenados no drive do OneDrive de um usuário.
• Você pode usar a opção pathGlobFilter para filtrar arquivos por nome. Não há suporte para filtragem baseada em caminho de pasta.
• O acompanhamento de alterações com cloudFiles.readChangeFeed requer o formato binaryFile e um caminho de carregamento que seja resolvido para uma unidade ou um diretório dentro de uma unidade. Consulte Ingestão incremental eficiente com acompanhamento de alterações.
• A gravação de volta no OneDrive não é suportada. O conector é somente leitura.
• O Auto Loader cleanSource (excluir ou arquivar arquivos na origem após a ingestão) não é compatível.

Outros recursos

• Saiba mais sobre o Auto Loader para padrões avançados de ingestão de transmissão
• Explore o COPY INTO para carregamentos incrementais idempotentes
• Revise ai_parse_document para analisar arquivos não estruturados
• Compare com o conector do SharePoint para ingestão a partir de sites do SharePoint
• Configure o agendamento de jobs para automatizar seus fluxos de trabalho de ingestão