Copiar dados do Xero usando 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 num pipeline do Azure Data Factory ou 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) Runtime de integração Azure (2) Runtime 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 (endpoints da API), exceto "Relatórios".
• Versões do Windows neste artigo.

Começar

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
• .NET SDK
• Python SDK
• Azure PowerShell
• API REST
• Modelo do Azure Resource Manager

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

Use os seguintes passos para criar um serviço ligado ao Xero na interface do portal Azure.

1. Navegue até ao separador Gerir no seu espaço de trabalho Azure Data Factory ou Synapse e selecione Serviços Ligados, depois 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",
        "version": "2.0",
        "typeProperties": {
            "host": "api.xero.com",
            "clientId": "<client ID>",
            "clientSecret": "<client secret>",
            "tenantId": "<tenant ID>", 
            "refreshToken": {
                "type": "SecureString",
                "value": "<refresh token>"
            },
            "authenticationType":"OAuth_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
• Contactos_Endereços
• Grupo_de_Contatos
• Contactos_Telefones
• 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
• Diários_Manuais
• Linhas_de_Jornal_Manual
• Organizações
• Itens_de_Linha_de_Prepagamento
• Projetos
• Utilizadores do Projeto
• Itens_de_Linha_de_Ordem_de_Compra
• Taxas_Fiscais
• Categorias_de_Rastreamento
• Opções_de_Categorias_de_Rastreamento
• Utilizadores

Propriedades da atividade de cópia

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

• Transações_Bancárias
• Contact_Groups
• Contactos
• Categorias_de_Rastreamento_de_Vendas_de_Contatos
• Contactos_Telefones
• Contactos_Endereços
• Contactos_Compras_Rastreamento_Categorias
• Notas_de_Crédito
• Atribuições_Notas_de_Crédito
• Pedidos_de_Despesas
• Erros de Validação de Reclamação de Despesa
• Faturas
• Faturas_Notas_de_Crédito
• Invoices_ Pré-pagamentos
• Faturas_Pagamentos_Excesso
• Diários_Manuais
• Pagamentos em excesso
• Atribuições_de_Pagamentos_Excessivos
• Pré-pagamentos
• Pagamentos Antecipados_Alocações
• Recibos
• Receipt_Validation_Errors
• Categorias_de_Rastreamento

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

• Complete.Bank_Transaction_Line_Items
• Completo.Rastreamento_de_Linha_de_Item_de_Transação_Bancária
• Completo.Grupo_de_Contatos_Contatos
• Complete.Contacts_Contact_Pessoas de Contato
• Complete.Itens_Linha_Nota_de_Crédito
• Completo.Tracking_Itens_de_Linha_de_Notas_de_Crédito
• Complete.Reembolso_Despesas_Pagamentos
• Completo.Recibos_de_Despesa_Reclamados
• Complete.Invoice_Line_Items
• Completo.Faturas_Itens_Linha_Rastreio
• Completar.Linhas_Manual_Jornal
• Complete.Rastreamento_de_Linha_do_Manual_de_Jornal
• Completo.Itens_de_Linha_de_Pagamento_Excedente
• Completo.Rastreio_de_Itens_de_Linha_de_Pagamento_Excedente
• Completa.Linhas_De_Adiantamento
• Complete.Rastreamento_de_Itens_de_Linha_de_Pagamento_Anticipado
• Completar.Itens_de_Linha_de_Recibo
• Completar.Rastreamento_De_Linha_De_Item_De_Recibo
• Completo.Opções_de_Categoria_de_Acompanhamento

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 consulta

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.