Ingerir dados do Zoho Books

info

Beta

Este recurso está em Beta. To use it, a workspace admin must turn on Lakeflow Connect for Zoho Books from the Previews page. See Gerenciar Databricks previews.

Esta página mostra como criar um pipeline de ingestão gerenciado do Zoho Books usando o Lakeflow Connect.

Requisitos

• Para criar um pipeline de ingestão, primeiro atenda aos seguintes requisitos:

  • Seu workspace deve estar habilitado para o Unity Catalog.

  • O compute serverless deve ser habilitado para seu workspace. Consulte Requisitos de computação 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 suportar a criação de pipelines baseada na IU, um administrador poderá criar a conexão e o pipeline simultaneamente, ao concluir os passos nesta página. No entanto, se os usuários que criam pipelines usam a autoria de pipeline baseada em API ou são usuários não administradores, um administrador deve primeiro criar a conexão no Catalog Explorer. Consulte Conectar-se a fontes de ingestão gerenciadas.

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

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

  • É necessário ter os privilégios USE SCHEMA e CREATE TABLE em um esquema existente ou os privilégios CREATE SCHEMA no catálogo de destino.

• Para ingerir dados do Zoho Books, primeiro configure a autenticação do Databricks e crie uma conexão. Consulte Configurar a autenticação para o Zoho Books e Criar uma conexão do Zoho Books.

Opções de conector

Defina opções no escopo da tabela no objeto individual. Consulte Exemplos para obter informações sobre o uso.

Opção	Escopo	Obrigatório	Aplica-se a	Descrição
start_datetime	Tabela	Não	bills, estimates, invoices, expenses, creditnotes, customer_payments, purchase_orders, sales_orders	Data e hora mais antigas a partir das quais ingerir dados, no formato yyyy-MM-ddTHH:mm:ssZ. O default é 365 dias antes da primeira sincronização. Aplica-se apenas à primeira sincronização de cada tabela; as sincronizações posteriores são retomadas a partir do cursor armazenado.
start_date	Tabela	Não	journals, transactions	Data mais antiga a partir da qual ingerir dados, no formato yyyy-MM-dd. Essas duas tabelas rastreiam uma data em vez de um timestamp, portanto, elas aceitam um valor apenas de data. O default é 365 dias antes da primeira sincronização. Aplica-se apenas à primeira sincronização de cada tabela; as sincronizações posteriores são retomadas a partir do cursor armazenado.

Opção	Escopo	Obrigatório	Aplica-se a	Descrição
start_datetime	Tabela	Não	bills, estimates, invoices, expenses, creditnotes, customer_payments, purchase_orders, sales_orders	Data e hora mais antigas a partir das quais ingerir dados, no formato yyyy-MM-ddTHH:mm:ssZ. O default é 365 dias antes da primeira sincronização. Aplica-se apenas à primeira sincronização de cada tabela; as sincronizações posteriores são retomadas a partir do cursor armazenado.
start_date	Tabela	Não	journals, transactions	Data mais antiga a partir da qual ingerir dados, no formato yyyy-MM-dd. Essas duas tabelas rastreiam uma data em vez de um timestamp, portanto, elas aceitam um valor apenas de data. O default é 365 dias antes da primeira sincronização. Aplica-se apenas à primeira sincronização de cada tabela; as sincronizações posteriores são retomadas a partir do cursor armazenado.

Criar pipeline de ingestão

Para obter a lista de tabelas de origem compatíveis, consulte Tabelas de origem compatíveis.

Databricks UI

1. Na barra lateral do workspace do Databricks, clique em Ingestão de dados .
2. Na página Adicionar dados , em conectores do Databricks , clique em Zoho Books .
3. Na página Conexão do assistente de ingestão, selecione a conexão que armazena suas credenciais do Zoho Books. Se tiver o privilégio CREATE CONNECTION no metastore, clique em Criar conexão para criar uma conexão com as credenciais de Configurar autenticação para Zoho Books.
4. Clique em Avançar .
5. Na página de **Configuração de ingestão**, insira um nome para o pipeline.
6. Selecione um catálogo e um esquema onde os logs de eventos serão gravados. Se tiver os privilégios USE CATALOG e CREATE SCHEMA no catálogo, clique em Criar esquema no menu suspenso para criar um esquema.
7. Clique em **Criar pipeline e continuar**.
8. Na **Página de Origem**, selecione as tabelas para ingestão.
9. Clique em Salvar e continuar .
10. Na página Destino , selecione um catálogo e um esquema para carregar dados. Se você tiver privilégios USE CATALOG e CREATE SCHEMA no catálogo, clique em Criar esquema no menu suspenso para criar um esquema.
11. Clique em Salvar e continuar .
12. (Opcional) Na página Cronogramas e notificações , clique em Crie um agendamento . Defina a frequência para fazer o refresh das tabelas de destino.
13. (Opcional) Clique em Adicionar notificação para configurar notificações por email para sucesso ou falha da operação do pipeline e, em seguida, clique em Salvar e executar pipeline .

