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

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

属性 説明 デフォルト 要否
name

ポリシーの内部名。name 属性の値には、英字、数字、スペース、ハイフン、アンダースコア、ピリオドを使用できます。この値は 255 文字を超えることはできません。

管理 UI プロキシ エディタで <DisplayName> 要素を追加して、ポリシーのラベルに使用する別の自然言語名を指定することもできます。

 なし 必須
continueOnError

ポリシーが失敗したときにエラーを返す場合は、false に設定します。これは、ほとんどのポリシーで想定される動作です。

ポリシーが失敗した後もフローの実行を続行する場合は、true に設定します。関連項目:

 false 省略可
enabled

ポリシーを適用するには、true に設定します。

ポリシーを無効にするには、false に設定します。ポリシーがフローに接続されている場合でも適用されません。

 true 省略可
async

この属性は非推奨となりました。

 false 非推奨

<DisplayName> 要素

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

<DisplayName>Policy Display Name</DisplayName>
デフォルト

なし

この要素を省略した場合、ポリシーの 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 ポリシーの場合と同じです。

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

最も単純な例では、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 で示されるブール値。

エラー

このセクションでは、このポリシーによってエラーがトリガーされたときに返される障害コードとエラー メッセージ、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

    エラー レスポンスの例

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

    障害ルールの例

    <FaultRule name="RequestVariableNotMessageType">
    <Step>
        <Name>AM-RequestVariableNotMessageType</Name>
    </Step>
    <Condition>(fault.name = "RequestVariableNotMessageType")</Condition>
</FaultRule>

    関連トピック