ServiceCallout ポリシー

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

Apigee Edge のドキュメントはこちらをご覧ください。

内容

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

このポリシーは拡張可能なポリシーです。Apigee ライセンスによっては、このポリシーの使用によって費用や使用量に影響する場合があります。ポリシータイプと使用量への影響については、ポリシータイプをご覧ください。

外部のユースケースでは、プロキシの外部にあたるサードパーティ API へのコールアウトを行います。サードパーティ API からのレスポンスは解析され、API のレスポンスメッセージに挿入され、アプリのエンドユーザーのデータを拡張し、「マッシュアップ」します。また、リクエストフローの ServiceCallout ポリシーを使用してリクエストを行い、レスポンス内の情報を 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 のドメイン部分と残りの部分では、別々の変数を使用する必要があります。

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>https://maps.googleapis.com/maps/api/geocode/json</URL>
    </HTTPTargetConnection>
</ServiceCallout>

AssignMessage ポリシーなどのポリシーを使用してリクエストオブジェクトを作成するのではなく、ServiceCallout ポリシー内で直接定義できます。この例では、外部サービスに渡される 3 つのクエリパラメータの値が ServiceCallout ポリシーによって設定されます。ServiceCallout ポリシーでリクエストメッセージ全体を作成し、ペイロード、application/xml などのエンコードタイプ、ヘッダー、フォームパラメータなどを指定できます。

次の例では、ServiceCallout ポリシーに到達する前にリクエストが作成されています。

<ServiceCallout name="ServiceCallout-GeocodingRequest2">
    <Request clearPayload="false" variable="GeocodingRequest"/>
    <Response>GeocodingResponse</Response>
    <Timeout>30000</Timeout>
    <HTTPTargetConnection>
      <URL>https://maps.googleapis.com/maps/api/geocode/json</URL>
    </HTTPTargetConnection>
</ServiceCallout>

リクエストメッセージの内容は、GeocodingRequest という変数から抽出されます（AssignMessage ポリシーなどによって入力されます）。レスポンスメッセージは GeocodingResponse という変数に割り当てられます。この変数は、ExtractVariables ポリシーあるいは JavaScript または Java で記述されたカスタムコードによって解析できます。このポリシーは、Google Geocoding API からのレスポンスを 30 秒間待ち、この時間が経過するとタイムアウトになります。

ターゲットサーバーの呼び出し

<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 つのターゲットサーバー間で負荷が分散されています。プロキシのターゲットサーバーの設定と負荷分散の構成については、バックエンドサーバー間の負荷分散をご覧ください。

ServiceCallout ポリシーについて

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

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

リクエスト: AssignMessage では、リモートサービスに送信されたリクエストメッセージを入力します。
レスポンス: ExtractVariables では、レスポンスを解析し、特定のコンテンツを抽出します。

注: ServiceCallout のリクエストとレスポンスのメッセージヘッダーは、フロー変数セクションに記載されているように、すでに変数として使用可能です。ExtractVariables ポリシーを使用してこれらを抽出する必要はありません。

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

AssignMessage ポリシー: リクエストメッセージを作成して、HTTP ヘッダー、クエリパラメータを入力し、HTTP 動詞などを設定します。
ServiceCallout ポリシー: AssignMessage ポリシーによって作成されたメッセージを参照して、外部呼び出しのターゲット URL を定義し、ターゲットサービスから返されるレスポンスオブジェクトの名前を定義します。

パフォーマンス向上のため、ServiceCallout レスポンスをキャッシュに保存することもできます。詳細については、ServiceCallout ポリシーの結果をキャッシュに保存するには？後でキャッシュから取得するには？をご覧ください。
ExtractVariables ポリシー: 通常、ServiceCallout ポリシーによって生成されたメッセージを解析する JSONPath または XPath 式を定義します。その後、このポリシーは ServiceCallout レスポンスからの解析済みの値を格納する変数を設定します。

カスタムエラー処理

サンプル: 実際に試して学ぶ
この Learn Apigee の例では、ServiceCallout レスポンスの HTTP コードを確認し、コードの値に基づいてカスタム例外をスローします。このサンプルは、ターゲットサービスが 404 ステータスを返すときにカスタムエラーメッセージを返します。リポジトリのクローンを作成し、そのトピックの手順に沿うだけです。このサンプルは、ServiceCallout のエラーを処理する一般的なパターンを示しています。

要素リファレンス

このポリシーで構成できる要素と属性は次のとおりです。