Declarative Automation Bundles

Use os Bundles de Automação Declarativa para gerenciar pipelines do Zoho Books 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 executados em diferentes workspaces de destino (como desenvolvimento, preparo e produção). Para obter mais informações, consulte O que são Pacotes de Automação Declarativa?.

1. Crie um pacote utilizando a CLI do Databricks:

   Bash

   databricks bundle init

2. Adicione dois novos arquivos de recurso ao pacote:

   • Um arquivo de definição de pipeline (por exemplo, resources/zoho_books_pipeline.yml). Veja pipeline.definição_de_ingestão e Exemplos.
   • Um arquivo de definição de Job que controla a frequência da ingestão de dados (por exemplo, resources/zoho_books_job.yml).

3. Implante o pipeline usando a CLI do Databricks:

   Bash

   databricks bundle deploy

Databricks notebook

1. Importe o seguinte notebook em seu workspace do Databricks:

Abrir notebook em uma nova abaOpen in Databricks

2. Deixe as células um e dois como estão. Não modifique.

3. Modificar a célula três com os detalhes da configuração do pipeline. Veja pipeline.ingestion_definition e Exemplos.

4. Configure as configurações avançadas do pipeline (opcional). Consulte Padrões comuns para pipelines de ingestão gerenciados.

5. Clique em Executar tudo .

Exemplos

O conector Zoho Books disponibiliza 16 tabelas de origem no esquema de origem default. Ingerir tabelas individuais ou o esquema inteiro.

Ingerir tabelas específicas

Use esta opção para ingerir um subconjunto específico de tabelas, ou para personalizar a nomenclatura de destino por tabela.

Declarative Automation Bundles

O seguinte arquivo de definição de pipeline ingere tabelas individuais do Zoho Books:

YAML

resources:
  pipelines:
    zoho_books_pipeline:
      name: zoho_books_pipeline
      catalog: 'main'
      target: 'zoho_books_data'
      ingestion_definition:
        connection_name: zoho_books_connection
        objects:
          - table:
              source_schema: 'default'
              source_table: 'invoices'
              destination_catalog: 'main'
              destination_schema: 'zoho_books_data'
              destination_table: 'invoices'
          - table:
              source_schema: 'default'
              source_table: 'bills'
              destination_catalog: 'main'
              destination_schema: 'zoho_books_data'
              destination_table: 'bills'
          - table:
              source_schema: 'default'
              source_table: 'contacts'
              destination_catalog: 'main'
              destination_schema: 'zoho_books_data'
              destination_table: 'contacts'

Databricks notebook

A seguinte especificação de pipeline ingere tabelas individuais do Zoho Books:

Python

pipeline_name = "zoho_books_pipeline"
connection_name = "<zoho-books-connection>"
pipeline_spec = {
  "name": pipeline_name,
  "ingestion_definition": {
    "connection_name": connection_name,
    "objects": [
      {
        "table": {
          "source_schema": "default",
          "source_table": "invoices",
          "destination_catalog": "main",
          "destination_schema": "zoho_books_data",
          "destination_table": "invoices"
        }
      },
      {
        "table": {
          "source_schema": "default",
          "source_table": "bills",
          "destination_catalog": "main",
          "destination_schema": "zoho_books_data",
          "destination_table": "bills"
        }
      },
      {
        "table": {
          "source_schema": "default",
          "source_table": "contacts",
          "destination_catalog": "main",
          "destination_schema": "zoho_books_data",
          "destination_table": "contacts"
        }
      }
    ]
  }
}
json_payload = json.dumps(pipeline_spec, indent=2)
create_pipeline(json_payload)

Ingerir a partir de uma data de início específica

Use start_datetime ou start_date para controlar até onde uma tabela lê na sua primeira sincronização. Defina a opção em cada tabela que deseja limitar e use aquela que corresponde ao cursor da tabela: start_datetime para tabelas baseadas em Timestamp, start_date para journals e transactions.

