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

Artigo
11/05/2024

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.

Observação

O conector Xero exige a autenticação OAuth e não se destina ao uso de servidor para servidor.

Funcionalidades com suporte

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

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

① 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.
Todas as tabelas Xero (pontos de extremidade de API), exceto "Relatórios".
Versões do Windows neste artigo.

Observação

Devido ao pôr do sol da autenticação OAuth 1.0 no Xero, atualize para o tipo de autenticação OAuth 2.0 se no momento você estiver usando o tipo de autenticação OAuth 1.0.

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.

Compartilhar via

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

Funcionalidades com suporte

Introdução

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

Detalhes da configuração do conector

Propriedades do serviço vinculado

Propriedades do conjunto de dados

Propriedades da atividade de cópia

Xero como fonte

Pesquisar propriedades de atividade

Comentários

Recursos adicionais

Compartilhar via

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

Funcionalidades com suporte

Introdução

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

Detalhes da configuração do conector

Propriedades do serviço vinculado

Propriedades do conjunto de dados

Propriedades da atividade de cópia

Xero como fonte

Pesquisar propriedades de atividade

Conteúdo relacionado

Comentários

Recursos adicionais