コネクタタスク

コネクタタスクでは、すぐに利用できる Integration Connectors のコネクタを使用して、インテグレーションからさまざまな Google Cloud サービスやその他のビジネス アプリケーションにすばやく確実に接続できます。

Apigee Integration でサポートされているすべてのコネクタの一覧については、コネクタ リファレンスをご覧ください。

始める前に

  • Google Cloud プロジェクトに対してコネクタ管理者（roles/connectors.admin）IAM ロールが付与されていることを確認します。ロールの付与の詳細については、アクセスの管理をご覧ください。
  • Integration Connectors の一般的なコンセプトについて確認します。
  • コネクタを使用して Google Cloud サービスや他のビジネス アプリケーションに接続するには、ご使用の Integration にユーザー管理のサービス アカウントが接続されていることを確認してください。ご使用の Integration にユーザー管理のサービス アカウントが構成されていない場合は、デフォルトで、デフォルトのサービス アカウント（service-PROJECT_NUMBER@gcp-sa-apigee.iam.gserviceaccount.com）が認証に使用されます。
  • サービス アカウントに必要な IAM ロールがあることを確認します。サービス アカウントへのロールの付与については、サービス アカウントに対するアクセス権の管理をご覧ください。

コネクタタスクを追加する

統合にコネクタタスクを追加する手順は次のとおりです。

  1. Apigee UI で、Apigee 組織を選択します。
  2. [Develop] > [Integrations] の順にクリックします。
  3. 既存のインテグレーションを選択するか、[Create Integration] をクリックして新しいインテグレーションを作成します。

    新しいインテグレーションを作成する場合:

    1. [Create Integration] ダイアログで名前と説明を入力します。
    2. サポートされているリージョンのリストから、インテグレーションのリージョンを選択します。
    3. [Create] をクリックします。

    インテグレーション デザイナーでインテグレーションが開きます。

  4. インテグレーション デザイナーのナビゲーション バーで、[+ Add a task/trigger] > [Tasks] の順にクリックして、使用可能なタスクのリストを表示します。

    5. コネクタタスクを示す画像

  5. 新しい接続を構成する場合は、統合エディタでコネクタ要素をクリックして配置します。[コネクタの構成] をクリックして接続を構成します。

    コネクタタスクのリストが表示されている画像 コネクタタスクのリストが表示されている画像

  6. 既存の接続がある場合は、[コネクタ] タブをクリックして、最近作成した接続を表示します。[検索] フィールドに名前を入力すると、コネクタ、接続、タスクを検索できます。

    コネクタタスクの検索機能を示す画像

  7. 統合エディタでコネクタ要素をクリックして配置します。コネクタタスクを構成する方法については、コネクタタスクを構成するをご覧ください。

コネクタタスクを構成する

コネクタタスクを構成するには、次の手順を行います。

  1. デザイナーで [コネクタ] タスク要素をクリックして、[コネクタ] タスク構成ペインを表示します。

    必要に応じて、[] をクリックしてタスク名を変更します。

  2. [コネクタを設定する] をクリックします。
  3. リージョン内で既存の接続を選択するか、新しい接続を作成することができます。既存の接続を構成するには、[Connectors Task Editor] ページで次の手順を完了します。

    次の画像は、[Connectors Task Editor] ページのサンプル レイアウトを示しています。[Configure connector task] ダイアログを示す画像 [Configure connector task] ダイアログを示す画像

    1. [Select connection] セクションで、接続のリージョンを選択します。
    2. 選択したリージョンで利用可能な接続のリストから、既存の接続を選択します。
    3. [次へ] をクリックします。
    4. [タイプ] リストで [エンティティ] または [アクション] を選択します。
      • [エンティティ] を選択すると、接続でサポートされているエンティティのリストが [Set entities/actions] セクションに表示されます。エンティティを選択してから、そのエンティティで行う [オペレーション] を選択します。
      • [アクション] を選択すると、接続でサポートされているアクションのリストが [Set entities/actions] 列に表示されます。接続のアクションを選択します。
        • サポートされるエンティティとアクションは、コネクタの種類によって異なります。Apigee Integration でサポートされているすべてのコネクタの一覧については、コネクタ リファレンスをご覧ください。コネクタでサポートされているアクションとエンティティを確認するには、各コネクタのドキュメントをご覧ください。

        コネクタがカスタム SQL クエリをサポートしている場合は、[アクション] リストで [カスタムクエリを実行する] オプションを選択します。コネクタにカスタム SQL クエリを追加する方法については、アクション: カスタム SQL クエリを実行するをご覧ください。

    5. [完了] をクリックして接続の構成を完了し、ペインを閉じます。

