Copiar dados do Xero usando o Azure Data Factory ou o Synapse Analytics

APLICA-SE A: Azure Data Factory Azure Synapse Analytics

Este artigo descreve como usar a Atividade de Cópia em um pipeline do Azure Data Factory ou do Synapse Analytics para copiar dados do Xero. Ele se baseia no artigo de visão geral da atividade de cópia que apresenta uma visão geral da atividade de cópia.

Capacidades suportadas

Este conector Xero é suportado para as seguintes capacidades:

(1) Tempo de execução de integração do Azure (2) Tempo de execução de integração auto-hospedado

Para obter uma lista de armazenamentos de dados suportados como fontes/coletores, consulte a tabela Armazenamentos de dados suportados.

Especificamente, este conector Xero suporta:

• Autenticação OAuth 2.0.
• Todas as tabelas Xero (pontos de extremidade API), exceto "Relatórios".
• Versões do Windows neste artigo.

Introdução

Para executar a atividade de cópia com um pipeline, você pode usar uma das seguintes ferramentas ou SDKs:

• Ferramenta Copiar dados
• portal do Azure
• SDK do .NET
• Python SDK
• Azure PowerShell
• API REST
• Modelo Azure Resource Manager

Criar um serviço vinculado ao Xero usando a interface do usuário

Use as etapas a seguir para criar um serviço vinculado ao Xero na interface do usuário do portal do Azure.

1. Navegue até a guia Gerenciar em seu espaço de trabalho do Azure Data Factory ou Synapse e selecione Serviços Vinculados e clique em Novo:

   • Fábrica de Dados do Azure
   • Azure Synapse

   

2. Procure Xero e selecione o conector Xero.

   

3. Configure os detalhes do serviço, teste a conexão e crie o novo serviço vinculado.

   

Detalhes de configuração do conector

As seções a seguir fornecem detalhes sobre as propriedades que são usadas para definir entidades do Data Factory específicas para o conector Xero.

Propriedades do serviço vinculado

O conector Xero agora suporta a versão 2.0. Consulte esta seção para fazer a atualização do conector Xero a partir da versão 1.0. Para obter os detalhes da propriedade, consulte as seções correspondentes.

• Versão 2.0
• Versão 1.0

Versão 2.0

O serviço Xero ligado suporta as seguintes propriedades ao utilizar a versão 2.0.

Exemplo:

{
    "name": "XeroLinkedService",
    "properties": {
        "type": "Xero",
        "typeProperties": {
            "host": "api.xero.com",
            "clientId": "<client ID>",
            "clientSecret": "<client secret>",
            "tenantId": "<tenant ID>", 
            "refreshToken": {
                "type": "SecureString",
                "value": "<refresh token>"
            },
            "authenticationType":"OAuth_2.0", 
            "version": "2.0"         
        }
    }
}

Versão 1.0

O serviço associado Xero suporta as seguintes propriedades ao utilizar a versão 1.0:

Exemplo: autenticação OAuth 2.0

{
    "name": "XeroLinkedService",
    "properties": {
        "type": "Xero",
        "typeProperties": {
            "connectionProperties": { 
                "host": "api.xero.com",
                "authenticationType":"OAuth_2.0", 
                "consumerKey": {
                    "type": "SecureString",
                    "value": "<client ID>"
                },
                "privateKey": {
                    "type": "SecureString",
                    "value": "<client secret>"
                },
                "tenantId": "<tenant ID>", 
                "refreshToken": {
                    "type": "SecureString",
                    "value": "<refresh token>"
                }, 
                "useEncryptedEndpoints": true, 
                "useHostVerification": true, 
                "usePeerVerification": true
            }            
        }
    }
}

Exemplo: autenticação OAuth 1.0

{
    "name": "XeroLinkedService",
    "properties": {
        "type": "Xero",
        "typeProperties": {
            "connectionProperties": {
                "host": "api.xero.com", 
                "authenticationType":"OAuth_1.0", 
                "consumerKey": {
                    "type": "SecureString",
                    "value": "<consumer key>"
                },
                "privateKey": {
                    "type": "SecureString",
                    "value": "<private key>"
                }, 
                "useEncryptedEndpoints": true,
                "useHostVerification": true,
                "usePeerVerification": true
            }
        }
    }
}

Exemplo de valor de chave privada:

Inclua todo o texto do arquivo .pem, incluindo as terminações de linha Unix(\n).

"-----BEGIN RSA PRIVATE KEY-----\nMII***************************************************P\nbu****************************************************s\nU/****************************************************B\nA*****************************************************W\njH****************************************************e\nsx*****************************************************l\nq******************************************************X\nh*****************************************************i\nd*****************************************************s\nA*****************************************************dsfb\nN*****************************************************M\np*****************************************************Ly\nK*****************************************************Y=\n-----END RSA PRIVATE KEY-----"

Propriedades do conjunto de dados

Para obter uma lista completa de seções e propriedades disponíveis para definir conjuntos de dados, consulte o artigo sobre conjuntos de dados. Esta seção fornece uma lista de propriedades suportadas pelo conjunto de dados Xero.

Para copiar dados do Xero, defina a propriedade type do conjunto de dados como XeroObject. As seguintes propriedades são suportadas:

Exemplo

{
    "name": "XeroDataset",
    "properties": {
        "type": "XeroObject",
        "typeProperties": {},
        "schema": [],
        "linkedServiceName": {
            "referenceName": "<Xero linked service name>",
            "type": "LinkedServiceReference"
        }
    }
}

O conector versão 2.0 suporta as seguintes tabelas Xero:

