Azure Data Factory または Azure Synapse Analytics を使用して Xero からデータをコピーする

[アーティクル]
11/05/2024

適用対象: Azure Data Factory Azure Synapse Analytics

ヒント

企業向けのオールインワン分析ソリューション、Microsoft Fabric の Data Factory をお試しください。 Microsoft Fabric は、データ移動からデータサイエンス、リアルタイム分析、ビジネスインテリジェンス、レポートまで、あらゆるものをカバーしています。無料で新しい試用版を開始する方法について説明します。

この記事では、Azure Data Factory および Azure Synapse Analytics パイプラインで Copy アクティビティを使用して、Xero からデータをコピーする方法について説明します。この記事は、コピーアクティビティの概要を示しているコピーアクティビティの概要に関する記事に基づいています。

Note

Xero コネクタは OAuth 認証を必要とし、サーバー間での使用を目的としたものではありません。

サポートされる機能

この Xero コネクタでは、次の機能がサポートされます。

サポートされる機能	IR
Copy アクティビティ (ソース/-)	① ②
Lookup アクティビティ	① ②

① Azure 統合ランタイム ② セルフホステッド統合ランタイム

ソースおよびシンクとしてサポートされているデータストアの一覧については、「サポートされているデータストア」の表を参照してください。

具体的には、この Xero コネクタは以下をサポートします。

OAuth 2.0 認証。
"Reports" を除くすべて Xero テーブル (API エンドポイント)。
この記事の Windows バージョン。

Note

Xero での OAuth 1.0 認証の廃止に伴い、現在 OAuth 1.0 認証の種類を使用している場合は、OAuth 2.0 認証の種類にアップグレードしてください。

作業の開始

パイプラインでコピーアクティビティを実行するには、次のいずれかのツールまたは SDK を使用します。

UI を使用して Xero のリンクサービスを作成する

次の手順を使用して、Azure portal UI で Xero のリンクサービスを作成します。

Azure Data Factory または Synapse ワークスペースの [管理] タブに移動し、[リンクされたサービス] を選択して、[新規] をクリックします。
- Azure Data Factory
- Azure Synapse
Xero を検索し、Xero コネクタを選択します。
サービスの詳細を構成し、接続をテストして、新しいリンクサービスを作成します。

コネクタの構成の詳細

次のセクションでは、Xero コネクタに固有の Data Factory エンティティの定義に使用されるプロパティについて詳しく説明します。

リンクされたサービスのプロパティ

Xero のリンクされたサービスでは、次のプロパティがサポートされます。

プロパティ	内容	必須
type	type プロパティは、次のように設定する必要があります:Xero	はい
connectionProperties	Xero への接続方法を定義するプロパティグループ。	はい
`connectionProperties` の下:
host	Xero サーバーのエンドポイント (`api.xero.com`)。	はい
authenticationType	使用できる値は `OAuth_2.0` と `OAuth_1.0` です。	はい
consumerKey	OAuth 2.0 の場合は、Xero アプリケーションのクライアント ID を指定します。 OAuth 1.0 の場合は、Xero アプリケーションに関連付けられているコンシューマーキーを指定します。このフィールドを SecureString とマークして安全に保存するか、Azure Key Vault に保存されているシークレットを参照します。	はい
privateKey	OAuth 2.0 の場合は、Xero アプリケーションのクライアントシークレットを指定します。 OAuth 1.0 の場合は、Xero プライベートアプリケーション用に生成された .pem ファイルの秘密キーを指定します。 `openssl genrsa -out privatekey.pem 512` を使用し、numbits に 512 を指定して、privatekey.pem を生成します。 1024 はサポートされていません。 Unix の改行文字 (\n) も含め、.pem ファイルのすべてのテキストを含めます (以下のサンプルを参照してください)。このフィールドを SecureString とマークして安全に保存するか、Azure Key Vault に保存されているシークレットを参照します。	はい
tenantId	Xero アプリケーションに関連付けられているテナント ID。 OAuth 2.0 認証に適用されます。アクセスを許可されているテナントの確認セクションで、テナント ID の取得方法を確認してください。	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 です。	いいえ
useHostVerification	TLS 経由で接続するときに、サーバーの証明書内のホスト名がサーバーのホスト名と一致する必要があるかどうかを指定します。既定値は、true です。	いいえ
usePeerVerification	TLS 経由で接続するときに、サーバーの ID を検証するかどうかを指定します。既定値は、true です。	いいえ

例: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
            }
        }
    }
}

サンプル秘密キー値:

Unix の改行文字 (\n) も含め、.pem ファイルのすべてのテキストを含めます。

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

コピーアクティビティのプロパティ

アクティビティの定義に利用できるセクションとプロパティの完全な一覧については、パイプラインに関する記事を参照してください。このセクションでは、Xero ソースでサポートされるプロパティの一覧を示します。

ソースとしての Xero

Xero からデータをコピーするは、コピーアクティビティのソースの種類を 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 データは 2 つのスキーマを通じて使用できます。Minimal (既定) と Complete です。 Complete スキーマには、目的のクエリを実行する前に追加データ (例: ID 列) を必要とする、前提条件呼び出しテーブルが含まれます。

次のテーブルは、Minimal スキーマと Complete スキーマで同じ情報を持ちます。 API 呼び出しの数を減らすには、Minimal スキーマ (既定) を使用します。

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

次のテーブルは、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

Lookup アクティビティのプロパティ

プロパティの詳細については、Lookup アクティビティに関するページを参照してください。

コピーアクティビティによってサポートされているデータストアの一覧については、サポートされているデータストアに関するセクションを参照してください。

次の方法で共有

Azure Data Factory または Azure Synapse Analytics を使用して Xero からデータをコピーする

サポートされる機能

作業の開始

UI を使用して Xero のリンクサービスを作成する

コネクタの構成の詳細

リンクされたサービスのプロパティ

データセットのプロパティ

コピーアクティビティのプロパティ

ソースとしての Xero

Lookup アクティビティのプロパティ

フィードバック

その他のリソース

次の方法で共有

Azure Data Factory または Azure Synapse Analytics を使用して Xero からデータをコピーする

サポートされる機能

作業の開始

UI を使用して Xero のリンク サービスを作成する

コネクタの構成の詳細

リンクされたサービスのプロパティ

データセットのプロパティ

コピー アクティビティのプロパティ

ソースとしての Xero

Lookup アクティビティのプロパティ

関連するコンテンツ

フィードバック

その他のリソース

UI を使用して Xero のリンクサービスを作成する

コピーアクティビティのプロパティ