<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>
            <StatusCode/>
            <Path/>
            <Version/>
            <Verb/>
         </Remove>
         <Copy>
            <StatusCode/>
            <Path/>
            <Version/>
            <Verb/>
        </Copy>
        <Add>
            <Headers/>
            <QueryParams/>
            <FormParams/>
        </Add>
        <Set>
            <Headers/>
            <QueryParams/>
            <FormParams/>
            <Payload/>
            <StatusCode/>
            <Path/>
            <Version/>
            <Verb/>
        </Set>
    </Request>
    <Response>calloutResponse</Response>
    <Timeout>30000</Timeout>
    <HTTPTargetConnection>
        <URL>http://example.com</URL>
        <LoadBalancer/>
        <SSLInfo/>
        <Properties/>
        <Authentication>
          <HeaderName ref="{variable}">STRING</HeaderName>
          <GoogleAccessToken>
            <Scopes>
              <Scope>https://www.googleapis.com/auth/cloud-platform</Scope>
            </Scopes>
            <LifetimeInSeconds ref="{variable}">3600</LifetimeInSeconds>
          </GoogleAccessToken>
        </Authentication>
        <Authentication>
          <HeaderName ref="{variable}">STRING</HeaderName>
          <GoogleIDToken>
            <Audience ref="{variable}" useTargetUrl="BOOLEAN">{hostname}</Audience>
            <IncludeEmail ref="{variable}">true</IncludeEmail>
          </GoogleIDToken>
        </Authentication>
    </HTTPTargetConnection>
    <LocalTargetConnection>
        <APIProxy/>
        <ProxyEndpoint/>
        <Path/>
    </LocalTargetConnection>
</ServiceCallout>

<ServiceCallout> 属性

<ServiceCallout async="false" continueOnError="false" enabled="true" name="Service-Callout-1">

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

属性	説明	デフォルト	要否
`name`	ポリシーの内部名。`name` 属性の値には、英字、数字、スペース、ハイフン、アンダースコア、ピリオドを使用できます。この値は 255 文字を超えることはできません。管理 UI プロキシエディタで `<DisplayName>` 要素を追加して、ポリシーのラベルに使用する別の自然言語名を指定することもできます。	なし	必須
`continueOnError`	ポリシーが失敗したときにエラーを返す場合は、`false` に設定します。これは、ほとんどのポリシーで想定される動作です。ポリシーが失敗した後もフローの実行を続行する場合は、`true` に設定します。関連項目: 障害ルールはエラー状態の場合にのみトリガーされる（continueOnError について）現在のフローにおける障害処理	false	省略可
`enabled`	ポリシーを適用するには、`true` に設定します。ポリシーを無効にするには、`false` に設定します。ポリシーがフローに接続されている場合でも適用されません。	true	省略可
`async`	この属性は非推奨となりました。	false	非推奨

<DisplayName> 要素

管理 UI プロキシエディタで name 属性と一緒に使用して、ポリシーのラベルに使用する自然言語名を指定します。

<DisplayName>Policy Display Name</DisplayName>

デフォルト

デフォルト	なしこの要素を省略した場合、ポリシーの `name` 属性の値が使用されます。
要否	省略可
タイプ	文字列

なし

この要素を省略した場合、ポリシーの name 属性の値が使用されます。

要否省略可

タイプ文字列

<Request> 要素

API プロキシから他のサービスに送信されるリクエストメッセージを格納する変数を指定します。この変数は、フロー内の先行ポリシーによって作成することも、ServiceCallout ポリシー内でインラインで作成することもできます。

<Request clearPayload="true" variable="myRequest">
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <Remove>
        <StatusCode/>
        <Path/>
        <Version/>
        <Verb/>
    </Remove>
    <Copy>
        <StatusCode/>
        <Path/>
        <Version/>
        <Verb/>
    </Copy>
    <Add>
        <Headers/>
        <QueryParams/>
        <FormParams/>
    </Add>
    <Set>
        <Headers/>
        <QueryParams/>
        <FormParams/>
        <Payload/>
        <StatusCode/>
        <Path/>
        <Version/>
        <Verb/>
    </Set>
</Request>

<Remove>、<Copy>、<Add>、<Set> の各タグの構文は、AssignMessage ポリシーの場合と同じです。

<Set> と <Add> のサブ要素では、メッセージテンプレートという変数文字列置換機能がサポートされています。

リクエストメッセージを解決できない場合、またはリクエストメッセージタイプが無効である場合、このポリシーではエラーが返されます。

最も単純な例では、API プロキシのフロー内の先行部分で入力されていたリクエストメッセージを含む変数を渡します。

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