• Accounts
• Itens_de_Linha_de_Transação_Bancária
• Transferências_Bancárias
• Orçamentos
• Contacts_Addresses
• Grupo_de_Contatos
• Contacts_Phones
• Itens_da_Nota_de_Crédito
• Rastreamento_de_Itens_de_Linha_de_Notas_de_Crédito
• Moedas
• Itens_de_Linha_da_Fatura
• Rastreamento_de_Itens_de_Linha_da_Fatura
• Itens
• Diários
• Linhas do Diário
• Categorias_de_Rastreio_de_Linha_do_Jornal
• Manual_Journals
• Linhas_de_Jornal_Manual
• Organizações
• Itens_de_Linha_de_Prepagamento
• Projetos
• Utilizadores do Projeto
• Itens_de_Linha_de_Ordem_de_Compra
• Taxas_Fiscais
• Tracking_Categories
• Opções_de_Categorias_de_Rastreamento
• Utilizadores

Propriedades da atividade Copy

Para obter uma lista completa de seções e propriedades disponíveis para definir atividades, consulte o artigo Pipelines . Esta seção fornece uma lista de propriedades suportadas pela fonte Xero.

Xero como fonte

Para copiar dados do Xero, defina o tipo de origem na atividade de cópia como XeroSource. As seguintes propriedades são suportadas na seção de origem da atividade de cópia:

Exemplo:

"activities":[
    {
        "name": "CopyFromXero",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<Xero input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "XeroSource",
                "query": "SELECT * FROM Contacts"
            },
            "sink": {
                "type": "<sink type>"
            }
        }
    }
]

Observe o seguinte ao especificar a consulta Xero:

• As tabelas com itens complexos serão divididas em várias tabelas. Por exemplo, as transações bancárias têm uma estrutura de dados complexa "LineItems", de modo que os dados da transação bancária são mapeados para a tabela Bank_Transaction e Bank_Transaction_Line_Items, com Bank_Transaction_ID como chave estrangeira para vinculá-los.

• Os dados do Xero estão disponíveis através de dois esquemas: Minimal (padrão) e Complete. O esquema completo contém tabelas de chamada de pré-requisito que exigem dados adicionais (por exemplo, coluna ID) antes de fazer a consulta desejada.

As tabelas a seguir têm as mesmas informações no esquema Mínimo e Completo. Para reduzir o número de chamadas de API, use Esquema mínimo (padrão).

• Bank_Transactions
• Contact_Groups
• Contactos
• Contacts_Sales_Tracking_Categories
• Contacts_Phones
• Contacts_Addresses
• Contacts_Purchases_Tracking_Categories
• Credit_Notes
• Credit_Notes_Allocations
• Expense_Claims
• Expense_Claim_Validation_Errors
• Faturas
• Invoices_Credit_Notes
• Invoices_ Pré-pagamentos
• Invoices_Overpayments
• Manual_Journals
• Pagamentos em excesso
• Overpayments_Allocations
• Pré-pagamentos
• Prepayments_Allocations
• Recibos
• Receipt_Validation_Errors
• Tracking_Categories

As tabelas a seguir só podem ser consultadas com esquema completo:

• Complete.Bank_Transaction_Line_Items
• Complete.Bank_Transaction_Line_Item_Tracking
• Complete.Contact_Group_Contacts
• Complete.Contacts_Contact_ Pessoas
• Complete.Credit_Note_Line_Items
• Complete.Credit_Notes_Line_Items_Tracking
• Complete.Expense_Claim_ Pagamentos
• Complete.Expense_Claim_Receipts
• Complete.Invoice_Line_Items
• Complete.Invoices_Line_Items_Tracking
• Complete.Manual_Journal_Lines
• Complete.Manual_Journal_Line_Tracking
• Complete.Overpayment_Line_Items
• Complete.Overpayment_Line_Items_Tracking
• Complete.Prepayment_Line_Items
• Complete.Prepayment_Line_Item_Tracking
• Complete.Receipt_Line_Items
• Complete.Receipt_Line_Item_Tracking
• Complete.Tracking_Category_Options

Mapeamento de tipo de dados para Xero

Quando você copia dados do Xero, os mapeamentos a seguir se aplicam dos tipos de dados do Xero aos tipos de dados internos usados pelo serviço. Para saber como a atividade de cópia mapeia o esquema de origem e o tipo de dados para o destino, consulte Mapeamentos de esquema e tipo de dados.

Propriedades da atividade de pesquisa

Para saber detalhes sobre as propriedades, verifique Atividade de pesquisa.

Ciclo de vida e atualização do conector Xero

A tabela a seguir mostra o estágio de liberação e os logs de alteração para diferentes versões do conector Xero:

Atualize o conector Xero da versão 1.0 para a versão 2.0

1. Na página Editar serviço vinculado , selecione a versão 2.0 e configure o serviço vinculado consultando as propriedades do serviço vinculado versão 2.0.

2. O mapeamento de tipo de dados para o serviço vinculado Xero versão 2.0 é diferente daquele para a versão 1.0. Para saber o mapeamento de tipo de dados mais recente, consulte Mapeamento de tipo de dados para Xero.

3. Se usares o runtime de integração auto-hospedado, a versão deverá ser 5.61 ou superior.

4. Use table em vez de tableName na versão 2.0. Para a configuração detalhada, vá a Propriedades do Conjunto de Dados.

5. query só é suportado na versão 1.0. Você deve usar o table em vez de query na versão 2.0.

6. Note que a versão 2.0 suporta tabelas Xero específicas. Para a lista de tabelas suportadas, vá para Propriedades do conjunto de dados.

Conteúdos relacionados

Para obter uma lista de armazenamentos de dados suportados pela atividade de cópia, consulte Armazenamentos de dados suportados.