IntegrationCallout ポリシー

このページは Apigee と Apigee ハイブリッドに適用されます。

ポリシーアイコン

概要

IntegrationCallout ポリシーを使用すると、API トリガーを持つ Apigee Integration を実行できます。ただし、統合を実行する前に、SetIntegrationRequest ポリシーを実行する必要があります。SetIntegrationRequest ポリシーは、リクエストオブジェクトを作成して、そのオブジェクトをフロー変数として IntegrationCallout ポリシーで使用できるようにします。リクエストオブジェクトには、API トリガー名、統合プロジェクト ID、統合名などの統合の詳細があり、SetIntegrationRequest ポリシーで構成されています。IntegrationCallout ポリシーは、リクエストオブジェクトのフロー変数を使用して統合を実行します。統合実行レスポンスをフロー変数に保存するように、IntegrationCallout ポリシーを構成できます。

IntegrationCallout ポリシーは、プロキシフローの途中で統合を実行する場合に役立ちます。また、IntegrationCallout ポリシーを構成する代わりに、統合エンドポイントをターゲットエンドポイントとして指定して統合を実行することもできます。詳細については、IntegrationEndpoint をご覧ください。

このポリシーは拡張可能なポリシーです。Apigee ライセンスによっては、このポリシーの使用によって費用や使用量に影響する場合があります。ポリシータイプと使用量への影響については、ポリシータイプをご覧ください。

注: IntegrationCallout ポリシーを実行するには、認証トークンが必要です。ただし、ポリシー定義に明示的な Authentication 要素はありません。Apigee は、内部でリクエストに認証トークンを追加します。IntegrationCallout ポリシーが正常に認証されるようにするには、統合の実行に必要な IAM ロールを持つサービスアカウントで API プロキシをデプロイする必要があります。必要なロールについては、統合の IAM ロールをご覧ください。API プロキシのデプロイの詳細については、Apigee にデプロイするをご覧ください。

`<IntegrationCallout>`

IntegrationCallout ポリシーを指定します。

デフォルト値	なし
必須かどうか	必須
型	複合型
親要素	なし
子要素	`<DisplayName>` `<AsyncExecution>` `<Request>` `<Response>`

次の表は、<IntegrationCallout> の子要素の概要をまとめたものです。

子要素	必須かどうか	説明
`<DisplayName>`	省略可	ポリシーのカスタム名。
`<AsyncExecution>`	省略可	統合を同期モードと非同期モードのどちらで実行するかを指定します。
`<Request>`	必須	SetIntegrationRequest ポリシーによって作成されたリクエストオブジェクトを持つフロー変数。
`<Response>`	省略可	統合のレスポンスを保存するフロー変数。

<IntegrationCallout> 要素の構文は次のとおりです。

構文

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<IntegrationCallout continueOnError="[true|false]" enabled="[true|false]" name=POLICY_NAME>
  <DisplayName>POLICY_DISPLAY_NAME</DisplayName>
  <AsyncExecution>BOOLEAN_ASYNC_EXECUTION</AsyncExecution>
  <Request clearPayload="[true|false]">REQUEST_FLOW_VARIABLE_NAME</Request>
  <Response>RESPONSE_FLOW_VARIABLE_NAME</Response>
</IntegrationCallout>

例

次の例は、IntegrationCallout ポリシーの定義を示しています。

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<IntegrationCallout continueOnError="false" enabled="true" name="Integration-Callout">
  <DisplayName>Integration-Callout-1</DisplayName>
  <AsyncExecution>true</AsyncExecution>
  <Request clearPayload="true">my_request_flow_var</Request>
  <Response>my_response_flow_var</Response>
</IntegrationCallout>

この要素には、すべてのポリシーに共通する次の属性があります。

属性	デフォルト	必須かどうか	説明
`name`	なし	必須	ポリシーの内部名。`name` 属性の値には、英字、数字、スペース、ハイフン、アンダースコア、ピリオドを使用できます。この値は 255 文字を超えることはできません。管理 UI プロキシエディタで `<DisplayName>` 要素を追加して、ポリシーのラベルに使用する別の自然言語名を指定することもできます。
`continueOnError`	false	省略可	ポリシーが失敗したときにエラーを返す場合は、`false` に設定します。これは、ほとんどのポリシーで想定される動作です。ポリシーが失敗した後もフローの実行を続行する場合は、`true` に設定します。関連情報: 障害ルールはエラー状態の場合にのみトリガーされる（continueOnError について）現在のフローにおける障害処理
`enabled`	true	省略可	ポリシーを適用するには、`true` に設定します。ポリシーを無効にするには、`false` に設定します。ポリシーがフローに接続されている場合でも適用されません。
`async`	false	非推奨	この属性は非推奨となりました。