または、外部サービスに送信されるリクエストメッセージを ServiceCallout ポリシー自体に入力することもできます。

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

デフォルト

リクエスト要素またはその属性のいずれかを省略すると、Apigee は次のデフォルト値を割り当てます。

これらのデフォルト値の意味を確認してみましょう。まず、clearPayload=true は、ServiceCallout ポリシーが実行されるたびに新しいリクエストオブジェクトが作成されることを意味します。このため、リクエストとリクエストの URI パスが再利用されることはありません。次に、デフォルトの変数名 servicecallout.request は、名前を指定しない場合にリクエストに割り当てられる予約済みの名前です。

データマスキングを使用している場合は、このデフォルト名を認識しておくことが重要です。変数名を省略した場合に servicecallout.request をマスク構成に追加する必要があるためです。たとえば、Authorization ヘッダーをマスクしてデバッグセッションで表示されないようにする必要がある場合に、マスク構成に以下を追加してデフォルト名をキャプチャします。

servicecallout.request.header.Authorization。

要否省略可。

型なし

属性

属性説明デフォルト要否

属性	説明	デフォルト	要否
変数	リクエストメッセージを格納する変数の名前。	`servicecallout.request`	省略可
clearPayload	`true` の場合、リクエストメッセージによって使用されるメモリを解放するために、リクエストが HTTP ターゲットに送信された後に、リクエストメッセージを格納する変数がクリアされます。 ServiceCallout の実行後にリクエストメッセージが必要な場合にのみ、clearPayload オプションを false に設定します。	true	省略可

変数

リクエストメッセージを格納する変数の名前。

servicecallout.request

省略可

clearPayload

true の場合、リクエストメッセージによって使用されるメモリを解放するために、リクエストが HTTP ターゲットに送信された後に、リクエストメッセージを格納する変数がクリアされます。

ServiceCallout の実行後にリクエストメッセージが必要な場合にのみ、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> 要素

ServiceCallout ポリシーがターゲットからのレスポンスを待つ時間（ミリ秒単位）。実行時は、この値を動的に設定することはできません。ServiceCallout がタイムアウトに達すると、HTTP 500 が返され、ポリシーが失敗し、API プロキシがエラー状態になります。詳細は、障害の処理をご覧ください。

<Timeout>30000</Timeout>

デフォルト	55,000 ミリ秒（55 秒）（Apigee のデフォルトの HTTP タイムアウト設定）。
要否	省略可
種類	整数

<HTTPTargetConnection> 要素

URL、TLS / SSL、HTTP プロパティなど、トランスポートの詳細を提供します。<TargetEndpoint> 構成リファレンスをご覧ください。

注: <HttpTargetConnection> 要素では、フロー変数を使用して URL を構成できます。

<HTTPTargetConnection>
    <URL>http://example.com</URL>
    <LoadBalancer/>
    <SSLInfo/>
    <Properties/>
</HTTPTargetConnection>

デフォルト	該当なし
要否	必須
型	なし

<HTTPTargetConnection>/<Authentication> 要素

Google OAuth 2.0 トークンまたは Google 発行の OpenID Connect トークンを生成し、特定の Google Cloud プロダクト（Cloud Functions、Cloud Run など）で実行されている Google サービスとカスタムサービスへの認証された呼び出しを行います。この要素を使用するには、Google 認証システムの使用で説明されている設定とデプロイの手順が必要です。適切に設定すると、ポリシーは認証トークンを作成し、それをサービスリクエストに追加します。

子要素、GoogleAccessToken と GoogleIDToken を使用すると、Google OAuth トークンまたは OpenID Connect トークンを生成するようにポリシーを構成できます。呼び出すサービスの種類に応じて、これらの子要素のいずれかを選択する必要があります。

ServiceCallout ポリシーでは、HTTP ベースのサービスの呼び出しのみがサポートされます。

デフォルト	なし
必須かどうか	省略可。
型	複合型
親要素	`<HTTPTargetConnection>`
子要素	`<HeaderName>` `<GoogleAccessToken>` `<GoogleIDToken>`

Authentication 要素の構文は次のとおりです。

構文

