Pular para o conteúdo principal
Última atualização em

Ingerir dados do OneDrive

info

Beta

Este recurso está em beta. Os administradores do Workspace podem controlar o acesso a este recurso na página Pré-visualizações ao optar pela prévia do Lakeflow Connect for OneDrive For Business . Consulte Gerenciar prévias do Databricks.

Esta página mostra como criar um pipeline de ingestão gerenciada do Microsoft OneDrive usando o Lakeflow Connect. O pipeline ingere arquivos do OneDrive em tabelas Delta e as mantém sincronizadas com a origem.

Antes de começar​

  • Para criar o pipeline de ingestão, você deve primeiro atender aos seguintes requisitos:

    • Seu workspace deve estar habilitado para o Unity Catalog.

    • O compute serverless deve estar habilitado para seu workspace. Consulte Requisitos de compute serverless.

    • Para criar uma nova conexão, você deve ter os privilégios CREATE CONNECTION no metastore. Consulte Gerenciar privilégios no Unity Catalog.

      Se o conector for compatível com a criação de pipelines baseada na IU, um administrador poderá criar a conexão e o pipeline ao mesmo tempo concluindo os passos desta página. No entanto, se os usuários que criam pipelines usarem a criação de pipelines baseada em API ou não forem administradores, um administrador deverá primeiro criar a conexão no Catalog Explorer. Consulte Conectar-se a fontes de ingestão gerenciadas.

    • Para usar uma conexão existente, você deve ter os privilégios USE CONNECTION ou ALL PRIVILEGES no objeto de conexão.

    • Você deve ter os privilégios USE CATALOG no catálogo de destino.

    • Você deve ter os privilégios USE SCHEMA e CREATE TABLE em um esquema existente ou os privilégios CREATE SCHEMA no catálogo de destino.

  • Use Databricks Runtime 19 ou acima. Em uma definição de pipeline de API ou Pacotes de Automação Declarativa, defina channel como PREVIEW.

  • Para usar Pacotes de Automação Declarativa, use a versão 1.23.0 ou acima da CLI do Databricks. Versões anteriores removem onedrive_options da definição do pipeline.

  • Para ingerir dados do OneDrive, primeiro configure um método de autenticação compatível e crie uma conexão. Consulte Criar uma conexão do OneDrive.

Criar pipeline de ingestão​

Para obter uma lista dos formatos de arquivo compatíveis, consulte parâmetros de file_ingestion_options. Para ver as limitações específicas do conector, consulte limitações do conector do Microsoft OneDrive.

Use os Pacotes de Automação Declarativa para gerenciar pipelines do OneDrive como código. Os pacotes podem conter definições YAML de Jobs e tarefas, são gerenciados usando a CLI do Databricks e podem ser compartilhados e ter execução em diferentes Workspace de destino (como desenvolvimento, staging e produção). Consulte O que são os Pacotes de Automação Declarativa?.

  1. Crie um pacote usando a CLI do Databricks:

    Bash
    databricks bundle init

  2. Adicione dois novos arquivos de recursos ao pacote:

  3. Implante o pipeline usando a CLI do Databricks:

    Bash
    databricks bundle deploy

A implantação do bundle cria o pipeline e o job. O Job executa o pipeline ao programar da definição do Job.

Escolha um URL de origem​

Cada objeto em uma definição de pipeline especifica sua origem em connector_options.onedrive_options.url. A URL deve resolver para um dos seguintes recursos em uma unidade Meus arquivos do OneDrive for Business:

  • A raiz da unidade
  • Uma pasta
  • Um arquivo
  • Um link de compartilhamento válido

O URL deve usar um host pessoal do OneDrive, como <tenant>-my.sharepoint.com. Os URLs a seguir não são compatíveis:

  • URLs de sites do SharePoint (/sites/...)
  • URLs do OneDrive do consumidor, como onedrive.live.com ou 1drv.ms
  • URLs de host simples
  • Caminhos fora de uma unidade pessoal