子要素のリファレンス

このセクションでは、<IntegrationCallout> の子要素について説明します。

`<DisplayName>`

name 属性に加えて、管理 UI プロキシエディタでポリシーを別の、より自然な響きの名前でラベル付けするために使います。

<DisplayName> 要素はすべてのポリシーに共通です。

デフォルト値	なし
必須かどうか	省略可。`<DisplayName>` を省略した場合、ポリシーの `name` 属性の値が使用されます。
型	文字列
親要素	<`PolicyElement`>
子要素	なし

<DisplayName> 要素の構文は次のとおりです。

構文

<PolicyElement>
  <DisplayName>POLICY_DISPLAY_NAME</DisplayName>
  ...
</PolicyElement>

例

<PolicyElement>
  <DisplayName>My Validation Policy</DisplayName>
</PolicyElement>

<DisplayName> 要素に属性や子要素はありません。

`<AsyncExecution>`

統合を実行するモードを指定します。統合は同期または非同期で行うことができます。

true に設定すると、統合は非同期的に実行されます。false に設定すると、統合が同期的に実行されます。

非同期モード: 統合の実行リクエストがエンドポイントに到達すると、エンドポイントはすぐに統合実行 ID を返しますが、<ScheduleTime> 要素で指定された時間に統合の実行を開始します。<ScheduleTime> 要素を設定していない場合、統合はすぐに実行されるようスケジュールされます。統合はすぐに実行されるようスケジュールされていますが、数秒後に実行が開始されることがあります。統合の実行が開始されると、次の 2 つの処理が行われます。
- 統合は HTTP 200 OK ステータスコードを返します。これにより、呼び出し元は処理を続行できます。
- IntegrationCallout ポリシーが完了しました。
統合の開始後、統合には実行の完了に最大 50 分の制限が適用されます。
同期モード: 統合を実行するリクエストがエンドポイントに到達すると、エンドポイントはすぐに統合の実行を開始し、レスポンスを待ちます。実行を完了するための最大時間制限は 2 分です。実行が終了すると、エンドポイントから実行 ID と他のレスポンスデータを含むレスポンスが返されます。

デフォルト値	false
必須かどうか	省略可
型	ブール値
親要素	`<IntegrationCallout>`
子要素	なし

<AsyncExecution> 要素の構文は次のとおりです。

構文

<AsyncExecution>BOOLEAN</AsyncExecution>

例

次の例では、非同期実行を true に設定しています。

<AsyncExecution>true</AsyncExecution>

`<Request>`

SetIntegrationRequest ポリシーによって作成されたリクエストオブジェクトを持つフロー変数を指定します。IntegrationCallout ポリシーは、統合を実行するために、このリクエストオブジェクトを Apigee Integration に送信します。

デフォルト値	なし
必須かどうか	必須
型	文字列
親要素	`<IntegrationCallout>`
子要素	なし

<Request> 要素の構文は次のとおりです。

構文

<Request clearPayload="true">FLOW_VARIABLE_NAME</Request>

例

次の例では、リクエストオブジェクトを my_request_flow_var フロー変数で使用できるように指定しています。

<Request clearPayload="true">my_request_flow_var</Request>

次の表に、<Request> 要素の属性を示します。

属性必須かどうか種類説明

属性	必須かどうか	種類	説明
`clearPayload`	省略可	ブール値	統合を実行するリクエストを送信した後、メモリからリクエストオブジェクトを消去するかどうかを指定します。 `true` に設定すると、Apigee はリクエストオブジェクトを消去します。 `false` に設定すると、Apigee はリクエストオブジェクトを消去しません。この属性を指定しない場合、デフォルト値は `true` で、リクエストオブジェクトがメモリから消去されます。

clearPayload

省略可

ブール値

統合を実行するリクエストを送信した後、メモリからリクエストオブジェクトを消去するかどうかを指定します。

true に設定すると、Apigee はリクエストオブジェクトを消去します。
false に設定すると、Apigee はリクエストオブジェクトを消去しません。

この属性を指定しない場合、デフォルト値は true で、リクエストオブジェクトがメモリから消去されます。

`<Response>`