<ServiceCallout>
...
  <HTTPTargetConnection>
    <Authentication>
      <HeaderName ref="FLOW_VARIABLE">STRING</HeaderName>
      <GoogleAccessToken>
        <Scopes>
          <Scope>SCOPE</Scope>
          ...
        </Scopes>
        <!-- NOTE: The default value for LifetimeInSeconds is 3600. Change the default only
        if you want to limit the risk of leaked access tokens or improve performance. -->
        <LifetimeInSeconds ref="{variable}">INTEGER</LifetimeInSeconds>
      </GoogleAccessToken>

    --OR--
      <HeaderName ref="FLOW_VARIABLE">STRING</HeaderName>
      <GoogleIDToken>
        <Audience ref="{variable}" useTargetUrl="BOOLEAN">STRING</Audience>
        <IncludeEmail ref="{variable}">BOOLEAN</IncludeEmail>
      </GoogleIDToken>
    </Authentication>
  </HTTPTargetConnection>
</ServiceCallout>

GoogleAccessToken の使用

次の例は、GoogleAccessToken 要素を示しています。

<Authentication>
  <GoogleAccessToken>
    <Scopes>
      <Scope>https://www.googleapis.com/auth/cloud-platform</Scope>
    </Scopes>
  </GoogleAccessToken>
</Authentication>

GoogleIDToken の使用

次の例は、GoogleIDToken 要素を示しています。

<Authentication>
  <GoogleIDToken>
      <Audience>https://httpserver0-bar.run.app</Audience>
      <IncludeEmail>false</IncludeEmail>
  </GoogleIDToken>
</Authentication>

HeaderName の使用

次の例は、HeaderName 要素を示しています。

  <Authentication>
    <HeaderName>X-Serverless-Authorization</HeaderName>
    <GoogleAccessToken>
      <Scopes>
        <Scope>"https://www.googleapis.com/auth/cloud-platform"</Scope>
      </Scopes>
    </GoogleAccessToken>
  </Authentication>

LifetimeInSeconds の使用

次の例は、HeaderName 要素を示しています。

  <Authentication>
    <GoogleAccessToken>
      <Scopes>
        <Scope>"https://www.googleapis.com/auth/cloud-platform"</Scope>
      </Scopes>
      <LifetimeInSeconds ref="variable">3600</LifetimeInSeconds>
    </GoogleAccessToken>
  </Authentication>

属性

なし。

HeaderName 子要素

デフォルトでは、認証構成が存在する場合、Apigee は署名なしトークンを生成し、ターゲットシステムに送信されるメッセージの Authorization ヘッダーにそれを挿入します。HeaderName 要素を使用すると、別のヘッダーの名前を指定して、その署名なしトークンを保持できます。この機能は、ターゲットが X-Serverless-Authorization ヘッダーを使用する Cloud Run サービスである場合に特に役立ちます。Authorization ヘッダーが存在する場合は、変更されずにリクエストで送信されます。

デフォルト	なし
必須かどうか	いいえ
タイプ	文字列
親要素	`<Authentication>`
子要素	なし

HeaderName 要素の構文は次のとおりです。

構文

<ServiceCallout>
...
  <Authentication>
    <HeaderName ref="FLOW_VARIABLE">STRING</HeaderName>
    <GoogleAccessToken>
      ...
    </GoogleAccessToken>
  </Authentication>
  ...
</ServiceCallout>

静的文字列を使用する場合

この例では、生成された署名なしトークンがデフォルトでは X-Serverless-Authorization という名前のヘッダーに追加され、ターゲットシステムに送信されます。Authorization ヘッダーが存在する場合は、変更されずにリクエストで送信されます。

<Authentication>
  <HeaderName>X-Serverless-Authorization</HeaderName>
  <GoogleAccessToken>
    <Scopes>
      <Scope>https://www.googleapis.com/auth/cloud-platform</Scope>
    </Scopes>
  </GoogleAccessToken>
</Authentication>

変数参照を使用する場合

この例では、生成された署名なしトークンがデフォルトでは X-Serverless-Authorization という名前のヘッダーに追加され、ターゲットシステムに送信されます。my-variable に値がある場合は、デフォルトの文字列の代わりにその値が使用されます。Authorization ヘッダーが存在する場合は、変更されずにリクエストで送信されます。

<Authentication>
  <HeaderName ref='my-variable'>X-Serverless-Authorization</HeaderName>
  <GoogleAccessToken>
    <Scopes>
      <Scope>https://www.googleapis.com/auth/cloud-platform</Scope>
    </Scopes>
  </GoogleAccessToken>
</Authentication>

GoogleAccessToken 子要素

Google サービスに対して認証済み呼び出しを行うための Google OAuth 2.0 トークンを生成します。Google OAuth トークンは、さまざまな種類の Google サービス（Cloud Logging や Secret Manager など）の呼び出しに使用できます。

