Копирование данных из Xero с помощью Фабрики данных Azure или Synapse Analytics

Статья
10/20/2023

Область применения:Фабрика данных Azure Azure Synapse Analytics

Совет

Попробуйте использовать фабрику данных в Microsoft Fabric, решение для аналитики с одним интерфейсом для предприятий. Microsoft Fabric охватывает все, от перемещения данных до обработки и анализа данных в режиме реального времени, бизнес-аналитики и отчетности. Узнайте, как бесплатно запустить новую пробную версию !

В этой статье описывается, как с помощью действия копирования в Фабрике данных Azure и конвейерах Azure Synapse Analytics копировать данные из Xero. Это продолжение статьи об обзоре действия копирования, в которой представлены общие сведения о действии копирования.

Поддерживаемые возможности

Соединитель Xero поддерживается для перечисленных ниже возможностей.

Поддерживаемые возможности	IR
Действие копирования (источник/-)	① ②
Действие поиска	① ②

① Среда выполнения интеграции Azure ② Локальная среда выполнения интеграции

Список хранилищ данных, которые поддерживаются в качестве источников/приемников, см. в таблице Поддерживаемые хранилища данных.

В частности, этот соединитель Xero поддерживает:

Проверка подлинности OAuth 2.0 и OAuth 1.0. Для OAuth 1.0 соединитель поддерживает частное приложение Xero, но не общедоступное приложение.
все таблицы Xero (конечные точки API), кроме таблицы "Отчеты".

Начало работы

Чтобы выполнить действие копирования с конвейером, можно воспользоваться одним из приведенных ниже средств или пакетов SDK:

Создание связанной службы для Xero с помощью пользовательского интерфейса

Выполните следующие действия, чтобы создать связанную службу для Xero в пользовательском интерфейсе портала Azure.

Перейдите на вкладку "Управление" в рабочей области Фабрики данных Azure или Synapse и выберите "Связанные службы", после чего нажмите "Создать":
- Фабрика данных Azure
- Azure Synapse
Выполните поиск по запросу Xero и выберите соединитель Xero.
Настройте сведения о службе, проверьте подключение и создайте связанную службу.

Сведения о конфигурации соединителя

Следующие разделы содержат сведения о свойствах, которые используются для определения сущностей фабрики данных, относящихся к соединителю Xero.

Свойства связанной службы

Для связанной службы Xero поддерживаются следующие свойства:

Свойство	Описание:	Обязательное поле
type	Для свойства type необходимо задать значение Xero.	Да
connectionProperties	Группа свойств, определяющих способ подключения к Xero.	Да
В разделе `connectionProperties`:
host	Конечная точка сервера Xero (`api.xero.com`).	Да
authenticationType	Допустимые значения — `OAuth_2.0` и `OAuth_1.0`.	Да
consumerKey	Для OAuth 2.0 укажите идентификатор клиента для приложения Xero. Для OAuth 1.0 укажите ключ пользователя, связанный с приложением Xero. Пометьте это поле как SecureString, чтобы безопасно хранить его, или добавьте ссылку на секрет, хранящийся в Azure Key Vault.	Да
privateKey	Для OAuth 2.0 укажите секрет клиента для приложения Xero. Для OAuth 1.0 укажите закрытый ключ из PEM-файла, созданный для частного приложения Xero. Примечание для создания privatekey.pem с numbits 512 с использованием `openssl genrsa -out privatekey.pem 512`; 1024 не поддерживается. Включает весь текст из PEM-файла, в том числе окончания строк Unix (\n). Пример см. ниже. Пометьте это поле как SecureString, чтобы безопасно хранить его, или добавьте ссылку на секрет, хранящийся в Azure Key Vault.	Да
tenantId	Идентификатор клиента, связанный с приложением Xero. Применимо к проверке подлинности OAuth 2.0. Сведения о том, как получить идентификатор клиента, см. в разделе Проверка клиентов, которым вы разрешили доступ.	Да, для проверки подлинности OAuth 2.0
refreshtoken	Применимо к проверке подлинности OAuth 2.0. Маркер обновления OAuth 2.0 связан с приложением Xero и используется для обновления маркера доступа. Срок действия маркера составляет 30 минут. Узнайте, как работает поток авторизации Xero и как получить маркер обновления, из этой статьи. Чтобы получить маркер обновления, необходимо запросить область offline_access. Известное ограничение: Xero сбрасывает маркер обновления после его использования для обновления маркера доступа. Для операционной рабочей нагрузки перед выполнением каждого действия копирования необходимо задать допустимый маркер обновления для службы. Пометьте это поле как SecureString, чтобы безопасно хранить его, или добавьте ссылку на секрет, хранящийся в Azure Key Vault.	Да, для проверки подлинности OAuth 2.0
useEncryptedEndpoints	Указывает, шифруются ли конечные точки источника данных с помощью протокола HTTPS. Значение по умолчанию — true.	No
useHostVerification	Указывает, нужно ли, чтобы имя узла в сертификате сервера совпадало с именем узла сервера при подключении по протоколу TLS. Значение по умолчанию — true.	No
usePeerVerification	Указывает, следует ли проверять удостоверение сервера при подключении по протоколу TLS. Значение по умолчанию — true.	No