統合のレスポンスを保存するフロー変数を指定します。

この要素を指定しない場合、このポリシーは integration.response フロー変数にレスポンスを保存します。

デフォルト値	integration.response
必須かどうか	省略可
型	文字列
親要素	`<IntegrationCallout>`
子要素	なし

<Response> 要素の構文は次のとおりです。

構文

<Response>FLOW_VARIABLE_NAME</Response>

例

次の例では、統合実行のレスポンスを my_response_flow_var フロー変数に保存します。

<Response>my_response_flow_var</Response>

エラーコード

このセクションでは、このポリシーでエラーがトリガーされたときに Apigee が設定する障害コード、エラーメッセージ、障害変数について説明します。これは、障害に対処する障害ルールを作成する場合に重要な情報です。詳細については、ポリシーエラーについて知っておくべきことと障害の処理をご覧ください。

ランタイムエラー

このエラーは、ポリシーの実行時に発生することがあります。

障害コード	HTTP ステータス	原因
`entities.UnresolvedVariable`	`500`	このエラーは、Apigee が `integration.project.id` 変数または `integration.name` 変数を解決できない場合に発生します。
`steps.integrationcallout.ExecutionFailed`	`500`	このエラーは、バックエンドターゲットサービスが `4xx` や `5xx` などの HTTP エラーステータスを返した場合に発生します。考えられる原因は次のとおりです。プロキシでデプロイされたサービスアカウントに、統合を実行するための正しい権限が付与されていない。統合または API トリガーが存在しない。 Google Cloud プロジェクトで Application Integration が有効になっていない。 SetIntegrationRequest ポリシーで `<ScheduleTime>` 要素を構成し、IntegrationCallout ポリシーで `AsyncExecution` を `false` に設定している。
`steps.integrationcallout.NullRequestVariable`	`500`	このエラーは、`<Request>` で指定されたフロー変数が null の場合に発生します。
`steps.integrationcallout.RequestVariableNotMessageType`	`500`	このエラーは、`Request` 要素で指定されたフロー変数がメッセージ型でない場合に発生します。
`steps.integrationcallout.RequestVariableNotRequestMessageType`	`500`	このエラーは、`Request` 要素で指定されたフロー変数がリクエストメッセージ型でない場合に発生します。
`messaging.adaptors.http.filter.GoogleTokenGenerationFailure`	`500`	このエラーは、サービスアカウントの構成に誤りがある場合に発生することがあります。考えられる原因は次のとおりです。プロキシを使用してデプロイされたサービスアカウントがプロジェクトに存在しない。プロキシを使用してデプロイされたサービスアカウントが無効になっている。

障害変数

ポリシーで実行エラーが発生すると、Apigee によってエラーメッセージが生成されます。これらのエラーメッセージはエラーレスポンスで確認できます。多くの場合、システムによって生成されたエラーメッセージは、製品のコンテキストとは関係ありません。エラーのタイプに基づいてエラーメッセージをカスタマイズして、より有用なメッセージにすることができます。

エラーメッセージをカスタマイズするには、障害ルールまたは RaiseFault ポリシーを使用します。障害ルールと RaiseFault ポリシーの違いについては、FaultRule ポリシーと RaiseFault ポリシーをご覧ください。障害ルールと RaiseFault ポリシーの両方で Condition 要素を使用して条件を確認する必要があります。Apigee では、各ポリシーに固有の障害変数が用意されています。障害変数の値は、ポリシーがランタイムエラーをトリガーするときに設定されます。これらの変数を使用することで、特定のエラー条件を確認し、適切なアクションを実行できます。エラー条件の確認について詳しくは、条件の作成をご覧ください。

次の表に、このポリシーに固有の障害変数を示します。

変数	説明	例
`fault.name`	`fault.name` は、ランタイムエラーの表にある障害のいずれかに一致します。障害名は、障害コードの最後の部分です。	`fault.name Matches "UnresolvedVariable"`
`IntegrationCallout.POLICY_NAME.failed`	`POLICY_NAME` は、障害が発生したポリシーのユーザー指定の名前です。	`IntegrationCallout.integration-callout-1.failed = true`

ポリシーエラーの詳細については、ポリシーエラーについて知っておくべきことをご覧ください。

IntegrationCallout ポリシー

概要

<IntegrationCallout>

構文

例

子要素のリファレンス

<DisplayName>

構文

例

<AsyncExecution>

構文

例

<Request>

構文

例

<Response>

構文

例