タスクの入出力変数を構成する

コネクタタスク構成ペインには、[Configure connector task] ダイアログで選択したエンティティとオペレーションまたはアクションに基づいて自動生成されたタスク入力とタスク出力の変数が表示されます。これらの変数は構成可能です。これらの変数は、現在のタスクへの入力として、または現在のインテグレーションで後続のタスクまたは条件への出力としてアクセスできます。

タスク入力変数またはタスク出力変数を構成するには、それぞれの変数をクリックして、[Configure Variable] ペインを開き、次の手順を行います。

  1. [デフォルト値] フィールドに変数値を入力します。
  2. （省略可）[Use as an input to integration] または [Use as an output to integration] を選択します。
  3. [保存] をクリックします。

コネクタタスクの入出力パラメータの詳細については、エンティティ オペレーションをご覧ください。

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

コネクタのエンティティで CRUD（作成、読み取り、更新、削除）オペレーションを行うことができます。これらのエンティティ オペレーションでは、それぞれ入力パラメータと出力パラメータのセットが異なります。次のテーブルに、さまざまなエンティティ オペレーションの入力パラメータと出力パラメータが示されています。

オペレーション名 入力パラメータ 出力パラメータ
List（リスト）
  • listEntitiesPageSize
  • listEntitiesPageToken
  • listEntitiesSortByColumns
  • filterClause
  • connectorOutputPayload
  • listEntitiesNextPageToken
Get（取得） entityId connectorOutputPayload
Create（作成） connectorInputPayload connectorOutputPayload
Update（更新）
  • connectorInputPayload
  • entityId
  • filterClause
 connectorOutputPayload
Delete（削除）
  • entityId
  • filterClause
 該当なし

入力パラメータ

次のテーブルに、さまざまなエンティティ オペレーションの入力パラメータを示します。

パラメータ名 データ型 説明
entityId 文字列

アクセスする行の固有識別子。

通常、entityId はテーブルまたはデータセットの主キーの値です。entityId の値を指定し、テーブルまたはデータセットに主キー列がない場合は、インテグレーションによってランタイム エラーが報告され、コネクタタスクは失敗します。

たとえば、MySQL テーブルから特定の行を取得するには、entityId をテーブルの主キー値として使用します。
connectorInputPayload JSON エンティティで追加または更新される実際のデータ。次の例は、テーブルに追加される行データの JSON スニペットを示しています。 
{
"employee_first_name": "John",
"employee_emailID": "test-05@test.com"
}

この例では、employee_first_name と employee_emailID は列名で、それぞれ対応する値 John と test-05@test.com を持っています。
filterClause 文字列 条件に基づいてオペレーションの結果を制限します。フィルタ句の追加について詳しくは、オペレーション用のフィルタを追加するをご覧ください。
listEntitiesPageSize 整数

ページで返される結果の数を指定します。

ページは、結果セットのレコードの論理グループです。ページのコンセプトは、結果セットに多数のレコードが含まれることが予想される場合に有効に活用できます。結果セットのサイズが大きい場合、コネクタタスクが処理できるデータサイズには上限があるため、コネクタタスクが失敗する可能性があります。この問題は、結果セットをより小さなチャンクに分割することで回避できます。

たとえば、結果セットで 1,000 件のレコードが想定される場合は、listEntitiesPageSize を 100 に設定できます。したがって、コネクタタスクの初回実行時には最初の 100 件のレコードが返され、2 回目の実行時には次の 100 件のレコードが返されるといった具合です。
listEntitiesPageToken 文字列

特定のページへのアクセスを可能にするページ識別子（トークン）。

ページトークンの値は、listEntitiesNextPageToken 出力パラメータから取得できます。各ページには一意のトークンがあるため、結果セット内のどのページにも柔軟にアクセスできます。このパラメータの使用方法については、listEntitiesNextPageToken 出力パラメータの説明もご覧ください。
listEntitiesSortByColumns 文字列配列 結果セットの並べ替えに使用する列の名前。

出力パラメータ

次のテーブルに、さまざまなエンティティ オペレーションの出力パラメータを示します。

