このページの内容は 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>
エラーコード
このセクションでは、このポリシーでエラーがトリガーされたときに Apigee が設定する障害コード、エラー メッセージ、障害変数について説明します。これは、障害に対処する障害ルールを作成する場合に重要な情報です。詳細については、ポリシーエラーについて知っておくべきことと障害の処理をご覧ください。
ランタイム エラー
このエラーは、ポリシーの実行時に発生することがあります。
障害コード | HTTP ステータス | 原因 |
---|---|---|
entities.UnresolvedVariable |
500 |
このエラーは、Apigee が integration.project.id 変数または integration.name 変数を解決できない場合に発生します。 |
steps.integrationcallout.ExecutionFailed |
500 |
このエラーは、バックエンド ターゲット サービスが
|
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 の概要をご覧ください。