IntegrationCallout ポリシー

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

概要

IntegrationCallout ポリシーを使用すると、API トリガーを持つ Application 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>

This element has the following attributes that are common to all policies:

Attribute	Default	Required?	Description
name	N/A	Required	The internal name of the policy. The value of the name attribute can contain letters, numbers, spaces, hyphens, underscores, and periods. This value cannot exceed 255 characters. Optionally, use the <DisplayName> element to label the policy in the management UI proxy editor with a different, natural-language name.
continueOnError	false	Optional	Set to false to return an error when a policy fails. This is expected behavior for most policies. Set to true to have flow execution continue even after a policy fails. See also: Fault rules are triggered ONLY in an error state (about continueOnError) Handling faults within the current flow
enabled	true	Optional	Set to true to enforce the policy. Set to false to turn off the policy. The policy will not be enforced even if it remains attached to a flow.
async	false	Deprecated	This attribute is deprecated.

子要素のリファレンス

このセクションでは、<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 ポリシーは、統合を実行するために、このリクエスト オブジェクトを Application 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 で、リクエスト オブジェクトがメモリから消去されます。

<Response>

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

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

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

統合の出力には、integration.response.content または flow_variable.content でアクセスできます。<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

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

関連トピック

Application Integration 機能の詳細については、Application Integration の概要をご覧ください。