デフォルト	なし
必須かどうか	`GoogleAccessToken` 子要素または `GoogleIDToken` 子要素のいずれかを指定する必要があります。
型	文字列
親要素	`<Authentication>`
子要素	`<Scopes>` `<LifetimeInSeconds>`

GoogleAccessToken 要素の構文は次のとおりです。

構文

<ServiceCallout>
...
  <Authentication>
    <GoogleAccessToken>
      <Scopes>
        <Scope>SCOPE_1</Scope>
        ...
      </Scopes>
      <!-- NOTE: The default value for LifetimeInSeconds is 3600. We do not recommend changing
      the default unless you want to limit the risk of leaked access tokens or improve performance. -->
      <LifetimeInSeconds ref="FLOW_VARIABLE">INTEGER</LifetimeInSeconds>
    </GoogleAccessToken>
  </Authentication>
  ...
</ServiceCallout>

例 1

次の例は、GoogleAccessToken 要素を示しています。

<Authentication>
  <GoogleAccessToken>
    <Scopes>
      <Scope>https://www.googleapis.com/auth/cloud-platform</Scope>
    </Scopes>
  </GoogleAccessToken>
</Authentication>

例 2

以下の例は、ServiceCallout ポリシーを使用して Secret Manager に接続し、Secret を取得する方法を示しています。

<ServiceCallout name="ServiceCallout-sm">
  <Response>SecretManagerResponse</Response>
  <Timeout>30000</Timeout>
  <HTTPTargetConnection>
    <Authentication>
      <GoogleAccessToken>
        <Scopes>
          <Scope>https://www.googleapis.com/auth/cloud-platform</Scope>
        </Scopes>
      </GoogleAccessToken>
    </Authentication>
    <URL>
      https://secretmanager.googleapis.com/v1/projects/project-id/secrets/secret-id
    </URL>
  </HTTPTargetConnection>
</ServiceCallout>

例 3

次の例は、ServiceCallout ポリシーから Cloud Run へのコールアウトを実行する方法を示しています。

<ServiceCallout name="ServiceCallout-CloudRun">
  <Response>CloudRunResponse</Response>
  <Timeout>30000</Timeout>
  <HTTPTargetConnection>
    <Authentication>
      <GoogleIDToken>
        <Audience>https://cloudrun-hostname.a.run.app/test</Audience>
      </GoogleIDToken>
    </Authentication>
    <URL>https://cloudrun-hostname.a.run.app/test</URL>
  </HTTPTargetConnection>
</ServiceCallout>

Scopes 子要素

OAuth 2.0 アクセストークンに含めるスコープを識別します。詳細については、Google API の OAuth 2.0 スコープをご覧ください。この要素の下には、<Scope> 子要素を 1 つ以上追加できます。

デフォルト	なし
必須かどうか	必須
型	文字列
親要素	`<GoogleAccessToken>`
子要素	`<Scope>`

Scope 子要素

有効な Google API スコープを指定します。詳細については、Google API の OAuth 2.0 スコープをご覧ください。

デフォルト	なし
必須かどうか	値を少なくとも 1 つ指定してください。
型	文字列
親要素	`<Scopes>`
子要素	なし

LifetimeInSeconds 子要素

アクセストークンの存続期間を秒単位で指定します。

デフォルト	3600
必須かどうか	省略可
種類	整数
親要素	`<GoogleAccessToken>`
子要素	なし

GoogleIDToken 子要素

Google 発行の OpenID Connect トークンを生成し、Google サービスへの認証済みの呼び出しを行います。

デフォルト	なし
必須かどうか	`GoogleAccessToken` 子要素または `GoogleIDToken` 子要素のいずれかが存在する必要があります。
型	文字列
親要素	`<Authentication>`
子要素	`<Audience>` `<IncludeEmail>`

GoogleIDToken 要素の構文は次のとおりです。

構文

<ServiceCallout>
...
  <Authentication>
    <GoogleIDToken>
        <Audience ref="{variable}" useTargetUrl="BOOLEAN">STRING</Audience>
        <IncludeEmail ref="{variable}">BOOLEAN</IncludeEmail>
    </GoogleIDToken>
  </Authentication>
</ServiceCallout>

例 1

次の例は、GoogleIDToken 要素を示しています。

<Authentication>
  <GoogleIDToken>
      <Audience>https://httpserver0-bar.run.app</Audience>
      <IncludeEmail>true</IncludeEmail>
  </GoogleIDToken>
</Authentication>

Audience 子要素

生成された認証トークンの対象（トークンがアクセス権を付与する API やアカウントなど）。