Пример: проверка подлинности 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
            }            
        }
    }
}

Пример: проверка подлинности 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
            }
        }
    }
}

Пример значения закрытого ключа

Включает весь текст из PEM-файла, в том числе окончания строк 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-----"

Свойства набора данных

Полный список разделов и свойств, доступных для определения наборов данных, см. в статье о наборах данных. В этом разделе содержится список свойств, поддерживаемых набором данных Xero.

Чтобы копировать данные из Xero, установите свойство type набора данных XeroObject. Поддерживаются следующие свойства:

Свойство	Описание:	Обязательное поле
type	Свойство type для набора данных должно иметь значение XeroObject	Да
tableName	Имя таблицы.	Нет (если свойство query указано в источнике действия)

Пример

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

Свойства действия копирования

Полный список разделов и свойств, используемых для определения действий, см. в статье Конвейеры и действия в фабрике данных Azure. В этом разделе содержится список свойств, поддерживаемых источником Xero.

Xero в качестве источника

Чтобы копировать данные из HTTP, установите тип источника XeroSource в действии копирования. В разделе source действия копирования поддерживаются следующие свойства:

Свойство	Описание:	Обязательное поле
type	Свойство type источника действия копирования должно иметь значение XeroSource.	Да
query	Используйте пользовательский SQL-запрос для чтения данных. Например: `"SELECT * FROM Contacts"`.	Нет (если для набора данных задано свойство tableName)

Пример:

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

При указании запроса Xero обратите внимание на следующее:

Таблицы со сложными элементами необходимо разделять на несколько. Например, банковские переводы имеют сложную структуру данных LineItems. Поэтому данные перевода сопоставляются с таблицами Bank_Transaction и Bank_Transaction_Line_Items, где Bank_Transaction_ID — это внешний ключ, который связывает их.
Данные Xero имеют две схемы: Minimal (по умолчанию) и Complete. Полная схема содержит необходимые таблицы вызовов, которые требуют дополнительные данные (например, столбец идентификатора) перед выполнением запроса.

Ниже приведены таблицы с одинаковой информацией в полной и минимальной схеме. Чтобы уменьшить число вызовов API, используйте минимальную схему (по умолчанию).

Bank_Transactions
Contact_Groups
Контакты
Contacts_Sales_Tracking_Categories
Contacts_Phones
Contacts_Addresses
Contacts_Purchases_Tracking_Categories
Credit_Notes
Credit_Notes_Allocations
Expense_Claims
Expense_Claim_Validation_Errors
Счета
Invoices_Credit_Notes
Invoices_ Prepayments
Invoices_Overpayments
Manual_Journals
Overpayments
Overpayments_Allocations
Предоплаты
Prepayments_Allocations
Получения
Receipt_Validation_Errors
Tracking_Categories

Следующие таблицы можно запрашивать только с использованием полной схемы:

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

Свойства действия поиска

Подробные сведения об этих свойствах см. в разделе Действие поиска.

Список источников данных, которые поддерживает действие копирования, приведен в таблице поддерживаемых хранилищ данных и форматов.