Xero

このコネクタは、Xero バックエンドに SQL アクセスを提供します。

準備

Xero コネクタを使用する前に、次の作業を行います。

  • Google Cloud プロジェクトで次の操作を行います。
    • コネクタを構成するユーザーに roles/connectors.admin IAM ロールを付与します。
    • コネクタに使用するサービス アカウントに、次の IAM ロールを付与します。
      • roles/secretmanager.viewer
      • roles/secretmanager.secretAccessor

      サービス アカウントは特別なタイプの Google アカウントで、Google API のデータにアクセスするのに認証を受ける必要がある人間以外のユーザーを表します。サービス アカウントがない場合は、サービス アカウントを作成する必要があります。詳細については、サービス アカウントを作成するをご覧ください。

    • 次のサービスを有効にします。
      • secretmanager.googleapis.com（Secret Manager API）
      • connectors.googleapis.com（Connectors API）

      サービスを有効にする方法については、サービスを有効にするをご覧ください。

    以前にプロジェクトでこうしたサービスを有効にしていない場合は、コネクタを構成するときにそれを有効にすることを求められます。

コネクタを構成する

コネクタを構成するには、データソース（バックエンド システム）への接続を作成する必要があります。接続はデータソースに特有です。つまり、多数のデータソースがある場合は、データソースごとに別々の接続を作成する必要があります。接続を作成する手順は次のとおりです。

  1. Cloud コンソールで、[Integration Connectors] > [接続] ページに移動し、Google Cloud プロジェクトを選択または作成します。

    [接続] ページに移動

  2. [+ 新規作成] をクリックして [接続の作成] ページを開きます。
  3. [ロケーション] セクションで、接続のロケーションを選択します。
    1. リージョン: プルダウン リストからロケーションを選択します

      コネクタをサポートしているリージョンは次のとおりです。

      サポートされているすべてのリージョンのリストについては、ロケーションをご覧ください。

    2. [Next] をクリックします。
  4. [接続の詳細] セクションで、次の操作を行います。
    1. コネクタ: 使用可能なコネクタのプルダウン リストから [Xero] を選択します。
    2. コネクタのバージョン: 使用可能なバージョンのプルダウン リストからコネクタのバージョンを選択します。
    3. [接続名] フィールドに、接続インスタンスの名前を入力します。

      接続名は次の条件を満たす必要があります。

      • 接続名には英字、数字、ハイフンを使用できます。
      • 文字は小文字のみを使用できます。
      • 接続名の先頭には英字を設定し、末尾には英字または数字を設定する必要があります。
      • 接続名は 63 文字以内で指定してください。
    4. 必要に応じて、接続インスタンスの [説明] を入力します。
    5. サービス アカウント: 必要なロールを持つサービス アカウントを選択します。
    6. 必要に応じて、接続ノードの設定を構成します。

      • ノードの最小数: 接続ノードの最小数を入力します。
      • ノードの最大数: 接続ノードの最大数を入力します。

      ノードは、トランザクションを処理する接続の単位（またはレプリカ）です。1 つの接続でより多くのトランザクションを処理するには、より多くのノードが必要になります。逆に、より少ないトランザクションを処理するには、より少ないノードが必要になります。ノードがコネクタの料金に与える影響については、接続ノードの料金をご覧ください。値を入力しない場合は、デフォルトで最小ノード数は 2 に設定され（可用性を高めるため）、最大ノード数は 50 に設定されます。

    7. スキーマ: データベース スキーマとしてアクセスする Xero API。
    8. Tenant: 接続先の Xero 組織を設定します。名前またはテナント ID を指定できます。
    9. 詳細レベル: 接続の冗長性レベルは 1 ～ 5 です。詳細レベルが高いと、すべての通信の詳細（リクエスト、レスポンス、SSL 証明書）がログに記録されます。
    10. 必要に応じて、[+ ラベルを追加] をクリックして Key-Value ペアの形式でラベルを接続に追加します。
    11. [Next] をクリックします。
  5. [認証] セクションで、認証の詳細を入力します。
    1. [認証タイプ] を選択し、関連する詳細を入力します。

      Xero 接続でサポートされる認証タイプは次のとおりです。

      • OAuth 2.0 クライアント認証情報
      • OAuth 2.0 認証コードの付与

      2. これらの認証タイプの構成方法については、認証を構成するをご覧ください。

    2. [Next] をクリックします。
  6. レビュー: 接続と認証の詳細を確認します。
  7. [Create（作成）] をクリックします。