Para obter exemplos de URLs e instruções para copiar um URL do OneDrive, consulte Ler arquivos do OneDrive.

Exemplos​

Use estes exemplos para configurar seu pipeline. Substitua cada espaço reservado por valores para seu ambiente.

Ingerir arquivos como dados não estruturados​

Ingira arquivos do OneDrive como conteúdo binário. Cada arquivo se torna uma linha que contém os bytes e os metadados do arquivo. Use esta abordagem para PDFs, documentos do Office, imagens e outros arquivos que você pretende processar posteriormente, por exemplo, para aplicativos RAG.

nota

Disponível na versão Beta, o tipo FILE armazena uma referência governada a cada arquivo e seus metadados, em vez dos bytes do arquivo, o que melhora o desempenho de leitura. Para ingerir arquivos como o tipo FILE em vez de BINARYFILE, consulte Ingerir arquivos como o tipo FILE (Beta).

YAML
resources:
  pipelines:
    onedrive_binary_pipeline:
      name: onedrive_binary_pipeline
      catalog: main
      schema: ingest_destination_schema
      channel: PREVIEW
      ingestion_definition:
        connection_name: <onedrive-connection>
        objects:
          - table:
              destination_catalog: main
              destination_schema: ingest_destination_schema
              destination_table: drive_files
              connector_options:
                onedrive_options:
                  entity_type: FILE
                  url: https://mytenant-my.sharepoint.com/personal/user_mytenant_onmicrosoft_com/Documents
                  file_ingestion_options:
                    format: BINARYFILE
                    schema_evolution_mode: NONE

Ingerir arquivos como tipo FILE (Beta)​

info

Beta

Esse recurso está na versão beta.

Ingerir arquivos como o tipo FILE para copiar cada arquivo de origem para um volume do Unity Catalog e armazenar uma referência governada a cada arquivo e aos respectivos metadados na tabela de destino. A tabela de destino expõe uma coluna file que você pode passar para funções como ai_parse_document e para funções definidas pelo usuário (UDFs).

Para usar o tipo FILE, configure o seguinte no pipeline:

  • Defina o pipeline channel como PREVIEW.
  • Defina file_ingestion_options.format como FILE.
  • Defina a propriedade de tabela databricks.filespace-preview para declarar o volume que o Unity Catalog usa como armazenamento gerenciado.

Para obter os requisitos e o comportamento de FILE, consulte Ingerir arquivos como tipo FILE.

YAML
resources:
  pipelines:
    onedrive_file_pipeline:
      name: onedrive_file_pipeline
      catalog: <catalog>
      schema: <schema>
      channel: PREVIEW
      ingestion_definition:
        connection_name: <onedrive-connection>
        objects:
          - table:
              destination_catalog: <catalog>
              destination_schema: <schema>
              destination_table: <destination-table>
              table_configuration:
                table_properties:
                  databricks.filespace-preview: /Volumes/<catalog>/<schema>/<volume>/
              connector_options:
                onedrive_options:
                  entity_type: FILE
                  url: https://mytenant-my.sharepoint.com/personal/user_mytenant_onmicrosoft_com/Documents
                  file_ingestion_options:
                    format: FILE
                    schema_evolution_mode: NONE

Ingerir arquivos estruturados​

Ingerir arquivos estruturados (por exemplo, arquivos JSON) de uma pasta do OneDrive. Cada linha nos arquivos de origem se torna uma linha na tabela de destino.

YAML
resources:
  pipelines:
    onedrive_json_pipeline:
      name: onedrive_json_pipeline
      catalog: main
      schema: ingest_destination_schema
      channel: PREVIEW
      ingestion_definition:
        connection_name: <onedrive-connection>
        objects:
          - table:
              destination_catalog: main
              destination_schema: ingest_destination_schema
              destination_table: json_files
              connector_options:
                onedrive_options:
                  entity_type: FILE
                  url: https://mytenant-my.sharepoint.com/personal/user_mytenant_onmicrosoft_com/Documents/json_folder
                  file_ingestion_options:
                    format: JSON
                    schema_evolution_mode: NONE

