Copia de datos de Xero con Azure Data Factory o Synapse Analytics

Artículo
10/20/2023

SE APLICA A: Azure Data Factory Azure Synapse Analytics

Sugerencia

Pruebe Data Factory en Microsoft Fabric, una solución de análisis todo en uno para empresas. Microsoft Fabric abarca todo, desde el movimiento de datos hasta la ciencia de datos, el análisis en tiempo real, la inteligencia empresarial y los informes. ¡Obtenga más información sobre cómo iniciar una nueva evaluación gratuita!

En este artículo se explica cómo usar la actividad de copia de una canalización de Azure Data Factory o Synapse Analytics para copiar datos de Xero. El documento se basa en el artículo de introducción a la actividad de copia que describe información general de la actividad de copia.

Funcionalidades admitidas

El conector Xero es compatible para las siguientes funcionalidades:

Funcionalidades admitidas	IR
Actividad de copia (origen/-)	7,7
Actividad de búsqueda	7,7

① Azure Integration Runtime ② Entorno de ejecución de integración autohospedado

Para obtener una lista de los almacenes de datos que se admiten como orígenes y receptores, consulte la tabla de almacenes de datos admitidos.

En concreto, este conector Xero admite lo siguiente:

Autenticación de OAuth 2.0 y OAuth 1.0. En OAuth 1.0, el conector admite la aplicación privada Xero pero no una aplicación pública.
Todas las tablas de Xero (puntos de conexión de API), excepto "Reports" (Informes).

Introducción

Para realizar la actividad de copia con una canalización, puede usar una de los siguientes herramientas o SDK:

Creación de un servicio vinculado en Xero mediante la interfaz de usuario

Siga estos pasos para crear un servicio vinculado en Xero en la interfaz de usuario de Azure Portal.

Vaya a la pestaña Administrar del área de trabajo de Azure Data Factory o Synapse y seleccione Servicios vinculados; luego haga clic en Nuevo:
- Azure Data Factory
- Azure Synapse
Busque Xero y seleccione el conector de Xero.
Configure los detalles del servicio, pruebe la conexión y cree el nuevo servicio vinculado.

Detalles de configuración del conector

En las secciones siguientes se proporcionan detalles sobre las propiedades que se usan para definir entidades de Data Factory específicas del conector Xero.

Propiedades del servicio vinculado

Las siguientes propiedades son compatibles con el servicio vinculado de Xero:

Propiedad	Descripción	Obligatorio
type	La propiedad type debe establecerse en: Xero	Sí
connectionProperties	Grupo de propiedades que define cómo conectarse a Xero.	Sí
En `connectionProperties`:
host	El punto de conexión del servidor de Xero (`api.xero.com`).	Sí
authenticationType	Los valores permitidos son `OAuth_2.0` y `OAuth_1.0`.	Sí
consumerKey	Para OAuth 2.0, especifique el id. de cliente para la aplicación Xero. Para OAuth 1.0, especifique la clave de consumidor asociada a la aplicación Xero. Marque este campo como SecureString para almacenarlo de forma segura, o bien haga referencia a un secreto almacenado en Azure Key Vault.	Sí
privateKey	Para OAuth 2.0, especifique el secreto de cliente* para la aplicación Xero. Para OAuth 1.0, especifique la clave privada del archivo .pem que se generó para la aplicación privada Xero. Asegúrese de generar el archivo privatekey.pem con numbits de 512 con `openssl genrsa -out privatekey.pem 512`; 1024 no se admite. Incluya todo el texto del archivo .pem, así como los finales de línea Unix (\n). Vea el ejemplo a continuación. Marque este campo como SecureString para almacenarlo de forma segura, o bien haga referencia a un secreto almacenado en Azure Key Vault.	Sí
tenantId	Identificador de inquilino asociado a la aplicación Xero. Aplicable para la autenticación de OAuth 2.0. Aprenda a obtener el identificador de inquilino en la sección Comprobación de los inquilinos a los que tiene autorizado el acceso.	Sí para la autenticación de OAuth 2.0
refreshToken	Aplicable para la autenticación de OAuth 2.0. El token de actualización de OAuth 2.0 está asociado a la aplicación Xero y se usa para actualizar el token de acceso, que expira después de 30 minutos. Obtenga información sobre cómo funciona el flujo de autorización de Xero y cómo obtener el token de actualización en este artículo. Para obtener un token de actualización, debe solicitar el ámbito offline_access. Limitación conocida: tenga en cuenta que Xero restablece el token de actualización después de que se use para la actualización del token de acceso. En el caso de cargas de trabajo operativas, antes de que se ejecute la actividad de copia, debe establecer un token de actualización válido para que lo use el servicio. Marque este campo como SecureString para almacenarlo de forma segura, o bien haga referencia a un secreto almacenado en Azure Key Vault.	Sí para la autenticación de OAuth 2.0
useEncryptedEndpoints	Especifica si los puntos de conexión de origen de datos se cifran mediante HTTPS. El valor predeterminado es true.	No
useHostVerification	Especifica si se requiere que el nombre de host del certificado del servidor coincida con el nombre de host del servidor al conectarse a través de TLS. El valor predeterminado es true.	No
usePeerVerification	Especifica si se debe verificar la identidad del servidor al conectarse a través de TLS. El valor predeterminado es true.	No