認証を構成する

使用する認証に基づいて詳細を入力します。

  • OAuth 2.0 クライアント認証情報
    • クライアント ID: 作成したアプリのコネクタから提供されるクライアント ID。
    • クライアント シークレット: 作成した接続されているアプリのクライアント シークレットを含む Secret Manager のシークレットです。
  • OAuth 2.0 認証コードの付与
    • アクセス トークン: auth-code-flow-based 接続でリクエストを認証するために使用されるアクセス トークン。
    • クライアント ID: アクセス トークンのリクエストに使用されるクライアント ID。
    • クライアント シークレット: アクセス トークンのリクエストに使用されるクライアント シークレット。

エンティティ、オペレーション、アクション

すべての Integration Connectors が、接続されたアプリケーションのオブジェクトを抽象化するレイヤを提供します。アプリケーションのオブジェクトには、この抽象化を通じてのみアクセスできます。抽象化は、エンティティ、オペレーション、アクションとして公開されます。

  • エンティティ: エンティティは、接続されているアプリケーションやサービスのオブジェクト、またはプロパティのコレクションと考えることができます。エンティティの定義は、コネクタによって異なります。たとえば、データベース コネクタでは、テーブルがエンティティであり、ファイル サーバー コネクタでは、フォルダがエンティティです。また、メッセージング システム コネクタでは、キューがエンティティです。

    ただし、コネクタでいずれのエンティティもサポートされていない、またはエンティティが存在しない可能性があります。その場合、Entities リストは空になります。

  • オペレーション: エンティティに対して行うことができるアクティビティです。エンティティに対して次のいずれかのオペレーションを行うことができます。

    使用可能なリストからエンティティを選択すると、そのエンティティで使用可能なオペレーションのリストが生成されます。オペレーションの詳細については、コネクタタスクのエンティティ オペレーションをご覧ください。ただし、コネクタがどのエンティティ オペレーションもサポートしていない場合、サポートされていないオペレーションは Operations リストに表示されません。

  • アクション: コネクタ インターフェースを介して統合で使用できる最初のクラス関数です。アクションを使用すると、1 つまたは複数のエンティティに対して変更を加えることができます。また、使用できるアクションはコネクタごとに異なります。ただし、コネクタがどのアクションもサポートしていない可能性があります。その場合は、Actions リストが空になります。

統合で Xero 接続を使用する

システムの上限

Xero コネクタは、ノードごとに 1 秒あたり 5 つのトランザクションを処理でき、この上限を超えるトランザクションをスロットルします。 ただし、Xero コネクタで処理できるトランザクション数は、Xero インスタンスによる制約によって異なります。詳細については、Xero API のレート上限をご覧ください。デフォルトでは、Integration Connectors は、接続に 2 つのノードを割り当てます（可用性を高めるため）。

Integration Connectors に適用される上限の詳細については、上限をご覧ください。

アクション

このセクションでは、コネクタでサポートされているアクションを一覧表示します。アクションの構成方法については、アクションの例をご覧ください。

DownloadAttachment アクション

このアクションでは、添付ファイルをダウンロードします。

DownloadAttachment アクションの入力パラメータ

パラメータ名 データ型 必須 説明
ファイル名 文字列 いいえ ダウンロードする添付ファイルの名前。
テーブル 文字列 いいえ 添付ファイルをダウンロードする必要があるテーブルの名前。
ObjectId 文字列 いいえ 添付ファイルの ObjectId。

DownloadAttachment アクションの出力パラメータ

