Ingerir dados do Xero

info

Beta

Este recurso está em Beta. Para usá-lo, um administrador de workspace deve habilitar o Lakeflow Connect para Xero na página Prévias . Consulte Gerenciar prévias do Databricks.

Crie um pipeline gerenciado do Lakeflow Connect que ingere dados do Xero em tabelas do Unity Catalog. Use a interface de usuário do Databricks, pacotes de automação declarativa ou um notebook do Databricks.

Requisitos

• Para criar um pipeline de ingestão, primeiro cumpra os 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 privilégios de CREATE CONNECTION no metastore. Consulte Gerenciar privilégios no Unity Catalog.

    Se o conector suportar a criação de pipeline baseada em interface do usuário, um administrador pode criar a conexão e o pipeline ao mesmo tempo completando os passos nesta página. No entanto, se os usuários que criam pipelines usarem a criação de pipeline baseada em API ou não forem usuários 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, você deve 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.

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

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

• Observe a ID do tenant da organização Xero a ser ingerida. Veja Encontrar a ID do tenant.

Opções de conector

Para obter as opções que o conector do Xero aceita, seu escopo e as tabelas às quais eles se aplicam, consulte Opções de conector. Defina as opções no escopo do pipeline em source_configurations. Todo pipeline deve definir tenant_id. Consulte Exemplos para ver o uso.

Criar um pipeline de ingestão

Para obter uma lista das tabelas de origem suportadas, consulte Tabelas de origem suportadas.

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 Xero .
3. Na página Conexão do assistente de ingestão, selecione a conexão que armazena suas credenciais do Xero. Se você 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 no Xero.
4. Clique em Avançar .
5. Na página Configuração da ingestão , insira um nome para o pipeline.
6. Selecione um catálogo e um esquema nos quais gravar logs de eventos. Se você tiver privilégios USE CATALOG e CREATE SCHEMA no catálogo, clique em Criar esquema no menu suspenso para criar um esquema.
7. Para ID do tenant , insira o ID do tenant da organização Xero a ser ingerida. Opcionalmente, defina uma Data e hora de início . Consulte Opções de conector.
8. Clique em Criar pipeline e continuar .
9. Na página Origem , selecione as tabelas para ingestão.
10. Clique em Salvar e continuar .
11. Na página Destino , selecione um catálogo e um schema para carregar os dados. Se você tiver privilégios USE CATALOG e CREATE SCHEMA no catálogo, clique em Criar schema no menu suspenso para criar um schema.
12. Clique em Salvar e continuar .
13. (Opcional) Na página programar e notificações , clique em Criar programar . Defina a frequência para refresh as tabelas de destino.
14. (Opcional) Clique em Adicionar notificação para configurar notificações por email para sucesso ou falha da operação do pipeline e clique em Salvar e iniciar a execução do pipeline .

Declarative Automation Bundles

Use os Pacotes de Automação Declarativa para gerenciar pipelines do Xero 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 bundle usando 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/xero_pipeline.yml). Consulte pipeline.ingestion_definition e Exemplos.
   • Um arquivo de definição de job que controla a frequência de ingestão de dados (por exemplo, resources/xero_job.yml).

3. Implante o pipeline usando a CLI do Databricks:

   Bash

   databricks bundle deploy

Databricks notebook

1. Importe o seguinte Notebook para o seu workspace do Databricks:

Abrir notebook em uma nova abaOpen in Databricks

2. Deixe as três primeiras células como estão.

3. Modifique a quarta célula, que define pipeline_spec, com os detalhes da configuração do seu pipeline. Consulte pipeline.ingestion_definition e Exemplos.

4. Opcionalmente, configure as configurações avançadas do pipeline. Consulte Padrões comuns para pipelines de ingestão gerenciados.

5. Clique em Executar tudo .

Exemplos

O conector Xero disponibiliza 23 tabelas de origem no esquema de origem default. Especifique cada tabela que deseja ingerir e defina tenant_id para a organização a ser ingerida.

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 arquivo de definição de pipeline a seguir ingere tabelas individuais do Xero:

YAML

