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.

nota

A ingestão do OneDrive oferece suporte ao uso em Workspace com a opção Configure enhanced security and compliance settings ativada.

Você 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. As APIs SQL e Spark oferecem suporte à ingestão incremental de arquivos do OneDrive usando APIs de lotes e de transmissão, incluindo o Auto Loader, spark.read e COPY INTO, tudo com governança do Unity Catalog. Use estas APIs para criar Spark DataFrames, view materializadas e tabelas de transmissão diretamente a partir de arquivos no OneDrive.

A ingestão do OneDrive lê arquivos do drive pessoal de um usuário individual. Para ingerir dados de sites do SharePoint, sites de equipe ou bibliotecas de documentos compartilhados, consulte Ingest files from SharePoint em vez disso.

Escolha como ingerir do OneDrive

O Lakeflow Connect oferece duas maneiras de fazer a ingestão do OneDrive. Ambos acessam dados no OneDrive, mas diferem quanto ao nível de gerenciamento.

Opção	Descrição
Conector gerenciado do OneDrive	Um conector totalmente gerenciado para aplicativos empresariais que ingere dados em tabelas Delta e as mantém sincronizadas com a origem.
SQL e Spark API	Crie pipelines personalizados de ingestão com SQL, PySpark ou LakeFlow Pipelines usando APIs de lotes e transmissão, como read_files, spark.read, COPY INTO e Auto Loader. Oferece a flexibilidade de realizar transformações complexas durante a ingestão, ao mesmo tempo que lhe confere maior responsabilidade pelo gerenciamento e pela manutenção de seus pipelines.

Opção	Descrição
Conector gerenciado do OneDrive	Um conector totalmente gerenciado para aplicativos empresariais que ingere dados em tabelas Delta e as mantém sincronizadas com a origem.
SQL e Spark API	Crie pipelines personalizados de ingestão com SQL, PySpark ou LakeFlow Pipelines usando APIs de lotes e transmissão, como read_files, spark.read, COPY INTO e Auto Loader. Oferece a flexibilidade de realizar transformações complexas durante a ingestão, ao mesmo tempo que lhe confere maior responsabilidade pelo gerenciamento e pela manutenção de seus pipelines.

Principais recursos

As SQL e Spark API oferecem:

• Ingestão de arquivos estruturados, semiestruturados e não estruturados do OneDrive pessoal de um usuário
• Ingestão granular: ingerir um drive inteiro, uma pasta ou um único arquivo
• Ingestão em lotes e por transmissão usando spark.read, o Auto Loader e COPY INTO
• Inferência e evolução automáticas de esquema para formatos estruturados e semiestruturados, como CSV
• Armazenamento seguro de credenciais com uma conexão do Unity Catalog
• Seleção de arquivos com correspondência de padrões 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 o Databricks Runtime 19 ou acima.

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

Criar a conexão

Crie uma conexão no Unity Catalog para armazenar suas credenciais do OneDrive. A ingestão do OneDrive usa autorização OAuth de usuário para máquina (U2M) em relação ao Microsoft Entra ID (Azure AD) e ao Microsoft Graph. O processo de configuração da conexão é o mesmo, independentemente de você usar as APIs SQL e Spark API ou o conector gerenciado do OneDrive.

Para obter instruções completas sobre a configuração da conexão, incluindo as opções OAuth U2M: gerenciado pela Databricks e OAuth U2M: gerenciado de forma personalizada, consulte Criar uma conexão do OneDrive.

A conexão lê os arquivos como o usuário conectado, portanto, ela só pode acessar os arquivos que esse usuário pode acessar no OneDrive dele.

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

Os 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. Para fazer a ingestão do SharePoint, consulte Ingerir arquivos do SharePoint em vez disso.

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

Há algumas maneiras de ler arquivos do OneDrive usando Spark API e SQL.

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

A ingestão de arquivos do OneDrive com SQL e as Spark APIs requer o Databricks Runtime 19 ou acima. Para usá-lo, defina "CHANNEL" = "PREVIEW" nas configurações do pipeline. Para obter mais informações sobre os pré-lançamentos, consulte Referência das 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 SQL e Spark APIs 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 geração aumentada de recuperação (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;

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.

Análise incremental com pipelines do LakeFlow Pipelines

Você também pode usar ai_parse_document nos pipelines do LakeFlow Pipelines 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 grava 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;

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.

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

Limitações

As APIs SQL e Spark têm as seguintes limitações.

• A ingestão do OneDrive lê de um único OneDrive pessoal de um usuário ( My files ). Sites do SharePoint, sites de equipe e bibliotecas de documentos compartilhados não são suportados. Consulte Ingerir arquivos do SharePoint para esses casos.
• Listas e páginas de sites do OneDrive não são compatíveis. Apenas os arquivos armazenados no drive do OneDrive de um usuário são ingeridos.
• Você pode usar a opção pathGlobFilter para filtrar arquivos por nome. Não há suporte para filtragem baseada em caminho de pasta.
• A gravação de volta no OneDrive não é suportada. A ingestão é 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
• Saiba mais sobre a ingestão do SharePoint
• Configure o agendamento de jobs para automatizar seus fluxos de trabalho de ingestão