Audienceの値が空であるか、ref変数が有効な値に解決されない場合、useTargetUrlはtrueとなり、ターゲットの URL（クエリパラメータを除く）がオーディエンスとして使用されます。デフォルトでは、useTargetUrl は false となっています。

Apigee ハイブリッドユーザー: Apigee ハイブリッドを使用する場合、useTargetUrl 属性は Apigee ハイブリッドバージョン 1.8 以降のバージョンで使用できることに留意してください。

<Audience>explicit-audience-value-here</Audience>

or:

<Audience ref='variable-name-here'/>

or:

<Audience ref='variable-name-here' useTargetUrl='true'/>

or:

<Audience useTargetUrl='true'/>

デフォルト	なし
必須かどうか	必須
型	文字列
親要素	`<GoogleIDToken>`
子要素	なし

includeEmail 子要素

true に設定すると、生成された認証トークンには、サービスアカウント email と email_verified クレームが含まれます。

デフォルト	false
必須かどうか	省略可
型	ブール値
親要素	`<GoogleIDToken>`
子要素	なし

<HTTPTargetConnection>/<URL> 要素

呼び出されるサービスの 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 構成のヘルプについては、TLS の構成オプションと、API プロキシ構成リファレンスの「TLS / SSL TargetEndpoint 構成」をご覧ください。

注: ref://mykeystoreref 形式で参照として SSLInfo 要素に KeyStore 名を指定します。直接の名前やフロー変数ではなく、参照を使用することをおすすめします。<KeyStore> 要素と <TrustStore> 要素の設定についてをご覧ください。

<HTTPTargetConnection>
    <URL>https://example.com</URL>
    <SSLInfo>
        <Enabled>true</Enabled>
        <ClientAuthEnabled>true</ClientAuthEnabled>
        <KeyStore>ref://mykeystoreref</KeyStore>  ## Use of a reference is recommended
        <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 つ以上のターゲットサーバーを呼び出し、負荷分散を実行します。サンプルセクションのターゲットサーバーを呼び出すのサンプルをご覧ください。バックエンドサーバー間の負荷分散をご覧ください。ServiceCallout ポリシーとルートルールの両方からターゲットサーバーを呼び出す方法については、ターゲットエンドポイント / サーバーコールアウトもご覧ください。

<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 ヘッダー、メッセージコンテンツ、またはフローコンテキストに基づいた動的な振る舞いを持たせることが可能です。ServiceCallout ポリシーの実行後は、事前定義された次のフロー変数を使用できます。フロー変数の詳細については、変数リファレンスをご覧ください。

ServiceCallouts には独自のリクエストとレスポンスがあり、それらのデータには変数を介してアクセスできます。メインメッセージでは request.* 変数と response.* 変数の接頭辞を使用するため、myrequest.* 接頭辞と calloutResponse.* 接頭辞（ServiceCallout 構成のデフォルト）を使用して、ServiceCallout に固有のメッセージデータを取得します。次の表の最初の例は、ServiceCallout で HTTP ヘッダーを取得する方法を示しています。

変数説明

変数	説明
以下は、メインリクエストとレスポンスからヘッダーを取得する方法と同じように、ServiceCallout のリクエストとレスポンスのヘッダーを取得する例です。 `calloutResponse.header.HeaderName` `myRequest.header.HeaderName` ここで、calloutResponse は、Service Callout のレスポンスの変数名で、myRequest はリクエストの変数名です。次に例を示します。 `calloutResponse.header.Content-Length` この例は、ServiceCallout レスポンスの Content-Length ヘッダーを返します。	スコープ: ServiceCallout 以降タイプ: 文字列権限: 読み取り / 書き込み ServiceCallout のリクエストまたはレスポンスのメッセージヘッダー。たとえば、API プロキシターゲットが http://example.com で、ServiceCallout ターゲットが http://mocktarget.apigee.net の場合、これらの変数は http://mocktarget.apigee.net に対するコールアウトのヘッダーになります。
`servicecallout.requesturi`	スコープ: ServiceCallout リクエスト以降タイプ: 文字列権限: 読み取り / 書き込み ServiceCallout ポリシーの TargetEndpoint URI。この URI は、プロトコルとドメイン仕様が指定されていない TargetEndpoint URL です。
`servicecallout.{policy-name}.target.url`	スコープ: ServiceCallout リクエスト以降タイプ: 文字列権限: 読み取り / 書き込み ServiceCallout のターゲット URL。
`calloutResponse.content` ここで、`calloutResponse` は ServiceCallout 構成の `<Response>` 変数名です。	スコープ: ServiceCallout レスポンス以降タイプ: 文字列権限: 読み取り / 書き込み ServiceCallout からのレスポンス本文。
`servicecallout.{policy-name}.expectedcn`	スコープ: ServiceCallout リクエスト以降タイプ: 文字列権限: 読み取り / 書き込み ServiceCallout ポリシーで参照される TargetEndpoint で想定される共通名。これは、TargetEndpoint が TLS / SSL エンドポイントを参照している場合にのみ意味があります。
`servicecallout.{policy-name}.failed`	スコープ: ServiceCallout レスポンス以降タイプ: ブール値権限: 読み取り / 書き込みポリシーが正常完了した場合は false、失敗した場合は true で示されるブール値。