Ejemplo: autenticación de 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
            }            
        }
    }
}

Ejemplo: autenticación de 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 clave privada de ejemplo:

Incluya todo el texto del archivo .pem, así como los finales de línea 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-----"

Propiedades del conjunto de datos

Si desea ver una lista completa de las secciones y propiedades disponibles para definir conjuntos de datos, consulte el artículo sobre conjuntos de datos. En esta sección se proporciona una lista de las propiedades que admite el conjunto de datos de Xero.

Para copiar datos de Xero, establezca la propiedad type del conjunto de datos en XeroObject. Se admiten las siguientes propiedades:

Propiedad	Descripción	Obligatorio
type	La propiedad type del conjunto de datos debe establecerse en: XeroObject	Sí
tableName	Nombre de la tabla.	No (si se especifica "query" en el origen de la actividad)

Ejemplo

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

Propiedades de la actividad de copia

Si desea ver una lista completa de las secciones y propiedades disponibles para definir actividades, consulte el artículo sobre canalizaciones. En esta sección se proporciona una lista de las propiedades que admite el origen de Xero.

Xero como origen

Para copiar datos de Xero, establezca el tipo de origen de la actividad de copia en XeroSource. Se admiten las siguientes propiedades en la sección source de la actividad de copia:

Propiedad	Descripción	Obligatorio
type	La propiedad type del origen de la actividad de copia debe establecerse en: XeroSource	Sí
Query	Use la consulta SQL personalizada para leer los datos. Por ejemplo: `"SELECT * FROM Contacts"`.	No (si se especifica "tableName" en el conjunto de datos)

Ejemplo:

"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>"
            }
        }
    }
]

Tenga en cuenta lo siguiente al especificar la consulta de Xero:

Las tablas con elementos complejos se dividirán en varias tablas. Por ejemplo, las transacciones bancarias tienen una estructura de datos compleja "LineItems", así que los datos de la transacción bancaria se asignan a las tablas Bank_Transaction y Bank_Transaction_Line_Items, con la clave externa Bank_Transaction_ID para vincularlas.
Los datos de Xero están disponibles a través de dos esquemas: Minimal (predeterminado) y Complete. El esquema Complete contiene tablas de llamadas de requisitos previos que necesitan datos adicionales (por ejemplo, la columna ID) antes de realizar la consulta deseada.

Las siguientes tablas tienen la misma información en los esquemas Minimal y Complete. Para reducir el número de llamadas API, use un esquema Minimal (predeterminado).

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
Facturas
Invoices_Credit_Notes
Invoices_ Prepayments
Invoices_Overpayments
Manual_Journals
Overpayments
Overpayments_Allocations
Prepayments
Prepayments_Allocations
Receipts
Receipt_Validation_Errors
Tracking_Categories

Las siguientes tablas solo se pueden consultar con el esquema Complete:

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

Propiedades de la actividad de búsqueda

Para obtener información detallada sobre las propiedades, consulte Actividad de búsqueda.

Para obtener una lista de los almacenes de datos que admite la actividad de copia, consulte los almacenes de datos compatibles.