このアクションは、ダウンロードが正常に完了した場合、ステータス 200（OK）を返します。

DownloadAttachment アクションの構成方法については、アクションの例をご覧ください。

UploadAttachment アクション

このアクションにより、添付ファイルをアップロードできます。

UploadAttachment アクションの入力パラメータ

パラメータ名 データ型 必須 説明
ファイル名 文字列 いいえ アップロードする添付ファイルの名前。
ObjectId 文字列 いいえ 添付ファイルの ObjectId。
ContentType 文字列 いいえ 添付ファイルのコンテンツ タイプ。
テーブル 文字列 いいえ 添付ファイルをアップロードする必要があるテーブルの名前。
コンテンツ 文字列 いいえ 添付ファイルの内容

UploadAttachment アクションの出力パラメータ

このアクションは、オブジェクトのアップロードが成功した場合、ステータス 200（OK）を返します。

UploadAttachment アクションの構成方法については、アクションの例をご覧ください。

ListAttachment アクション

このアクションにより、テーブルのすべての添付ファイルを一覧表示できます。

ListAttachment アクションの入力パラメータ

パラメータ名 データ型 必須 説明
ObjectId 文字列 いいえ 添付ファイルのオブジェクト ID。
テーブル 文字列 いいえ 添付ファイルを一覧表示する必要があるテーブルの名前。

ListAttachment アクションの出力パラメータ

このアクションは、削除が正常に完了した場合、ステータス 200（OK）を返します。

ListAttachment アクションの構成方法については、アクションの例をご覧ください。

SendInvoiceMail アクション

このアクションにより、請求書の発行者にメールを送信できます。

SendInvoiceMail アクションの入力パラメータ

パラメータ名 データ型 必須 説明
InvoiceId 文字列 いいえ メールを送信する必要がある請求書の ID。

SendInvoiceMail アクションの出力パラメータ

このアクションは、移動オペレーションが正常に完了した場合、ステータス 200（OK）を返します。

SendInvoiceMail アクションの構成方法については、アクションの例をご覧ください。

UploadFile アクション

このアクションにより、ファイルをアップロードできます。

UploadFile アクションの入力パラメータ

パラメータ名 データ型 必須 説明
名前 文字列 いいえ アップロードするファイルの名前。
コンテンツ 文字列 いいえ アップロードするファイル コンテンツ。

UploadFile アクションの出力パラメータ

このアクションは、オブジェクトのアップロードが成功した場合、ステータス 200（OK）を返します。

UploadFile アクションの構成方法については、アクションの例をご覧ください。

アクションの例

このセクションでは、このコネクタでいくつかのアクションを実行する方法について説明します。

例 - 添付ファイルをダウンロードする

この例では、添付ファイルをダウンロードします。

  1. [Configure connector task] ダイアログで、[Actions] をクリックします。
  2. [DownloadAttachment] アクションを選択してから、[完了] をクリックします。
  3. [コネクタ] タスクの [タスク入力] セクションで、connectorInputPayload をクリックし、Default Valueフィールドに次のような値を入力します。 
    {
"Filename": "Xero_Test.txt",
"Table": "Contacts",
"ObjectId": "6a92a3ab-87cf-4f2f-8beb-ecb4f8ae4d41"
}

    4. アクションが成功すると、DownloadAttachment タスクの connectorOutputPayload レスポンス パラメータの値は次のようになります。

    [{
"Success": "True",
"Content": "Test content"
}]

例 - 添付ファイルをアップロードする