以下は、メインリクエストとレスポンスからヘッダーを取得する方法と同じように、ServiceCallout のリクエストとレスポンスのヘッダーを取得する例です。

calloutResponse.header.HeaderName

myRequest.header.HeaderName

ここで、calloutResponse は、Service Callout のレスポンスの変数名で、myRequest はリクエストの変数名です。次に例を示します。

calloutResponse.header.Content-Length

この例は、ServiceCallout レスポンスの Content-Length ヘッダーを返します。

スコープ: ServiceCallout 以降
タイプ: 文字列
権限: 読み取り / 書き込み

ServiceCallout のリクエストまたはレスポンスのメッセージヘッダー。たとえば、API プロキシターゲットが http://example.com で、ServiceCallout ターゲットが http://mocktarget.apigee.net の場合、これらの変数は http://mocktarget.apigee.net に対するコールアウトのヘッダーになります。

servicecallout.requesturi

スコープ: ServiceCallout リクエスト以降
タイプ: 文字列
権限: 読み取り / 書き込み

ServiceCallout ポリシーの TargetEndpoint URI。この URI は、プロトコルとドメイン仕様が指定されていない TargetEndpoint URL です。

servicecallout.{policy-name}.target.url

スコープ: ServiceCallout リクエスト以降
タイプ: 文字列
権限: 読み取り / 書き込み

ServiceCallout のターゲット URL。

calloutResponse.content

ここで、calloutResponse は ServiceCallout 構成の <Response> 変数名です。

スコープ: ServiceCallout レスポンス以降
タイプ: 文字列
権限: 読み取り / 書き込み

ServiceCallout からのレスポンス本文。

servicecallout.{policy-name}.expectedcn

スコープ: ServiceCallout リクエスト以降
タイプ: 文字列
権限: 読み取り / 書き込み

ServiceCallout ポリシーで参照される TargetEndpoint で想定される共通名。これは、TargetEndpoint が TLS / SSL エンドポイントを参照している場合にのみ意味があります。

servicecallout.{policy-name}.failed

スコープ: ServiceCallout レスポンス以降
タイプ: ブール値
権限: 読み取り / 書き込み

ポリシーが正常完了した場合は false、失敗した場合は true で示されるブール値。

エラー

このセクションでは、このポリシーによってエラーがトリガーされたときに返される障害コードとエラーメッセージ、Apigee によって設定される障害変数について説明します。これは、障害に対処する障害ルールを作成するうえで重要な情報です。詳細については、ポリシーエラーについて知っておくべきことと障害の処理をご覧ください。

ランタイムエラー

このエラーは、ポリシーの実行時に発生することがあります。

障害コード	HTTP ステータス	原因
`steps.servicecallout.ExecutionFailed`	`500`	このエラーは、次の場合に発生します。ポリシーが不正な入力または無効な入力を処理するよう要求された場合。バックエンドターゲットサービスがエラーステータスを返した場合（デフォルトでは `4xx` または `5xx`）。
`steps.servicecallout.RequestVariableNotMessageType`	`500`	ポリシーで指定された `Request` 変数のタイプが `Message` ではありません。たとえば、文字列または他のメッセージ以外のタイプの場合、このエラーが発生します。
`steps.servicecallout.RequestVariableNotRequestMessageType`	`500`	ポリシーで指定された `Request` 変数のタイプが `RequestMessage` ではありません。たとえば、Response タイプの場合、このエラーが発生します。
`googletoken.EmptyIDTokenAudience`	`500`	`<GoogleIDToken>` が有効になっていますが、`useTargetUrl` が false に設定されており、エラー時に `<Audience>` に直接または参照を介して値が提供されていません。
`messaging.adaptors.http.filter.GoogleTokenGenerationFailure`	`500`	このエラーは、API プロキシが <Authentication> 要素で構成されている場合に発生することがあります。次のような原因が考えられます。プロキシを使用してデプロイされたサービスアカウントが次の状態になっている。プロジェクトに存在しない無効になっている（Apigee ハイブリッドのみ）`apigee-runtime` サービスアカウントに対する roles/iam.serviceAccountTokenCreator ロールが付与されていない。 `apigee-runtime` サービスアカウントのソースプロジェクトで `IAMCredentials` API が無効になっています。 `<GoogleAccessToken>` 要素が使用され、1 つ以上の無効なスコープが指定されています。入力ミスや空のスコープなどを探してください。 Apigee ハイブリッドの場合のみ、ランタイムコンテナのログで `GoogleTokenGenerationFailure` を検索して、問題のデバッグに役立つ詳細なエラーメッセージを見つけます。

