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 ポリシーの構成は次のとおりです。

  1. AssignMessage ポリシー: リクエスト メッセージを作成して、HTTP ヘッダー、クエリ パラメータを入力し、HTTP 動詞などを設定します。

  2. ServiceCallout ポリシー: AssignMessage ポリシーによって作成されたメッセージを参照して、外部呼び出しのターゲット URL を定義し、ターゲット サービスから返されるレスポンス オブジェクトの名前を定義します。

    パフォーマンス向上のため、ServiceCallout レスポンスをキャッシュに保存することもできます。詳細については、ServiceCallout ポリシーの結果をキャッシュに保存するには？後でキャッシュから取得するには？をご覧ください。

  3. ExtractVariables ポリシー: 通常、ServiceCallout ポリシーによって生成されたメッセージを解析する JSONPath または XPath 式を定義します。その後、このポリシーは 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">

The following table describes attributes that are common to all policy parent elements:

Attribute Description Default Presence
name

The internal name of the policy. The value of the name attribute can contain letters, numbers, spaces, hyphens, underscores, and periods. This value cannot exceed 255 characters.

Optionally, use the <DisplayName> element to label the policy in the management UI proxy editor with a different, natural-language name.

 N/A Required
continueOnError

Set to false to return an error when a policy fails. This is expected behavior for most policies.

Set to true to have flow execution continue even after a policy fails. See also:

 false Optional
enabled

Set to true to enforce the policy.

Set to false to turn off the policy. The policy will not be enforced even if it remains attached to a flow.

 true Optional
async

This attribute is deprecated.

 false Deprecated

<DisplayName> element

Use in addition to the name attribute to label the policy in the management UI proxy editor with a different, natural-language name.

<DisplayName>Policy Display Name</DisplayName>
Default

N/A

If you omit this element, the value of the policy's name attribute is used.
Presence Optional
Type String

<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 ポリシーの場合と同じです。

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

最も単純な例では、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 は次のデフォルト値を割り当てます。

<Request clearPayload="true" variable="servicecallout.request"/>

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

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

servicecallout.request.header.Authorization。
要否 省略可。
型 なし

属性

属性 説明 デフォルト 要否
変数

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

 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>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 となっています。

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

<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 構成」をご覧ください。

<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 で示されるブール値。

エラー

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee 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.

Fault code HTTP status Cause Fix
steps.servicecallout.ExecutionFailed 500

This error can occur when:

  • The policy is asked to handle input that is malformed or otherwise invalid.
  • The backend target service returns an error status (by default, 4xx or 5xx).
steps.servicecallout.RequestVariableNotMessageType 500 The Request variable specified in the policy is not of type Message. For example, if it's a string or other non-message type, you'll see this error.
steps.servicecallout.RequestVariableNotRequestMessageType 500 The Request variable specified in the policy is not of type RequestMessage. For example, if it's a Response type, you'll see this error.
googletoken.EmptyIDTokenAudience 500

<GoogleIDToken> is enabled but useTargetUrl is set to false and no value is provided to <Audience> either directly or through reference at the time of error.
messaging.adaptors.http.filter.GoogleTokenGenerationFailure 500 This error can happen if the API proxy is configured with the <Authentication> element. Possible causes include:
  • The service account deployed with the proxy:
    • does not exist in your project
    • has been disabled
    • (Apigee hybrid only) has not granted the roles/iam.serviceAccountTokenCreator role on the apigee-runtime service account.
  • The IAMCredentials API is disabled in the source project of the apigee-runtime service account.
  • The <GoogleAccessToken> element is used and one or more invalid scopes are provided. For example, look for typos or empty scopes.

    • For Apigee hybrid only, check the runtime container's log and search for GoogleTokenGenerationFailure to find more detailed error messages that may help with debugging the problem.

    Deployment errors

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

    Error name Cause Fix
    URLMissing The <URL> element inside <HTTPTargetConnection> is missing or empty.
    ConnectionInfoMissing This error happens if the policy does not have an <HTTPTargetConnection> or <LocalTargetConnection> element.
    InvalidTimeoutValue This error happens if the <Timeout> value is negative or zero.
    FAILED_PRECONDITION This error happens if the service account is missing when the proxy is configured with the <Authentication> tag.

    For example: 

    Deployment of \"organizations/foo/apis/apiproxy/revisions/1\" requires a service
          account identity, but one was not provided with the request.
    PERMISSION_DENIED This error happens if there is a permission problem with the service account if the proxy is configured with the <Authentication> tag. Possible causes:
    • The service account does not exist.
    • The service account was not created in the same Google Cloud project as the Apigee organization.
    • The deployer does have iam.serviceAccounts.actAs permission on the service account. For details, see About service account permissions.

    Fault variables

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

    Variables Where Example
    fault.name="fault_name" fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code. fault.name = "RequestVariableNotMessageType"
    servicecallout.policy_name.failed policy_name is the user-specified name of the policy that threw the fault. servicecallout.SC-GetUserData.failed = true

    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="RequestVariableNotMessageType">
    <Step>
        <Name>AM-RequestVariableNotMessageType</Name>
    </Step>
    <Condition>(fault.name = "RequestVariableNotMessageType")</Condition>
</FaultRule>

    関連トピック