この例では、添付ファイルをアップロードします。

  1. [Configure connector task] ダイアログで、[Actions] をクリックします。
  2. [UploadAttachment] アクションを選択してから、[完了] をクリックします。
  3. [コネクタ] タスクの [タスク入力] セクションで、connectorInputPayload をクリックし、Default Valueフィールドに次のような値を入力します。 
    {
"Filename": "Xero_Test.txt",
"ObjectId": "6a92a3ab-87cf-4f2f-8beb-ecb4f8ae4d41",
"ContentType": "txt",
"Table": "Contacts",
"Content": "Test content upload attachment"
}

    4. アクションが成功すると、UploadAttachment タスクの connectorOutputPayload レスポンス パラメータの値は次のようになります。

    [{
"Success": null,
"AttachmentId": "5ba982a6-9294-45a7-bdda-5f134b0d69d5",
"FileName": "Xero_Test.txt",
"URL": "https://api.xero.com/api.xro/2.0/Contacts/6a92a3ab-87cf-4f2f-8bwb-fcb4f8ae4d41/Attachments/Xero_Test.txt",
"MimeType": "text/plain",
"ContentLength": "27",
"IncludeOnline": null,
"_": ""
}, {
"Success": null,
"AttachmentId": null,
"FileName": null,
"URL": null,
"MimeType": null,
"ContentLength": null,
"IncludeOnline": null,
"_": null
}]

例 - 添付ファイルを一覧表示する

この例では、指定したテーブルの添付ファイルを一覧表示します。

  1. [Configure connector task] ダイアログで、[Actions] をクリックします。
  2. [ListAttachment] アクションを選択してから、[完了] をクリックします。
  3. [コネクタ] タスクの [タスク入力] セクションで、connectorInputPayload をクリックし、Default Valueフィールドに次のような値を入力します。 
    {
"ObjectId": "6a92a3ab-87cf-4f2f-8beb-ecb4f8ae4d41",
"Table": "Contacts"
}

    4. アクションが成功すると、ListAttachment タスクの connectorOutputPayload レスポンス パラメータの値は次のようになります。

    [{
"AttachmentId": "5ba982a6-9294-45a7-bdda-5f134b0d69d5",
"FileName": "Xero_Limit_Testing.txt",
"URL": "https://api.xero.com/api.xro/2.0/Contacts/6a92a3ab-87cf-4f2f-8bwb-fcb4f8ae4d41/Attachments/Xero_Test.txt",
"MimeType": "text/plain",
"ContentLength": "27"
}]

例 - 請求書メールを送信する

この例では、指定された請求書のメールを送信します。

  1. [Configure connector task] ダイアログで、[Actions] をクリックします。
  2. [SendInvoiceMail] アクションを選択してから、[完了] をクリックします。
  3. [コネクタ] タスクの [タスク入力] セクションで、connectorInputPayload をクリックし、Default Valueフィールドに次のような値を入力します。 
    {
"InvoiceId": "016a64c7-be0b-45a2-acae-13057fdf1566"
}

    4. アクションが成功すると、SendInvoiceMail タスクの connectorOutputPayload レスポンス パラメータの値は次のようになります。

    [{
"Success": "true"
}]

例 - ファイルをアップロードする

この例では、ファイルをアップロードします。

  1. [Configure connector task] ダイアログで、[Actions] をクリックします。
  2. [UploadFile] アクションを選択してから、[完了] をクリックします。
  3. [コネクタ] タスクの [タスク入力] セクションで、connectorInputPayload をクリックし、Default Valueフィールドに次のような値を入力します。 
    {
"Name": "Sample1.txt",
"Content": "This is a sample file"
}

    4. アクションが成功すると、UploadFile タスクの connectorOutputPayload レスポンス パラメータの値は次のようになります。

    [{
"Success": "true",
"FileId": "09039c7b-35a2-473d-aa79-16fe00b8d460",
"Name": "Sample1.txt",
"FolderId": "36e5115d-a9b6-4c22-baf3-40a8b28ee71d",
"MimeType": "text/plain",
"Size": 26.0,
"User_Id": "c1e33cc9-eb61-45cb-9e46-3ea4121cbdc6",
"User_Name": "test_user_1@test.com",
"User_FirstName": "John",
"User_LastName": "Smith",
"User_FullName": "John Smith",
"Created": "2023-12-18 17:38:53.01",
"Updated": "2023-12-18 17:38:53.01"
}]

エンティティ オペレーションの例