Ingerir somente metadados do arquivo​

Ingerir metadados de arquivo (nome, tamanho, Timestamp, caminho) sem fazer download do conteúdo dos arquivos. Use esta abordagem quando precisar de um inventário de arquivos sem a sobrecarga de ingerir seu conteúdo.

Defina entity_type como FILE_METADATA. A ingestão de FILE_METADATA deve usar o formato BINARYFILE. Os formatos estruturados e semiestruturados não são compatíveis com a ingestão somente de metadados.

YAML
resources:
  pipelines:
    onedrive_metadata_pipeline:
      name: onedrive_metadata_pipeline
      catalog: main
      schema: ingest_destination_schema
      channel: PREVIEW
      ingestion_definition:
        connection_name: <onedrive-connection>
        objects:
          - table:
              destination_catalog: main
              destination_schema: ingest_destination_schema
              destination_table: file_metadata
              connector_options:
                onedrive_options:
                  entity_type: FILE_METADATA
                  url: https://mytenant-my.sharepoint.com/personal/user_mytenant_onmicrosoft_com/Documents
                  file_ingestion_options:
                    format: BINARYFILE
                    schema_evolution_mode: NONE

Arquivo de definição de job de Pacotes de Automação Declarativa​

Este arquivo de definição de job de exemplo executa o pipeline todos os dias. Ele faz refresh do pipeline de Ingerir arquivos como dados não estruturados. Para fazer refresh de um pipeline diferente, substitua onedrive_binary_pipeline pelo key de recurso desse pipeline.

YAML
resources:
  jobs:
    onedrive_job:
      name: onedrive_job

      trigger:
        periodic:
          interval: 1
          unit: DAYS

      email_notifications:
        on_failure:
          - <email-address>

      tasks:
        - task_key: refresh_pipeline
          pipeline_task:
            pipeline_id: ${resources.pipelines.onedrive_binary_pipeline.id}

Configurar opções de ingestão de arquivos​

O bloco file_ingestion_options controla como os arquivos são processados. Todas as opções são definidas dentro do bloco connector_options.onedrive_options.file_ingestion_options na definição do pipeline. Os snippets a seguir usam a sintaxe YAML do Declarative Automation Bundles. Em uma definição de notebook ou pipeline de API, use as mesmas key no JSON. Para todos os parâmetros, consulte parâmetros file_ingestion_options.

Filtros de arquivo​

Use file_filters para restringir os arquivos ingeridos do URL de origem:

YAML
file_ingestion_options:
  format: CSV
  file_filters:
    - path_filter: invoices/*.csv
    - modified_after: 2026-01-01T00:00:00

Evolução do esquema e dicas de esquema​

Defina schema_evolution_mode para controlar como as novas colunas nos arquivos recebidos são tratadas. Substitua os tipos de coluna inferidos usando schema_hints.

A evolução do esquema se aplica somente a CSV, JSON, XML, PARQUET e AVRO. Para outros formatos (BINARYFILE, FILE, EXCEL e ORC), defina schema_evolution_mode como NONE.

YAML
file_ingestion_options:
  format: CSV
  schema_evolution_mode: ADD_NEW_COLUMNS_WITH_TYPE_WIDENING
  schema_hints: order_id INT, amount DOUBLE, ts TIMESTAMP

Para obter mais informações sobre a evolução do esquema e as dicas de esquema, consulte Configurar a inferência e a evolução do esquema no Auto Loader.

Opções específicas do formato​

Passe opções específicas do formato usando format_options:

YAML
file_ingestion_options:
  format: CSV
  format_options:
    header: 'true'
    sep: ','

Os keys compatíveis são as opções de formato padrão do Auto Loader. Consulte opções de fonte de dados do Spark.

Padrões comuns​

Para configurações avançadas de pipeline, consulte Padrões comuns para pipelines de ingestão gerenciados.

Próximos os passos​

Comece, programe e defina alertas no seu pipeline. Consulte Tarefas comuns de manutenção de pipeline.

Outros recursos​

Nesta página