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

Artigo
10/20/2023

APLICA-SE A: Azure Data Factory Azure Synapse Analytics

Dica

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

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:

Funcionalidades com suporte	IR
Atividade de cópia (origem/-)	6/6
Atividade de pesquisa	6/6

① Runtime de integração do Azure ② Runtime de integração auto-hospedada

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

Introdução

Para executar a atividade de Cópia com um pipeline, será possível usar as ferramentas ou os SDKs abaixo:

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 workspace do Azure Data Factory ou do Synapse, selecione Serviços Vinculados e clique em Novo:
- Azure Data Factory
- Azure Synapse
Procure por Xero e selecione o conector do Xero.
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

As propriedades a seguir têm suporte para o serviço vinculado do Xero:

Propriedade	Descrição	Obrigatório
type	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	Para o OAuth 2.0, especifique a ID do cliente para seu aplicativo Xero. Para o 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 referencie um segredo armazenado no Azure Key Vault.	Sim
privateKey	Para o OAuth 2.0, especifique o segredo do cliente para seu aplicativo Xero. Para o OAuth 1.0, especifique a chave privada do arquivo .pem que foi gerada para o seu aplicativo privado Xero. Observe gerar privatekey.pem com numbits de 512 usando `openssl genrsa -out privatekey.pem 512`; não há suporte para a 1024. Inclua todo o texto do arquivo .pem, incluindo as terminações de linha Unix (\n), consulte o exemplo abaixo. Marque este campo como um SecureString para armazená-lo com segurança ou referencie um segredo armazenado no Azure Key Vault.	Sim
tenantId	A ID de locatário associada ao seu aplicativo Xero. Aplicável à autenticação OAuth 2.0. Saiba como obter a ID do locatário em Verificar os locatários que você está autorizado a acessar a seção.	Sim para autenticação OAuth 2.0
refreshToken	Aplicável à autenticação OAuth 2.0. O token de atualização OAuth 2.0 é associado ao aplicativo Xero e usado para atualizar o token de acesso, que 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 escopo offline_access. Limitação desaber: observe que 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 execução de atividade de cópia, 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 referencie um segredo armazenado no Azure Key Vault.	Sim para autenticação OAuth 2.0
useEncryptedEndpoints	Especifica se os endpoints de fonte de dados são criptografados usando HTTPS. O valor padrão é true.	Não
useHostVerification	Especifica se o nome do host é necessário no certificado do servidor para corresponder ao nome de host do servidor ao se conectar via TLS. O valor padrão é true.	Não
usePeerVerification	Especifica se a identidade do servidor deve ser verificada nas conexões por TLS. O valor padrão é 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
            }
        }
    }
}

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:

Propriedade	Descrição	Obrigatório
type	A propriedade de tipo do conjunto de dados deve ser definido para: XeroObject	Sim
tableName	Nome da tabela.	Não (se "query" na fonte da atividade for especificada)

Exemplo

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

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:

Propriedade	Descrição	Obrigatório
type	A propriedade type da fonte da atividade de cópia deve ser definida como: XeroSource	Sim
Consulta	Utiliza a consulta SQL personalizada para ler os 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:

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
Invoices_ Prepayments
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

Pesquisar propriedades de atividade

Para saber detalhes sobre as propriedades, verifique Pesquisar atividade.

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