パラメータ名 データ型 説明
connectorOutputPayload JSON オペレーションの出力（JSON 形式）。
listEntitiesNextPageToken 文字列

システムが生成したページの識別子。トークンは、結果セットの特定のページにアクセスするためのポインタと考えられます。

listEntitiesPageSize パラメータを設定して結果セットを複数のページに分割している場合は、ページ間を移動するメカニズムが必要です。listEntitiesNextPageToken 出力パラメータを使用すると、この操作を実現できます。コネクタタスクが実行されるたびに、システムは次のページのトークンを生成し、listEntitiesNextPageToken の値を新しく生成されたトークンに設定します。このトークンを使用して、結果セットの次のページにアクセスできます。次のページにアクセスするには、listEntitiesPageToken 入力パラメータを次のページのトークン値に設定する必要があります。

たとえば、listEntitiesPageSize パラメータを 2 に設定しており、コネクタタスクを初めて実行するときに listEntitiesNextPageToken を ChoKC2VtcGxveWVlX2lkEgkRAAAAAAAA8D8YDw== トークン値に設定したとします。その後、listEntitiesPageToken 入力パラメータにこのトークン値を設定すると、後続のコネクタタスクの実行時に次のページを取得できます。

結果セットのページ数が多い場合は、For Each Loop タスクを使用してコネクタタスクを繰り返し呼び出し、データ マッピング タスクを使用して実行が完了するたびに listEntitiesPageToken 入力パラメータに自動的にトークン値を割り当てることを検討できます。

エンティティ オペレーションのフィルタ句

タスクの入力として使用可能なフィルタ句変数を使用して、コネクタタスクによって処理されるレコードを制限できます。たとえば、削除オペレーションの場合、特定の orderId を含むレコードを削除するフィルタ句を追加できます。

フィルタ句は、次のエンティティ オペレーションにのみ適用できます。

  • List（リスト）
  • Delete（削除）
  • Update（更新）

これらのオペレーションのいずれかを選択すると、コネクタタスクの [Task Input] セクションに [Filter clause] フィールドが自動的に表示されます。

フィルタ句を追加

フィルタ句を追加する手順は、次のとおりです。

  1. デザイナーでコネクタタスク要素をクリックして、コネクタタスク構成ペインを表示します。
  2. [Task Input] セクションを開き、[filterClause(Connectors)] 文字列変数をクリックします。

    [Configure Variable] ダイアログが表示されます。

  3. [デフォルト値] フィールドにフィルタ句（syntax 句の後）を入力します。
  4. [保存] をクリックします。

フィルタ句の構文と例

フィルタ句の形式は次のとおりです。

FIELD_NAME CONDITION FILTER_VALUE

例

  • OwnerId = '0053t000007941XAAQ'
  • PoNumber < 2345
  • OrderNumber = 00110 AND StatusCode = 'Draft'
  • TotalAmount > 2500
  • ShippingPostalCode = 94043 OR ShippingPostalCode = 77002

フィルタ句での変数の使用

フィルタ句でイ統合変数を直接使用することはできません。統合変数を使用する場合は、まずデータ マッピング タスクを構成して、統合変数とフィルタ句間のマッピングを作成する必要があります。

次のテーブルに、統合変数と filterClause(Connectors) 変数間のマッピング例を示します。

入力 出力
PRIMARY_KEY_ID = ' .CONCAT(INTEGRATION_VARIABLE) .CONCAT(') filterClause(Connectors)
ここで、PRIMARY_KEY_ID = ' は入力行に値として入力されています。

アクション: カスタム SQL クエリを実行する

