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

APLICA-SE A: Azure Data Factory Azure Synapse Analytics

Este artigo descreve como usar a atividade de cópia nos pipelines do Azure Data Factory ou do Azure Synapse Analytics para copiar dados de uma tabela do Xero. Ele amplia o artigo Visão geral da atividade de cópia que apresenta uma visão geral da atividade de cópia.

Funcionalidades com suporte

O conector Xero é compatível com as seguintes funcionalidades:

① Tempo de execução de integração do Azure ② Tempo de execução de integração auto-hospedado

Para obter uma lista de armazenamentos de dados com suporte como origens e coletores, confira a tabela Armazenamentos de dados com suporte.

Especificamente, esse conector do Xero fornece suporte para:

• Autenticação OAuth 2.0.
• Todas as tabelas Xero (pontos de extremidade de 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 de Cópia de Dados
• Portal do Azure
• SDK do .NET
• SDK do Python
• PowerShell do Azure
• REST API
• Modelo do 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 no workspace do Azure Data Factory ou do Synapse e selecione Serviços Vinculados. Depois, clique em Novo:

   • Fábrica de dados do Azure
   • Azure Synapse

   

2. Procure por Xero e selecione o conector do Xero.

   

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

   

Detalhes da configuração do conector

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

Propriedades do serviço vinculado

O conector Xero agora dá suporte à versão 2.0. Consulte esta seção para fazer o upgrade da versão do seu conector Xero a partir da versão 1.0. Para obter detalhes sobre as propriedades, consulte as seções correspondentes.

• Versão 2.0
• versão 1.0

Versão 2.0

O serviço vinculado do Xero dá suporte às seguintes propriedades ao aplicar a versão 2.0:

Exemplo:

{
    "name": "XeroLinkedService",
    "properties": {
        "type": "Xero",
        "typeProperties": {
            "host": "api.xero.com",
            "consumerKey": "<client ID>",
            "privateKey": {
                "type": "SecureString",
                "value": "<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 vinculado do Xero dá suporte às seguintes propriedades ao aplicar 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
            }
        }
    }
}

Valor de chave privada de exemplo:

Inclua todo o texto do arquivo .pem incluindo as terminações de linha do 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 das seções e propriedades disponíveis para definir os conjuntos de dados, confira o artigo sobre conjuntos de dados. Esta seção fornece uma lista das propriedades com suporte pelo conjunto de dados do Xero.

Para copiar dados do Xero, defina a propriedade type do conjunto de dados como XeroObject. Há suporte para as seguintes propriedades:

Exemplo

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

O conector versão 2.0 dá suporte às seguintes tabelas Xero:

• Accounts
• Bank_Transactions
• Itens_de_Linha_de_Transação_Bancária
• Transferências_Bancárias
• Budgets
• Contatos
• Contacts_Addresses
• Contact_Groups
• Contact_Group_Contacts
• Contacts_Phones
• Credit_Notes
• Itens_de_Linha_da_Nota_de_Crédito
• Rastreamento_de_Itens_de_Linha_de_Notas_de_Crédito
• Moedas
• Faturas
• Invoices_Credit_Notes
• Invoice_Line_Items
• Invoice_Line_Items_Tracking
• Invoices_Overpayments
• Faturas_Adiantamentos
• Itens
• Diários
• Linhas_do_Diário
• Journal_Line_Tracking_Categories
• Manual_Journals
• Manual_Journal_Lines
• Organizações
• Pagamentos a maior
• Payments
• Pagamento antecipado
• Prepayments_Allocations
• Itens_de_Linha_de_Adiantamento
• Projetos
• UsuáriosDoProjeto
• Pedidos_de_Compra
• Itens_de_Linha_de_Ordem_de_Compra
• Recebimentos
• Taxas_de_Impostos
• Tracking_Categories
• Opções_de_Categorias_de_Rastreamento
• Usuários

Propriedades da atividade de cópia

Para obter uma lista completa das seções e propriedades disponíveis para definir atividades, confia o artigo Pipelines. Esta seção fornece uma lista das propriedades com suporte pela fonte do Xero.

Xero como fonte

Para copiar dados de Xero, defina o tipo de fonte na atividade de cópia como XeroSource. As propriedades a seguir têm suporte na seção source 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:

• Tabelas com itens complexos serão divididas em várias tabelas. Por exemplo, as transações bancárias possuem uma estrutura de dados complexa "LineItems", portanto, os dados de 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 chamadas prévias que requerem dados adicionais (por exemplo, Coluna de ID) antes de fazer a consulta desejada.

As tabelas a seguir possuem a mesma informação no esquema Mínimo e Completo. Para reduzir o número de chamadas à API, use o esquema Mínimo (padrão).

• Bank_Transactions
• Contact_Groups
• Contatos
• 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
• Faturas_ Pagamentos Antecipados
• Invoices_Overpayments
• Manual_Journals
• Pagamentos a maior
• Overpayments_Allocations
• Pagamento antecipado
• Prepayments_Allocations
• Recebimentos
• Receipt_Validation_Errors
• Tracking_Categories

As tabelas a seguir somente podem ser consultadas com o esquema completo:

• Complete.Bank_Transaction_Line_Items
• Complete.Bank_Transaction_Line_Item_Tracking
• Complete.Contact_Group_Contacts
• Complete.Contacts_Contact_ Persons
• Complete.Credit_Note_Line_Items
• Complete.Credit_Notes_Line_Items_Tracking
• Complete.Expense_Claim_ Payments
• 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 mais sobre como a atividade Copy mapeia o tipo de dados e esquema de origem para o coletor, consulte Mapeamentos de tipo de dados e esquema.

Pesquisar propriedades de atividade

Para saber detalhes sobre as propriedades, verifique Pesquisar atividade.

Ciclo de vida e atualização do conector Xero

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

Atualizar 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 referindo-se às 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 do da versão 1.0. Para saber mais sobre o mapeamento de tipo de dados mais recente, consulte Mapeamento de tipo de dados para Xero.

3. Se você usar o runtime de integração auto-hospedada, sua 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, acesse as propriedades do conjunto de dados.

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

6. Observe que a versão 2.0 dá suporte a tabelas específicas do Xero. Para a lista de tabelas com suporte, acesse as propriedades do conjunto de dados.

Conteúdo relacionado

Para obter uma lista de armazenamentos de dados com suporte pela atividade de cópia, confira a tabela Armazenamentos de dados com suporte.