ServiceCallout ポリシー

概要

Service Callout ポリシーを使用すると、API プロキシフローから別のサービスを呼び出すことができます。外部サービス（外部 RESTful サービスのエンドポイントなど）や内部サービス（同じ組織と環境の API プロキシなど）へのコールアウトを行うことができます。

• 外部のユースケースでは、プロキシ外にあるサードパーティ API へのコールアウトを行うことができます。サードパーティ API からのレスポンスは、解析されて API のレスポンス メッセージに挿入されることで、アプリのエンドユーザーのデータを拡充して「マッシュアップ」します。また、リクエスト フローで Service Callout ポリシーを使用してリクエストを行い、レスポンス内の情報を API プロキシの TargetEndpoint に渡すこともできます。
• 別のユースケースでは、呼び出し元と同じ組織と環境に属するプロキシを呼び出します。これはたとえば、1 つ以上の他のプロキシが利用する個別の詳細レベルの機能を提供するプロキシが存在する場合などに、役立つことがあります。たとえば、バックエンド データストアにかかわる作成 / 読み取り / 更新 / 削除オペレーションを公開するプロキシは、データをクライアントに公開する他の複数のプロキシのターゲット プロキシになることがあります。

このポリシーは、HTTP または HTTPS を経由するリクエストに対応します。

サンプル

<LocalTargetConnection>
    <APIProxy>data-manager</APIProxy>
    <ProxyEndpoint>default</ProxyEndpoint>
</LocalTargetConnection>

<HTTPTargetConnection>
    <URL>http://example.com/{request.myResourcePath}</URL>
</HTTPTargetConnection>

<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>

<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>

<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>

Service Callout ポリシーについて

API プロキシ内で Service Callout ポリシーを使用できるシナリオは数多く存在します。たとえば、位置情報データ、顧客レビュー、パートナーの商品カタログのアイテムなどの配信を求めるための外部サービスへの呼び出しを行うように、API プロキシを構成できます。

通常、コールアウトは Assign Message と Extract Variables という他の 2 つのポリシーとともに使用されます。

• リクエスト: Assign Message では、リモート サービスに送信されるリクエスト メッセージを入力します。

• レスポンス: Extract Variables ではレスポンスを解析し、特定のコンテンツを抽出します。

一般的な Service Callout ポリシーの構成は次のとおりです。

1. Assign Message ポリシー: リクエスト メッセージを作成し、HTTP ヘッダーとクエリ パラメータを挿入して、HTTP 動詞などを設定します。
2. Service Calloutポリシー: AssignMessage ポリシーで作成されたメッセージを参照して、外部呼び出しのターゲット URL を定義し、ターゲット サービスから返されるレスポンス オブジェクトの名前を定義します。
   
   パフォーマンスを向上させるために、次の Apigee コミュニティのスレッドで説明されてように Service Callout レスポンスをキャッシュすることもできます（https://community.apigee.com/questions/34110/how-can-i-store-the-results-of-the-servicecallout.html）。
3. 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">

次の表に、すべてのポリシーの親要素に共通する属性を示します。

<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> / <IgnoreUnresolvedVariables> 要素

true に設定すると、リクエスト内の未解決の変数エラーが無視されます。

<Request clearPayload="true" variable="myRequest">
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
</Request>

<Response> 要素

API プロキシ ロジックでリモート呼び出しからのレスポンスをさらに処理する必要がある場合にこの要素を含めます。

この要素が存在する場合、外部サービスから受信するレスポンス メッセージを含む変数の名前を指定します。ポリシーでレスポンスの全体を正常に読み取った場合のみ、ターゲットからのレスポンスが変数に割り当てられます。なんらかの原因でリモート呼び出しが失敗した場合は、エラーが返されます。

この要素を省略すると、API プロキシはレスポンスを待ち受けません。後続のフローステップの実行が API プロキシで続行されます。また、Response 要素がない場合、ターゲットからのレスポンスを後続の手順で処理できず、プロキシフローでリモート呼び出しの失敗を検出することはできません。ServiceCallout を使用するときに Response 要素を省略する一般的な用途は、メッセージを外部システムに記録することです。

 <Response>calloutResponse</Response>

<Timeout> 要素

Service Callout ポリシーがターゲットからのレスポンスを待ち受けるミリ秒単位の時間。この値をランタイム時に動的に設定することはできません。Service Callout がタイムアウトになると、HTTP 500 が返され、ポリシーが失敗し、API プロキシが障害の処理で説明されているエラー状態になります。

<Timeout>30000</Timeout>

<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 ヘッダーを取得する方法を示しています。

エラー

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error. This information is important to know 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.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Example error response

{  
   "fault":{  
      "detail":{  
         "errorcode":"steps.servicecallout.RequestVariableNotMessageType"
      },
      "faultstring":"ServiceCallout[ServiceCalloutGetMockResponse]: 
            request variable data_str value is not of type Message"
   }
}

Example fault rule

<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 クライアントの実装