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

Artigo
11/16/2023

APLICA-SE A: Azure Data Factory Azure Synapse Analytics

Gorjeta

Experimente o Data Factory no Microsoft Fabric, uma solução de análise tudo-em-um para empresas. O Microsoft Fabric abrange tudo, desde a movimentação de dados até ciência de dados, análises em tempo real, business intelligence e relatórios. Saiba como iniciar uma nova avaliação gratuitamente!

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:

Capacidades suportadas	IR
Atividade de cópia (fonte/-)	① ②
Atividade de Pesquisa	① ②

(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 e OAuth 1.0. Para OAuth 1.0, o conector suporta o aplicativo privado Xero, mas não o aplicativo público.
Todas as tabelas Xero (pontos de extremidade API), exceto "Relatórios".

Introdução

Para executar a atividade Copiar com um pipeline, você pode usar uma das seguintes ferramentas ou SDKs:

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.

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
Procure Xero e selecione o conector Xero.
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

As seguintes propriedades são suportadas para o serviço vinculado Xero:

Propriedade	Descrição	Necessário
tipo	A propriedade type deve ser definida como: Xero	Sim
connectionProperties	Um grupo de propriedades que define como se conectar ao Xero.	Sim
Em `connectionProperties`:
host	O ponto de extremidade do servidor Xero (`api.xero.com`).	Sim
authenticationType	Os valores permitidos são `OAuth_2.0` e `OAuth_1.0`.	Sim
consumerKey [en]	Para OAuth 2.0, especifique o ID do cliente para seu aplicativo Xero. Para OAuth 1.0, especifique a chave de consumidor associada ao aplicativo Xero. Marque este campo como um SecureString para armazená-lo com segurança ou faça referência a um segredo armazenado no Cofre de Chaves do Azure.	Sim
chave privada	Para OAuth 2.0, especifique o segredo do cliente para seu aplicativo Xero. Para OAuth 1.0, especifique a chave privada do arquivo .pem que foi gerado para seu aplicativo privado Xero. Observação para gerar o privatekey.pem com numbits de 512 usando `openssl genrsa -out privatekey.pem 512`, 1024 não é suportado. Inclua todo o texto do arquivo .pem, incluindo as terminações de linha Unix(\n), veja o exemplo abaixo. Marque este campo como um SecureString para armazená-lo com segurança ou faça referência a um segredo armazenado no Cofre de Chaves do Azure.	Sim
tenantId	O ID do locatário associado ao seu aplicativo Xero. Aplicável à autenticação OAuth 2.0. Saiba como obter o ID do inquilino na secção Verificar os inquilinos a que está autorizado a aceder.	Sim para autenticação OAuth 2.0
refreshToken	Aplicável à autenticação OAuth 2.0. O token de atualização OAuth 2.0 está associado ao aplicativo Xero e é usado para atualizar o token de acesso; O token de acesso expira após 30 minutos. Saiba mais sobre como o fluxo de autorização do Xero funciona e como obter o token de atualização deste artigo. Para obter um token de atualização, você deve solicitar o offline_access escopo. Limitação conhecida: Observação O Xero redefine o token de atualização depois que ele é usado para a atualização do token de acesso. Para carga de trabalho operacionalizada, antes de cada atividade de cópia ser executada, você precisa definir um token de atualização válido para o serviço usar. Marque este campo como um SecureString para armazená-lo com segurança ou faça referência a um segredo armazenado no Cofre de Chaves do Azure.	Sim para autenticação OAuth 2.0
useEncryptedEndpoints	Especifica se os pontos de extremidade da fonte de dados são criptografados usando HTTPS. O valor predefinido é true.	Não
useHostVerification	Especifica se o nome do host é necessário no certificado do servidor para corresponder ao nome do host do servidor ao se conectar por TLS. O valor predefinido é true.	Não
usePeerVerification	Especifica se a identidade do servidor deve ser verificada ao se conectar por TLS. O valor predefinido é true.	Não

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:

Propriedade	Descrição	Necessário
tipo	A propriedade type do conjunto de dados deve ser definida como: XeroObject	Sim
tableName	Nome da tabela.	Não (se "consulta" na fonte da atividade for especificado)

Exemplo

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

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:

Propriedade	Descrição	Necessário
tipo	A propriedade type da fonte de atividade de cópia deve ser definida como: XeroSource	Sim
query	Use a consulta SQL personalizada para ler dados. Por exemplo: `"SELECT * FROM Contacts"`.	Não (se "tableName" no conjunto de dados for especificado)

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

Propriedades da atividade de pesquisa

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

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