カスタムクエリを作成する手順は次のとおりです。

  1. 詳細な手順に沿って、コネクタタスクを追加します。
  2. コネクタタスクを構成するときに、実行するアクションの種類で [Actions] を選択します。
  3. [Actions] リストで [Execute custom query] を選択し、[Done] をクリックします。

    execute-custom-query-action を示す画像 execute-custom-query-action を示す画像

  4. [Task input] セクションを開き、次の操作を行います。
    1. [Timeout after] フィールドに、クエリが実行されるまで待機する秒数を入力します。

      デフォルト値: 180 秒

    2. [Maximum number of rows] フィールドに、データベースから返される最大行数を入力します。

      デフォルト値: 25。

    3. カスタムクエリを更新するには、[Edit Custom Script] をクリックします。[Script editor] ダイアログが開きます。

      custom-sql-query を示す画像 custom-sql-query を示す画像

    4. [Script editor] ダイアログで、SQL クエリを入力して [Save] をクリックします。

      SQL ステートメントで疑問符（?）を使用して、クエリ パラメータ リストで指定する必要がある 1 つのパラメータを表すことができます。たとえば、次の SQL クエリは、LastName 列に指定された値と一致する Employees テーブルからすべての行を選択します。 

      SELECT * FROM Employees where LastName=?

    5. SQL クエリで疑問符を使用した場合は、各疑問符の [+ Add Parameter Name] をクリックして、パラメータを追加する必要があります。統合の実行中に、これらのパラメータにより SQL クエリ内の疑問符（?）が順番に置き換わります。たとえば、3 つの疑問符（?）を追加した場合、3 つのパラメータを順番に追加する必要があります。

      add-query-param を示す画像 add-query-param を示す画像

      クエリ パラメータを追加する手順は次のとおりです。

      1. [Type] リストから、パラメータのデータ型を選択します。
      2. [Value] フィールドに、パラメータの値を入力します。
      3. 複数のパラメータを追加するには、[+ Add Query Parameter] をクリックします。

スキーマの更新

すべてのエンティティとアクションに、関連するスキーマがあります。たとえば、アクション スキーマにはパラメータの詳細（パラメータ名や対応するデータ型など）が含まれます。エンティティとアクションのスキーマ（メタデータ）は、ランタイムに接続によってバックエンドから取得されます。スキーマが更新されても、既存の接続には自動的に反映されません。スキーマを手動で更新する必要があります。既存のコネクタタスクで更新されたスキーマを表示するには、次の操作を行います。
  1. Integration Connectors で、接続の詳細ページを開き、[Refresh connection schema] をクリックします。
  2. Apigee Integration で、同じ接続に対して既存のコネクタタスクを再構成する必要があります。

インライン接続の作成

コネクタタスクを使用して、Integration Connectors で新しい接続を直接作成できます。

始める前に

接続の新規作成

Apigee Integration から新しい接続を作成するには、次の手順を行います。

  1. デザイナーで [コネクタ] タスク要素をクリックして、[コネクタ] タスク構成ペインを表示します。
  2. [コネクタを設定する] をクリックします。

    [Connectors Task Editor] ページが表示されます。

  3. [リージョン] フィールドはスキップします。
  4. [接続] をクリックし、プルダウン メニューから [接続を作成] オプションを選択します。
  5. [接続を作成] ペインで、次の操作を行います。
    1. [ロケーション] ステップで、接続のロケーションを選択します。
      1. [リージョン] をクリックし、プルダウン リストからロケーションを選択します。
      2. [次へ] をクリックします。
    2. [接続の詳細] ステップで、接続の詳細を入力します。
      1. コネクタ: 作成するコネクタのタイプをプルダウン リストから選択します。サポートされているコネクタのリストについては、すべての Integration Connectors をご覧ください。
      2. コネクタのバージョン: プルダウン リストから、選択したコネクタタイプの使用可能なバージョンを選択します。
      3. 接続名: 接続インスタンスの名前を入力します。
      4. （オプション）接続インスタンスの [説明] を入力します。
      5. （オプション）接続インスタンスのログデータを保存するには、[Cloud Logging を有効にする] をオンにします。
      6. サービス アカウント: 必要なロールを持つサービス アカウントを選択します。
      7. （オプション）[詳細設定] をクリックして接続ノードの設定を構成します。

        詳しくは、Integration Connectors のそれぞれの接続に関するドキュメントをご覧ください。

      8. （オプション）[+ ラベルを追加] をクリックして Key-Value ペアの形式でラベルを接続に追加します。
      9. [次へ] をクリックします。
    3. [認証] ステップで、接続の認証の詳細を入力します。
      1. このステップでは、作成された接続タイプに基づいた認証方法で入力されます。

        接続タイプによって認証方法は異なります。詳細については、Integration Connectors のそれぞれの接続に関するドキュメントの認証を構成するのセクションをご覧ください。

      2. [次へ] をクリックします。
    4. レビュー: 接続と認証の詳細を確認します。
    5. [作成] をクリックします。

おすすめの方法

エラー処理方式

タスクのエラー処理方法では、一時的なエラーによってタスクが失敗した場合のアクションを指定します。エラー処理方式と、さまざまな種類のエラー処理方式の詳細については、エラー処理方法をご覧ください。