このセクションでは、このコネクタでエンティティ オペレーションの一部を実行する方法について説明します。

例 - すべてのレコードを一覧表示する

この例では、Accounts エンティティ内のすべてのレコードを一覧表示します。

  1. [Configure connector task] ダイアログで、[Entities] をクリックします。
  2. Entity から Accounts を選択します。
  3. [List] オペレーションを選択してから、[完了] をクリックします。
  4. 必要に応じて、コネクタタスクの [タスク入力] セクションでフィルタ句を指定して、結果セットをフィルタリングできます。 例: City='Bangalore'また、論理演算子を使用して複数のフィルタ条件を指定することもできます。例: City='Bangalore' and region='asia-south2'。

例 - 請求書を取得する

この例では、Invoices エンティティから、指定された ID の請求書を取得します。

  1. [Configure connector task] ダイアログで、[Entities] をクリックします。
  2. Entity から Invoices を選択します。
  3. [Get] オペレーションを選択してから、[完了] をクリックします。
  4. [コネクタ] タスクの [タスク入力] セクションで [EntityId] をクリックし、[デフォルト値] フィールドに 1|016a64c7-be0b-45a2-acae-13057fdf1566 を入力します。

    ここで、1|016a64c7-be0b-45a2-acae-13057fdf1566 は Invoices エンティティの主キー値です。

例 - 請求書を作成する

この例では、Invoices エンティティに請求書を作成します。

  1. [Configure connector task] ダイアログで、[Entities] をクリックします。
  2. Entity から Invoices を選択します。
  3. [Create] オペレーションを選択してから、[完了] をクリックします。
  4. [コネクタ] タスクの [タスク入力] セクションで、connectorInputPayload をクリックし、Default Valueフィールドに次のような値を入力します。 
    {
"Type": "ACCPAY",
"ContactName": "ContactName1",
"LineItem_Description": "LineItemDescription"
}

    統合に成功すると、コネクタタスクの connectorOutputPayload フィールドの値は次のようになります。

    {
"Id": "1|7b29efe9-dacd-47bb-85a6-0c0640ce25de"
}

例 - レコードを更新する

この例では、AssetTypes エンティティに レコードを作成します。

  1. [Configure connector task] ダイアログで、[Entities] をクリックします。
  2. Entity から AssetTypes を選択します。
  3. [Update] オペレーションを選択してから、[完了] をクリックします。
  4. [コネクタ] タスクの [タスク入力] セクションで、connectorInputPayload をクリックし、Default Valueフィールドに次のような値を入力します。 
    {
"BookDepreciationSetting_DepreciationRate": 10.0
}
  5. [エンティティ ID] をクリックし、[デフォルト値] フィールドに「f8d43548-25b0-4cc3-8f59-d97106974fe8」と入力します。

    統合に成功すると、コネクタタスクの connectorOutputPayload フィールドの値は次のようになります。

    {
"AssetTypeId": "f8d43548-25b0-4cc3-8f59-d97106974fe8"
}

例 - ファイルを削除する

この例では、指定した ID を持つファイルを Files エンティティから削除します。

  1. [Configure connector task] ダイアログで、[Entities] をクリックします。
  2. Entity から Files を選択します。
  3. [Delete] オペレーションを選択してから、[完了] をクリックします。
  4. [コネクタタスクの [タスク入力 セクションで [entityId] をクリックし、[デフォルト値] フィールドに 421c82f0-38fb-4074-a679-63b04c0d8832 を入力します。

接続を作成すると、Apigee Integration と Application Integration の両方で使用できるようになります。この接続は、コネクタタスクを介して統合で使用できます。

  • Apigee Integration で Connectors タスクを作成して使用する方法については、Connectors タスクをご覧ください。
  • Application Integration で Connectors タスクを作成して使用する方法については、Connectors タスクをご覧ください。

Google Cloud コミュニティの助けを借りる

Google Cloud コミュニティの Cloud フォーラムで質問を投稿したり、このコネクタについてディスカッションしたりできます。

次のステップ