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 o Databricks Runtime 19 ou acima. Em uma definição de pipeline da API, defina channel como PREVIEW.

  • 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.

  1. Importe o seguinte Notebook no seu Workspace do Databricks:
Abrir notebook em uma nova abaOpen in Databricks

  1. Não modifique a célula dois.

  2. Modifique a célula três com os detalhes da configuração do seu pipeline. Consulte a referência do conector do Microsoft OneDrive e os exemplos.

  3. Clique em Executar tudo .

A execução do notebook cria o pipeline, mas não o começa. Para começar e programar o pipeline, consulte Tarefas comuns de manutenção de pipelines.

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

Python
pipeline_spec = {
  "name": "onedrive_binary_pipeline",
  "catalog": "main",
  "schema": "ingest_destination_schema",
  "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"
              }
            }
          }
        }
      }
    ]
  },
  "channel": "PREVIEW"
}

json_payload = json.dumps(pipeline_spec, indent=2)
create_pipeline(json_payload)

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.

Python
pipeline_spec = {
  "name": "onedrive_file_pipeline",
  "catalog": "<catalog>",
  "schema": "<schema>",
  "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"
              }
            }
          }
        }
      }
    ]
  },
  "channel": "PREVIEW"
}

json_payload = json.dumps(pipeline_spec, indent=2)
create_pipeline(json_payload)

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.

Python
pipeline_spec = {
  "name": "onedrive_json_pipeline",
  "catalog": "main",
  "schema": "ingest_destination_schema",
  "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"
              }
            }
          }
        }
      }
    ]
  },
  "channel": "PREVIEW"
}

json_payload = json.dumps(pipeline_spec, indent=2)
create_pipeline(json_payload)

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.

Python
pipeline_spec = {
  "name": "onedrive_metadata_pipeline",
  "catalog": "main",
  "schema": "ingest_destination_schema",
  "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"
              }
            }
          }
        }
      }
    ]
  },
  "channel": "PREVIEW"
}

json_payload = json.dumps(pipeline_spec, indent=2)
create_pipeline(json_payload)

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 trechos de código a seguir mostram o fragmento file_ingestion_options de uma definição de pipeline. Para ver todos os parâmetros, consulte Parâmetros de file_ingestion_options.

Filtros de arquivo​

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

JSON
"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.

JSON
"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:

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