Declarative Automation Bundles

O seguinte arquivo de definição de pipeline dos Pacotes de Automação Declarativa ingere tabelas do Zoho Books a partir de uma data de início específica:

YAML

resources:
  pipelines:
    zoho_books_pipeline:
      name: zoho_books_pipeline
      catalog: 'main'
      target: 'zoho_books_data'
      ingestion_definition:
        connection_name: zoho_books_connection
        objects:
          - table:
              source_schema: 'default'
              source_table: 'invoices'
              destination_catalog: 'main'
              destination_schema: 'zoho_books_data'
              destination_table: 'invoices'
              connector_options:
                api_source_connector_options:
                  options:
                    start_datetime: '<start-datetime>'
          - table:
              source_schema: 'default'
              source_table: 'journals'
              destination_catalog: 'main'
              destination_schema: 'zoho_books_data'
              destination_table: 'journals'
              connector_options:
                api_source_connector_options:
                  options:
                    start_date: '<start-date>'

Databricks notebook

A seguinte especificação de pipeline ingere tabelas do Zoho Books a partir de uma data de início específica:

Python

pipeline_name = "zoho_books_pipeline"
connection_name = "<zoho-books-connection>"
pipeline_spec = {
  "name": pipeline_name,
  "ingestion_definition": {
    "connection_name": connection_name,
    "objects": [
      {
        "table": {
          "source_schema": "default",
          "source_table": "invoices",
          "destination_catalog": "main",
          "destination_schema": "zoho_books_data",
          "destination_table": "invoices",
          "connector_options": {
            "api_source_connector_options": {
              "options": {
                "start_datetime": "<start-datetime>"
              }
            }
          }
        }
      },
      {
        "table": {
          "source_schema": "default",
          "source_table": "journals",
          "destination_catalog": "main",
          "destination_schema": "zoho_books_data",
          "destination_table": "journals",
          "connector_options": {
            "api_source_connector_options": {
              "options": {
                "start_date": "<start-date>"
              }
            }
          }
        }
      }
    ]
  }
}
json_payload = json.dumps(pipeline_spec, indent=2)
create_pipeline(json_payload)

Ingerir o esquema inteiro

Use esta opção para ingerir todas as tabelas de origem do Zoho Books em um único esquema de destino com uma declaração.

Declarative Automation Bundles

O seguinte arquivo de definição de pipeline ingere todas as tabelas compatíveis do Zoho Books em um esquema de destino:

YAML

resources:
  pipelines:
    zoho_books_pipeline:
      name: zoho_books_pipeline
      catalog: 'main'
      target: 'zoho_books_data'
      ingestion_definition:
        connection_name: zoho_books_connection
        objects:
          - schema:
              source_schema: 'default'
              destination_catalog: 'main'
              destination_schema: 'zoho_books_data'

Databricks notebook

A seguinte especificação de pipeline ingere todas as tabelas compatíveis do Zoho Books em um esquema de destino:

Python

pipeline_name = "zoho_books_pipeline"
connection_name = "<zoho-books-connection>"
pipeline_spec = {
  "name": pipeline_name,
  "ingestion_definition": {
    "connection_name": connection_name,
    "objects": [
      {
        "schema": {
          "source_schema": "default",
          "destination_catalog": "main",
          "destination_schema": "zoho_books_data"
        }
      }
    ]
  }
}
json_payload = json.dumps(pipeline_spec, indent=2)
create_pipeline(json_payload)

Arquivo de definição de Job de Pacotes de Automação Declarativa

O seguinte é um exemplo de arquivo de definição de job para uso com Pacotes de Automação Declarativa. O Job é executado diariamente.

Declarative Automation Bundles

YAML

resources:
  jobs:
    zoho_books_job:
      name: zoho_books_job
      schedule:
        quartz_cron_expression: '0 0 0 * * ?'
        timezone_id: 'UTC'
      tasks:
        - task_key: zoho_books_ingestion
          pipeline_task:
            pipeline_id: ${resources.pipelines.zoho_books_pipeline.id}

Padrões comuns

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

Passos seguintes

Iniciar, programar e definir alertas no seu pipeline. Veja Tarefas comuns de manutenção de pipelines.

Recursos adicionais

• Perguntas frequentes sobre o conector do Zoho Books
• Limitações do conector do Zoho Books
• Referência do conector do Zoho Books
• Solucionar problemas do conector Zoho Books