概要
Service Callout ポリシーを使用すると、API プロキシフローから別のサービスを呼び出すことができます。外部サービス(外部 RESTful サービスのエンドポイントなど)や内部サービス(同じ組織と環境の API プロキシなど)へのコールアウトを行うことができます。
- 外部のユースケースでは、プロキシ外にあるサードパーティ API へのコールアウトを行うことができます。サードパーティ API からのレスポンスは、解析されて API のレスポンス メッセージに挿入されることで、アプリのエンドユーザーのデータを拡充して「マッシュアップ」します。また、リクエスト フローで Service Callout ポリシーを使用してリクエストを行い、レスポンス内の情報を API プロキシの TargetEndpoint に渡すこともできます。
- 別のユースケースでは、呼び出し元と同じ組織と環境に属するプロキシを呼び出します。これはたとえば、1 つ以上の他のプロキシが利用する個別の詳細レベルの機能を提供するプロキシが存在する場合などに、役立つことがあります。たとえば、バックエンド データストアにかかわる作成 / 読み取り / 更新 / 削除オペレーションを公開するプロキシは、データをクライアントに公開する他の複数のプロキシのターゲット プロキシになることがあります。
このポリシーは、HTTP または HTTPS を経由するリクエストに対応します。
サンプル
内部プロキシに対するローカル呼び出し
<LocalTargetConnection> <APIProxy>data-manager</APIProxy> <ProxyEndpoint>default</ProxyEndpoint> </LocalTargetConnection>
この例では、data-manager
という名前のローカル API プロキシ(同じ組織と環境に存在する)へのコールアウトを作成し、そのプロキシ エンドポイントの名前を default
に指定します。
変数としての URL
<HTTPTargetConnection> <URL>http://example.com/{request.myResourcePath}</URL> </HTTPTargetConnection>
この例は、URL 内で変数を使用して、ターゲットの URL を動的に代入します。URL のプロトコル部分 http:// を変数で指定することはできません。また、URL のドメイン部分や URL の残り部分にも、それぞれ別個の変数を使用する必要があります。
Google ジオコーディング / リクエストの定義
<ServiceCallout name="ServiceCallout-GeocodingRequest1"> <DisplayName>Inline request message</DisplayName> <Request variable="authenticationRequest"> <Set> <QueryParams> <QueryParam name="address">{request.queryparam.postalcode}</QueryParam> <QueryParam name="region">{request.queryparam.country}</QueryParam> <QueryParam name="sensor">false</QueryParam> </QueryParams> </Set> </Request> <Response>GeocodingResponse</Response> <Timeout>30000</Timeout> <HTTPTargetConnection> <URL>http://maps.googleapis.com/maps/api/geocode/json</URL> </HTTPTargetConnection> </ServiceCallout>
http://maps.googleapis.com/maps/api/geocode/json
リクエスト オブジェクトを作成するのに Assign Message などのポリシーを使用するのではなく、Service Callout ポリシー内で直接定義できます。この例では、外部サービスに渡される 3 つのクエリ パラメータの値が Service Callout ポリシーによって設定されます。Service Callout ポリシーでリクエスト メッセージ全体を作成し、ペイロード、application/xml などのエンコード タイプ、ヘッダー、フォーム パラメータなどを指定できます。
また、次の例では、Service Callout ポリシーに達する前にリクエストが構成されます。
<ServiceCallout name="ServiceCallout-GeocodingRequest2"> <Request clearPayload="false" variable="GeocodingRequest"/> <Response>GeocodingResponse</Response> <Timeout>30000</Timeout> <HTTPTargetConnection> <URL>http://maps.googleapis.com/maps/api/geocode/json</URL> </HTTPTargetConnection> </ServiceCallout>
リクエスト メッセージの内容は、GeocodingRequest という変数から抽出されます(AssignMessage ポリシーなどによって入力されます)。レスポンス メッセージは GeocodingResponse という変数に割り当てられます。この変数は、Extract Variables ポリシーあるいは JavaScript または Java で記述されたカスタムコードによって解析できます。このポリシーは、Google Geocoding API からのレスポンスを 30 秒間待ち、この時間が経過するとタイムアウトになります。
この例の Service Callout を使用する完全なサンプル API プロキシと、Assign Message ポリシーと Extract Variables ポリシーについては、ポリシー作成の使用をご覧ください。
ターゲット サーバーを呼び出す
<ServiceCallout async="false" continueOnError="false" enabled="true" name="service-callout"> <DisplayName>service-callout</DisplayName> <Properties/> <Request clearPayload="true" variable="myRequest"> <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables> </Request> <Response>myResponse</Response> <HTTPTargetConnection> <LoadBalancer> <Algorithm>RoundRobin</Algorithm> <Server name="httpbin"/> <Server name="yahoo"/> </LoadBalancer> <Path>/get</Path> </HTTPTargetConnection> </ServiceCallout>
このポリシーは、LoadBalancer 属性を使用してターゲット サーバーを呼び出し、サーバー間の負荷分散を行います。この例では、"httpbin" と "yahoo" という 2 つのターゲット サーバー間で負荷が分散されます。プロキシのターゲット サーバーの設定と負荷分散の構成については、バックエンド サーバー間の負荷分散をご覧ください。
Service Callout ポリシーについて
API プロキシ内で Service Callout ポリシーを使用できるシナリオは数多く存在します。たとえば、位置情報データ、顧客レビュー、パートナーの商品カタログのアイテムなどの配信を求めるための外部サービスへの呼び出しを行うように、API プロキシを構成できます。
通常、コールアウトは Assign Message と Extract Variables という他の 2 つのポリシーとともに使用されます。
- リクエスト: Assign Message では、リモート サービスに送信されるリクエスト メッセージを入力します。
-
レスポンス: Extract Variables ではレスポンスを解析し、特定のコンテンツを抽出します。
一般的な Service Callout ポリシーの構成は次のとおりです。
- Assign Message ポリシー: リクエスト メッセージを作成し、HTTP ヘッダーとクエリ パラメータを挿入して、HTTP 動詞などを設定します。
- Service Calloutポリシー: AssignMessage ポリシーで作成されたメッセージを参照して、外部呼び出しのターゲット URL を定義し、ターゲット サービスから返されるレスポンス オブジェクトの名前を定義します。
パフォーマンスを向上させるために、次の Apigee コミュニティのスレッドで説明されてように Service Callout レスポンスをキャッシュすることもできます(https://community.apigee.com/questions/34110/how-can-i-store-the-results-of-the-servicecallout.html)。 - Extract Variables ポリシー: 通常、ServiceCallout ポリシーによって生成されたメッセージを解析する JSONPath または XPath 式を定義します。その後、このポリシーは ServiceCallout レスポンスからの解析済みの値を格納する変数を設定します。
Service Callout ポリシーと、Assign Message ポリシー、Extract Variables ポリシーを一緒に使用する完全なサンプル API プロキシについては、ポリシー作成の使用をご覧ください。
カスタムエラー処理
要素リファレンス
このポリシーで構成できる要素と属性は次のとおりです。
<ServiceCallout async="false" continueOnError="false" enabled="true" name="Service-Callout-1"> <DisplayName>Custom label used in UI</DisplayName> <Request clearPayload="true" variable="myRequest"> <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables> <Remove> <ReasonPhrase/> <StatusCode/> <Path/> <Version/> <Verb/> </Remove> <Copy> <ReasonPhrase/> <StatusCode/> <Path/> <Version/> <Verb/> </Copy> <Add> <Headers/> <QueryParams/> <FormParams/> </Add> <Set> <Headers/> <QueryParams/> <FormParams/> <Payload/> <ReasonPhrase/> <StatusCode/> <Path/> <Version/> <Verb/> </Set> </Request> <Response>calloutResponse</Response> <Timeout>30000</Timeout> <HTTPTargetConnection> <URL>http://example.com</URL> <LoadBalancer/> <SSLInfo/> <Properties/> </HTTPTargetConnection> <LocalTargetConnection> <APIProxy/> <ProxyEndpoint/> <Path/> </LocalTargetConnection> </ServiceCallout>
<ServiceCallout> 属性
<ServiceCallout async="false" continueOnError="false" enabled="true" name="Service-Callout-1">
次の表に、すべてのポリシーの親要素に共通する属性を示します。
属性 | 説明 | デフォルト | 要否 |
---|---|---|---|
name |
ポリシーの内部名。 管理 UI プロキシ エディタで |
なし | 必須 |
continueOnError |
ポリシーが失敗した場合にエラーを返すには、 ポリシーが失敗した後もフローの実行を続行する場合は、 |
false | 省略可 |
enabled |
ポリシーを適用するには、 ポリシーを無効にするには、 |
true | 省略可 |
async |
この属性は非推奨となりました。 |
false | 非推奨 |
<DisplayName> 要素
管理 UI プロキシ エディタで name
属性と一緒に使用して、ポリシーのラベルに使用する自然言語名を指定します。
<DisplayName>Policy Display Name</DisplayName>
デフォルト |
なし この要素を省略した場合、ポリシーの |
---|---|
要否 | 省略可 |
タイプ | 文字列 |
<Request> 要素
API プロキシから他のサービスに送信されるリクエスト メッセージを格納する変数を指定します。この変数は、フロー内の先行ポリシーによって作成することも、Service Callout ポリシー内にインラインで作成することもできます。
<Request clearPayload="true" variable="myRequest"> <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables> <Remove> <ReasonPhrase/> <StatusCode/> <Path/> <Version/> <Verb/> </Remove> <Copy> <ReasonPhrase/> <StatusCode/> <Path/> <Version/> <Verb/> </Copy> <Add> <Headers/> <QueryParams/> <FormParams/> </Add> <Set> <Headers/> <QueryParams/> <FormParams/> <Payload/> <ReasonPhrase/> <StatusCode/> <Path/> <Version/> <Verb/> </Set> </Request>
<Remove>、<Copy>、<Add>、<Set> の各タグの構文は、Assign Message ポリシーの場合と同じです。
リクエスト メッセージを解決できない場合、またはリクエスト メッセージ タイプが無効である場合、このポリシーではエラーが返されます。
非常に単純な例では、次のように API プロキシのフロー内の先行部分ですでに代入されているリクエスト メッセージを格納する変数を渡します。
<Request clearPayload="true" variable="myRequest"/>
また、Service Callout ポリシー自体で外部サービスに送信されるリクエスト メッセージを代入することもできます。
<Request> <Set> <Headers> <Header name="Accept">application/json</Header> </Headers> <Verb>POST</Verb> <Payload contentType="application/json">{"message":"my test message"}</Payload> </Set> <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables> </Request>
デフォルト | Request 要素またはその属性のいずれかを省略すると、Edge は次のデフォルト値を割り当てます。
<Request clearPayload="true" variable="servicecallout.request"/> これらのデフォルト値の意味を確認してみましょう。まず、
データマスクを使用している場合はこのデフォルト名を認識しておくことが重要です。変数名を省略した場合に
|
要否 | 省略可。 |
型 | なし |
属性
属性 | 説明 | デフォルト | 要否 |
---|---|---|---|
変数 |
リクエスト メッセージを格納する変数の名前。 |
servicecallout.request |
省略可 |
clearPayload |
Service Callout の実行後にリクエスト メッセージが必要な場合にのみ、clearPayload オプションを false に設定します。 |
true | 省略可 |
<Request> / <IgnoreUnresolvedVariables> 要素
true に設定すると、リクエスト内の未解決の変数エラーが無視されます。
<Request clearPayload="true" variable="myRequest"> <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables> </Request>
デフォルト | false |
要否 | 省略可 |
型 | ブール値 |
<Response> 要素
API プロキシ ロジックでリモート呼び出しからのレスポンスをさらに処理する必要がある場合にこの要素を含めます。
この要素が存在する場合、外部サービスから受信するレスポンス メッセージを含む変数の名前を指定します。ポリシーでレスポンスの全体を正常に読み取った場合のみ、ターゲットからのレスポンスが変数に割り当てられます。なんらかの原因でリモート呼び出しが失敗した場合は、エラーが返されます。
この要素を省略すると、API プロキシはレスポンスを待ち受けません。後続のフローステップの実行が API プロキシで続行されます。また、Response
要素がない場合、ターゲットからのレスポンスを後続の手順で処理できず、プロキシフローでリモート呼び出しの失敗を検出することはできません。ServiceCallout を使用するときに Response
要素を省略する一般的な用途は、メッセージを外部システムに記録することです。
<Response>calloutResponse</Response>
デフォルト | なし |
要否 | 省略可 |
型 | 文字列 |
<Timeout> 要素
Service Callout ポリシーがターゲットからのレスポンスを待ち受けるミリ秒単位の時間。この値をランタイム時に動的に設定することはできません。Service Callout がタイムアウトになると、HTTP 500 が返され、ポリシーが失敗し、API プロキシが障害の処理で説明されているエラー状態になります。
<Timeout>30000</Timeout>
デフォルト | 55,000 ミリ秒(55 秒)。Apigee Edge のデフォルトの HTTP タイムアウトの設定 |
要否 | 省略可 |
型 | 整数 |
<HTTPTargetConnection> 要素
URL、TLS / SSL、HTTP プロパティなど、トランスポートの詳細を提供します。<TargetEndpoint>
構成リファレンスをご覧ください。
<HTTPTargetConnection> <URL>http://example.com</URL> <LoadBalancer/> <SSLInfo/> <Properties/> </HTTPTargetConnection>
デフォルト | なし |
要否 | 必須 |
型 | なし |
<HTTPTargetConnection>/<URL> 要素
呼び出されるサービスへの URL。
<HTTPTargetConnection> <URL>http://example.com</URL> </HTTPTargetConnection>
URL の一部は変数によって動的に指定できます。ただし、URL のプロトコル部分 http:// を変数で指定することはできません。次の例は、変数を使用してクエリ パラメータの値を指定しています。
<URL>http://example.com/forecastrss?w=${request.header.woeid}</URL>
また、URL のパスの部分を変数で設定することもできます。
<URL>http://example.com/{request.resourcePath}?w=${request.header.woeid}</URL>
変数を使用して URL のドメインとポートを指定する場合は、ドメインとポートのみに変数を 1 つ使用し、URL のその他の部分に 2 番目の変数を使用します。
<URL>http://{request.dom_port}/{request.resourcePath}</URL>
デフォルト | なし |
要否 | 必須 |
型 | 文字列 |
<HTTPTargetConnection> / <SSLInfo> 要素
バックエンド サービスに対する TLS / SSL 構成。TLS / SSL 構成のヘルプについては、Edge からの TLS の構成(Cloud、Private Cloud)、API プロキシ構成リファレンスの「TLS/SSL TargetEndpoint 構成」をご覧ください。
<HTTPTargetConnection> <URL>https://example.com</URL> <SSLInfo> <Enabled>true</Enabled> <ClientAuthEnabled>true</ClientAuthEnabled> <KeyStore>myKeystore</KeyStore> <KeyAlias>myKey</KeyAlias> <TrustStore>myTruststore</TrustStore> <Ciphers/> <Protocols/> </SSLInfo> </HTTPTargetConnection>
デフォルト | なし |
要否 | 省略可 |
型 | なし |
<HTTPTargetConnection> / <Properties> 要素
バックエンド サービスに対する HTTP トランスポートのプロパティ。詳細については、エンドポイント プロパティのリファレンスをご覧ください。
<HTTPTargetConnection> <URL>http://example.com</URL> <Properties> <Property name="allow.http10">true</Property> <Property name="request.retain.headers"> User-Agent,Referer,Accept-Language </Property> </Properties> </HTTPTargetConnection>
デフォルト | なし |
要否 | 省略可 |
型 | なし |
<HTTPTargetConnection> / <LoadBalancer> 要素
1 つ以上のターゲット サーバーを呼び出し、負荷分散を実行します。サンプル セクションのターゲット サーバーを呼び出すのサンプルをご覧ください。バックエンド サーバー間の負荷分散をご覧ください。Service Callout ポリシーとルートルールの使用の両方からターゲット サーバーを呼び出す方法については、こちらのコミュニティの投稿もご覧ください。
<HTTPTargetConnection> <LoadBalancer> <Algorithm>RoundRobin</Algorithm> <Server name="httpbin"/> <Server name="yahoo"/> </LoadBalancer> <Path>/get</Path> </HTTPTargetConnection>
デフォルト | なし |
要否 | 省略可 |
型 | なし |
<LocalTargetConnection> 要素
ローカル プロキシ、つまり、同じ組織と環境に属するプロキシをサービス コールアウトのターゲットとして指定します。
ターゲットをさらに詳細に指定するには、<APIProxy>
要素と <ProxyEndpoint>
要素、または <Path>
要素を使用します。
<LocalTargetConnection> <APIProxy/> <ProxyEndpoint/> <Path/> </LocalTargetConnection>
デフォルト | なし |
要否 | 必須 |
型 | なし |
<LocalTargetConnection>/<APIProxy> 要素
ローカル呼び出しの対象とする API プロキシの名前。このプロキシは呼び出し元のプロキシと同じ組織と環境に属している必要があります。
<LocalTargetConnection> <APIProxy>data-manager</APIProxy> <ProxyEndpoint>default</ProxyEndpoint> </LocalTargetConnection>
<APIProxy>
要素とともに、<ProxyEndpoint>
要素を含めて、呼び出しのターゲットとするプロキシ エンドポイントの名前を指定します。
<LocalTargetConnection> <APIProxy/> <ProxyEndpoint/> </LocalTargetConnection>
デフォルト | なし |
要否 | 必須 |
型 | 文字列 |
<LocalTargetConnection>/<ProxyEndpoint> 要素
呼び出しのターゲットにするプロキシ エンドポイントの名前。これは、<APIProxy>
要素で指定された API プロキシのプロキシ エンドポイントです。
<LocalTargetConnection> <APIProxy>data-manager</APIProxy> <ProxyEndpoint>default</ProxyEndpoint> </LocalTargetConnection>
デフォルト | なし |
要否 | 省略可 |
型 | なし |
<LocalTargetConnection>/<Path> 要素
ターゲットとされるエンドポイントへのパス。このエンドポイントは、呼び出し元のプロキシと同じ組織と環境に属しているプロキシを参照する必要があります。
プロキシ名がわからない、または信頼できない場合は、<APIProxy>/<ProxyEndpoint>
ペアの代わりにこれを使用します。パスは信頼性の高いターゲットになります。
<LocalTargetConnection> <Path>/data-manager</Path> </LocalTargetConnection>
デフォルト | なし |
要否 | 省略可 |
型 | なし |
スキーマ
フロー変数
フロー変数を使用すると、ポリシーとフローの実行中に HTTP ヘッダー、メッセージ コンテンツ、またはフロー コンテキストに基づいた動的な振る舞いを持たせることが可能です。Service Callout ポリシーの実行後は、事前定義された次のフロー変数を使用できます。フロー変数の詳細については、変数リファレンスをご覧ください。
Service Callouts には独自のリクエストとレスポンスがあり、それらのデータには変数を介してアクセスできます。メイン メッセージでは request.*
変数と response.*
変数の接頭辞を使用するため、myrequest.*
接頭辞と calloutResponse.*
接頭辞(Service Callout 構成のデフォルト)を使用して、Service Callout に固有のメッセージ データを取得します。次の表の最初の例は、Service Callout で HTTP ヘッダーを取得する方法を示しています。
変数 | 説明 |
---|---|
次に示すのは、メイン リクエストとレスポンスからヘッダーを取得するのと同様の方法で、Service Callout のリクエストとレスポンスのヘッダーを取得する例です。
ここで、calloutResponse は Service Callout のレスポンスの変数名で、myRequest はリクエストの変数名です。例:
この例は、Service Callout レスポンスの Content-Length ヘッダーを返します。 |
スコープ: Service Callout 以降 Service Callout のリクエスト / レスポンス内のメッセージ ヘッダー。たとえば、API プロキシ ターゲットが http://example.com で、Service Callout ターゲットが http://mocktarget.apigee.net である場合、これらの変数は http://mocktarget.apigee.net に対するコールアウトのヘッダーになります。 |
servicecallout.requesturi |
スコープ: Service Callout リクエスト以降 ServiceCallout ポリシーの TargetEndpoint URI。URI は、TargetEndpoint URL からプロトコルとドメイン仕様を除いたものです。 |
servicecallout.{policy-name}.target.url |
スコープ: Service Callout リクエスト以降 Service Callout のターゲット URL。 |
ここで、 |
スコープ: Service Callout レスポンス以降 Service Callout からのレスポンスの本文。 |
servicecallout.{policy-name}.expectedcn |
スコープ: Service Callout リクエスト以降 Service Callout ポリシーで参照される TargetEndpoinnt の予期される一般名。これは、TargetEndpoint が TLS / SSL エンドポイントを参照する場合にのみ意味があります。 |
servicecallout.{policy-name}.failed |
スコープ: Service Callout レスポンス以降 ポリシーが正常完了した場合は false で、失敗した場合は true で示されるブール値。 |
エラー
このセクションでは、このポリシーによってエラーがトリガーされたときに返される障害コードとエラー メッセージ、Edge によって設定される障害変数について説明します。 これは、障害に対処する障害ルールを作成するうえで重要な情報です。詳細については、ポリシーエラーについて知っておくべきことと障害の処理をご覧ください。
ランタイム エラー
このエラーは、ポリシーの実行時に発生することがあります。
障害コード | HTTP ステータス | 原因 | 修正 |
---|---|---|---|
steps.servicecallout.ExecutionFailed |
500 |
このエラーが発生するのは、次の場合です。
|
build |
steps.servicecallout.RequestVariableNotMessageType |
500 | ポリシーで指定された Request 変数が Message 型ではありません。たとえば、文字列または他のメッセージ以外のタイプの場合、このエラーが表示されます。 | build |
steps.servicecallout.RequestVariableNotRequestMessageType |
500 | ポリシーで指定された Request 変数のタイプが Request Message ではありません。たとえば、Response タイプの場合、このエラーが表示されます。 | build |
デプロイエラー
このポリシーを含むプロキシをデプロイするときに、これらのエラーが発生することがあります。
エラー名 | 原因 | 修正 |
---|---|---|
URLMissing |
<HTTPTargetConnection> 内の <URL> 要素がないか、空です。 |
build |
ConnectionInfoMissing |
このエラーは、ポリシーに <HTTPTargetConnection> 要素または <LocalTargetConnection> 要素がない場合に発生します。 |
build |
InvalidTimeoutValue |
このエラーは、<Timeout> の値が負の値またはゼロの場合に発生します。 |
build |
障害変数
ランタイム エラーが発生すると、次の変数が設定されます。詳細については、ポリシーエラーについて知っておくべきことをご覧ください。
変数 | 説明 | 例 |
---|---|---|
fault.name="fault_name" |
fault_name は、上記のランタイム エラーの表に記載されている障害の名前です。障害名は、障害コードの最後の部分です。 | fault.name = "RequestVariableNotMessageType" |
servicecallout.policy_name.failed |
policy_name は、障害が発生したポリシーのユーザー指定の名前です。 | servicecallout.SC-GetUserData.failed = true |
エラー レスポンスの例
{ "fault":{ "detail":{ "errorcode":"steps.servicecallout.RequestVariableNotMessageType" }, "faultstring":"ServiceCallout[ServiceCalloutGetMockResponse]: request variable data_str value is not of type Message" } }
障害ルールの例
<faultrule name="VariableOfNonMsgType"></faultrule><FaultRule name="RequestVariableNotMessageType"> <Step> <Name>AM-RequestVariableNotMessageType</Name> </Step> <Condition>(fault.name = "RequestVariableNotMessageType")</Condition> </FaultRule>
関連トピック
- メッセージを生成または変更する: Assign Message ポリシー
- 変数を抽出する: Extract Variables ポリシー
- 変数: 変数リファレンス
- TLS / SSL 構成
- Edge からバックエンドへの TLS の構成(Cloud、Private Cloud)
- API プロキシ構成リファレンスの「TLS / SSL TargetEndpoint 構成」
- HTTP トランスポートのプロパティ: Endpoint プロパティのリファレンス
- Service Callout の代替: JavaScript で作成された HTTPClient。JavaScript オブジェクト モデルと JavaScript での HTTP クライアントの実装