デプロイエラー

以下のエラーは、このポリシーを含むプロキシをデプロイするときに発生することがあります。

エラー名	原因	修正
`URLMissing`	`<HTTPTargetConnection>` 内の `<URL>` 要素が見つからないか、空になっています。
`ConnectionInfoMissing`	このエラーは、ポリシーに `<HTTPTargetConnection>` 要素または `<LocalTargetConnection>` 要素がない場合に発生します。
`InvalidTimeoutValue`	このエラーは、`<Timeout>` の値が負の値またはゼロの場合に発生します。
`FAILED_PRECONDITION`	プロキシが <Authentication> タグで構成されている場合にサービスアカウントがないと、このエラーが発生します。例: Deployment of \"organizations/foo/apis/apiproxy/revisions/1\" requires a service account identity, but one was not provided with the request.
`PERMISSION_DENIED`	プロキシが <Authentication> タグを使用して構成されている場合に、サービスアカウントに権限の問題があると、このエラーが発生します。考えられる原因: サービスアカウントが存在しない。サービスアカウントが Apigee 組織と同じ Google Cloud プロジェクトに作成されていない。デプロイ担当者に、サービスアカウントに対する iam.serviceAccounts.actAs 権限が付与されていない。詳細については、サービスアカウントの権限についてをご覧ください。

障害変数

ランタイムエラーが発生すると、次の変数が設定されます。詳細については、ポリシーエラーについて知っておくべきことをご覧ください。

変数	説明	例
`fault.name="fault_name"`	`fault_name` は、上記のランタイムエラーの表に記載されている障害の名前です。障害名は、障害コードの最後の部分です。	`fault.name = "RequestVariableNotMessageType"`
`servicecallout.policy_name.failed`	`policy_name` は、障害が発生したポリシーのユーザー指定の名前です。	`servicecallout.SC-GetUserData.failed = true`

エラーレスポンスの例

注: ベストプラクティスとして、エラー処理でエラーレスポンスの errorcode の部分をトラップすることをおすすめします。faultstring のテキストには依存しないでください。この部分は変更される可能性があります。

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

ServiceCallout ポリシー

内容

サンプル

内部プロキシに対するローカル呼び出し

変数としての URL

Google ジオコーディング / リクエストの定義

ターゲット サーバーの呼び出し

ServiceCallout ポリシーについて

カスタムエラー処理

要素リファレンス

<ServiceCallout> 属性

<DisplayName> 要素

<Request> 要素

属性

<Request>/<IgnoreUnresolvedVariables> 要素

<Response> 要素

<Timeout> 要素

<HTTPTargetConnection> 要素

<HTTPTargetConnection>/<Authentication> 要素

構文

GoogleAccessToken の使用

GoogleIDToken の使用

HeaderName の使用

LifetimeInSeconds の使用

属性

HeaderName 子要素

構文

静的文字列を使用する場合

変数参照を使用する場合

GoogleAccessToken 子要素

構文

例 1

例 2

例 3

Scopes 子要素

Scope 子要素

LifetimeInSeconds 子要素

GoogleIDToken 子要素

構文

例 1

Audience 子要素

includeEmail 子要素

<HTTPTargetConnection>/<URL> 要素

<HTTPTargetConnection>/<SSLInfo> 要素

<HTTPTargetConnection>/<Properties> 要素

<HTTPTargetConnection>/<LoadBalancer> 要素

<LocalTargetConnection> 要素

<LocalTargetConnection>/<APIProxy> 要素

<LocalTargetConnection>/<ProxyEndpoint> 要素

<LocalTargetConnection>/<Path> 要素

スキーマ

フロー変数

エラー

ランタイム エラー

デプロイエラー

障害変数

エラー レスポンスの例

障害ルールの例

関連トピック

ターゲットサーバーの呼び出し

ランタイムエラー

エラーレスポンスの例