resources:
  pipelines:
    xero_pipeline:
      name: xero_pipeline
      catalog: 'main'
      target: 'xero_data'
      ingestion_definition:
        connection_name: xero_connection
        source_configurations:
          - api_source_connector_config:
              configs:
                tenant_id: '<tenant-id>'
        objects:
          - table:
              source_schema: 'default'
              source_table: 'invoices'
              destination_catalog: 'main'
              destination_schema: 'xero_data'
              destination_table: 'invoices'
          - table:
              source_schema: 'default'
              source_table: 'contacts'
              destination_catalog: 'main'
              destination_schema: 'xero_data'
              destination_table: 'contacts'
          - table:
              source_schema: 'default'
              source_table: 'payments'
              destination_catalog: 'main'
              destination_schema: 'xero_data'
              destination_table: 'payments'

Databricks notebook

A especificação de pipeline a seguir ingere tabelas Xero individuais:

Python

pipeline_name = "xero_pipeline"
connection_name = "<xero-connection>"
pipeline_spec = {
  "name": pipeline_name,
  "ingestion_definition": {
    "connection_name": connection_name,
    "source_configurations": [
      {
        "api_source_connector_config": {
          "configs": {
            "tenant_id": "<tenant-id>"
          }
        }
      }
    ],
    "objects": [
      {
        "table": {
          "source_schema": "default",
          "source_table": "invoices",
          "destination_catalog": "main",
          "destination_schema": "xero_data",
          "destination_table": "invoices"
        }
      },
      {
        "table": {
          "source_schema": "default",
          "source_table": "contacts",
          "destination_catalog": "main",
          "destination_schema": "xero_data",
          "destination_table": "contacts"
        }
      },
      {
        "table": {
          "source_schema": "default",
          "source_table": "payments",
          "destination_catalog": "main",
          "destination_schema": "xero_data",
          "destination_table": "payments"
        }
      }
    ]
  }
}
json_payload = json.dumps(pipeline_spec, indent=2)
create_pipeline(json_payload)

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

Use a opção start_datetime para controlar até onde as tabelas incrementais leem em sua primeira sincronização.

Declarative Automation Bundles

O arquivo de definição de pipeline a seguir ingere tabelas do Xero a partir de uma data de início específica:

YAML

resources:
  pipelines:
    xero_pipeline:
      name: xero_pipeline
      catalog: 'main'
      target: 'xero_data'
      ingestion_definition:
        connection_name: xero_connection
        source_configurations:
          - api_source_connector_config:
              configs:
                tenant_id: '<tenant-id>'
                start_datetime: '<start-datetime>'
        objects:
          - table:
              source_schema: 'default'
              source_table: 'invoices'
              destination_catalog: 'main'
              destination_schema: 'xero_data'
              destination_table: 'invoices'
          - table:
              source_schema: 'default'
              source_table: 'contacts'
              destination_catalog: 'main'
              destination_schema: 'xero_data'
              destination_table: 'contacts'
          - table:
              source_schema: 'default'
              source_table: 'payments'
              destination_catalog: 'main'
              destination_schema: 'xero_data'
              destination_table: 'payments'

Databricks notebook

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

Python

pipeline_name = "xero_pipeline"
connection_name = "<xero-connection>"
pipeline_spec = {
  "name": pipeline_name,
  "ingestion_definition": {
    "connection_name": connection_name,
    "source_configurations": [
      {
        "api_source_connector_config": {
          "configs": {
            "tenant_id": "<tenant-id>",
            "start_datetime": "<start-datetime>"
          }
        }
      }
    ],
    "objects": [
      {
        "table": {
          "source_schema": "default",
          "source_table": "invoices",
          "destination_catalog": "main",
          "destination_schema": "xero_data",
          "destination_table": "invoices"
        }
      },
      {
        "table": {
          "source_schema": "default",
          "source_table": "contacts",
          "destination_catalog": "main",
          "destination_schema": "xero_data",
          "destination_table": "contacts"
        }
      },
      {
        "table": {
          "source_schema": "default",
          "source_table": "payments",
          "destination_catalog": "main",
          "destination_schema": "xero_data",
          "destination_table": "payments"
        }
      }
    ]
  }
}
json_payload = json.dumps(pipeline_spec, indent=2)
create_pipeline(json_payload)

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

Abaixo está um exemplo de arquivo de definição de job para uso com Declarative Automation Bundles. O Job é execução diariamente.

Declarative Automation Bundles

YAML

resources:
  jobs:
    xero_job:
      name: xero_job
      schedule:
        quartz_cron_expression: '0 0 0 * * ?'
        timezone_id: 'UTC'
      tasks:
        - task_key: xero_ingestion
          pipeline_task:
            pipeline_id: ${resources.pipelines.xero_pipeline.id}

Padrões comuns

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

Os passos seguintes

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

Outros recursos

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