このページは Apigee と Apigee ハイブリッドに適用されます。
概要
IntegrationCallout ポリシーを使用すると、API トリガーを持つ Application Integration を実行できます。ただし、統合を実行する前に、SetIntegrationRequest ポリシーを実行する必要があります。SetIntegrationRequest ポリシーは、リクエスト オブジェクトを作成して、そのオブジェクトをフロー変数として IntegrationCallout ポリシーで使用できるようにします。リクエスト オブジェクトには、API トリガー名、統合プロジェクト ID、統合名などの統合の詳細があり、SetIntegrationRequest ポリシーで構成されています。IntegrationCallout ポリシーは、リクエスト オブジェクトのフロー変数を使用して統合を実行します。統合実行レスポンスをフロー変数に保存するように、IntegrationCallout ポリシーを構成できます。
IntegrationCallout ポリシーは、プロキシフローの途中で統合を実行する場合に役立ちます。また、IntegrationCallout ポリシーを構成する代わりに、統合エンドポイントをターゲット エンドポイントとして指定して統合を実行することもできます。詳細については、IntegrationEndpoint をご覧ください。
このポリシーは拡張可能なポリシーです。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 |
なし | 必須 |
ポリシーの内部名。 管理 UI プロキシ エディタで |
continueOnError |
false | 省略可 | ポリシーが失敗したときにエラーを返す場合は、false に設定します。これは、ほとんどのポリシーで想定される動作です。ポリシーが失敗した後もフローの実行を続行する場合は、true に設定します。関連情報:
|
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 ポリシーが完了しました。
- 統合は HTTP
- 同期モード: 統合を実行するリクエストがエンドポイントに到達すると、エンドポイントはすぐに統合の実行を開始し、レスポンスを待ちます。実行を完了するための最大時間制限は 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 |
省略可 | ブール値 | 統合を実行するリクエストを送信した後、メモリからリクエスト オブジェクトを消去するかどうかを指定します。
この属性を指定しない場合、デフォルト値は |
<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>
エラーコード
This section describes the fault codes, error messages, and the fault variables set by Apigee when this policy triggers an error. This information is essential if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.
Runtime errors
These errors can occur when the policy executes.
| Fault code | HTTP status | Cause |
|---|---|---|
entities.UnresolvedVariable |
500 |
This error occurs if Apigee cannot resolve the integration.project.id
or the integration.name variables. |
steps.integrationcallout.ExecutionFailed |
500 |
This error can occur if the backend target service returns an HTTP error status such as
|
steps.integrationcallout.NullRequestVariable |
500 |
This error occurs if the flow variable specified in the <Request> is null. |
steps.integrationcallout.RequestVariableNotMessageType |
500 |
This error occurs when the flow variable specified by the Request element
is not of message type. |
steps.integrationcallout.RequestVariableNotRequestMessageType |
500 |
This error occurs when the flow variable specified by the Request element
is not of Request message type. |
messaging.adaptors.http.filter.GoogleTokenGenerationFailure |
500 |
This error can occur because of an incorrect service account configuration. The possible causes include:
|
Fault variables
Whenever there are execution errors in a policy, Apigee generates error messages. You can view these error messages in the error response. Many a time, system generated error messages might not be relevant in the context of your product. You might want to customize the error messages based on the type of error to make the messages more meaningful.
To customize the error messages, you can use either fault rules or the RaiseFault policy. For
information about differences between fault rules and the RaiseFault policy, see
FaultRules vs. the RaiseFault policy.
You must check for conditions using the Condition element in both the fault rules and the RaiseFault policy.
Apigee provides fault variables unique to each policy and the values of the fault variables are set when a policy triggers runtime errors.
By using these variables, you can check for specific error conditions and take appropriate actions. For more information about checking error
conditions, see Building conditions.
The following table describes the fault variables specific to this policy.
| Variables | Where | Example |
|---|---|---|
fault.name |
The fault.name can match to any of the faults listed in the Runtime errors table.
The fault name is the last part of the fault code. |
fault.name Matches "UnresolvedVariable" |
IntegrationCallout.POLICY_NAME.failed |
POLICY_NAME is the user-specified name of the policy that threw the fault. | IntegrationCallout.integration-callout-1.failed = true |
関連トピック
Application Integration 機能の詳細については、Application Integration の概要をご覧ください。