API プロキシ構成リファレンス

このページの内容は Apigee と Apigee ハイブリッドに該当します。

Apigee Edge のドキュメントを表示する。

Apigee を利用するデベロッパーの主要な開発作業には、API またはバックエンドサービスのプロキシとして機能する API プロキシの構成が含まれます。このドキュメントは、API プロキシを構築する際に利用できる、すべての構成要素のリファレンスです。

API プロキシの構築方法を学習する場合は、シンプルな API プロキシの構築のトピックから始めることをおすすめします。

次のいずれかの方法で API プロキシ構成を編集します。

Apigee UI または API を使用します。
API プロキシ構成バンドルのダウンロードとアップロードの説明に沿って、API プロキシ構成のバンドルをダウンロードして手動で編集し、新しい構成を Apigee にアップロードします。

API プロキシ構成のディレクトリ構造

API プロキシ構成のディレクトリ構造を以下に示します。

apiproxy をルートディレクトリとするディレクトリ構造。apiproxy ディレクトリの直下には、policies、proxies、resources、targets の各ディレクトリと weatherapi.xml ファイルが配置されています。

API プロキシ構成は、次の内容で構成されます。

基本構成	API プロキシのプライマリ構成設定。
ProxyEndpoint	インバウンド HTTP 接続（リクエストを行うアプリから Apigee への接続）、リクエストとレスポンスのフロー、ポリシー接続の設定。
TargetEndpoint	アウトバウンド HTTP 接続（Apigee からバックエンドサービスへの接続）、リクエストとレスポンスのフロー、ポリシー接続の設定。
フロー	ポリシーを接続できる、ProxyEndpoint と TargetEndpoint のリクエストとレスポンスのパイプライン。
ポリシー	Apigee ポリシースキーマに準拠する XML 形式の構成ファイル。
リソース	カスタムロジックを実行するためにポリシーによって参照されるスクリプト、JAR ファイル、XSLT ファイル。

基本構成

`/apiproxy/weatherapi.xml`

API プロキシの基本構成。API プロキシの名前を定義します。名前は組織内で一意でなければなりません。

構成の例:

<APIProxy name="weatherapi">
</APIProxy>

基本構成の要素

名前	説明	デフォルト	必須かどうか
`APIProxy`
`name`	API プロキシの名前。組織内で一意にする必要があります。名前に使用できる文字は、`A-Za-z0-9_-` のみです。	なし	○
`revision`	API プロキシ構成のリビジョン番号。Apigee では API プロキシの現在のリビジョンが自動的にトラッキングされるため、リビジョン番号を明示的に設定する必要はありません。	なし	×
`ConfigurationVersion`	この API プロキシが準拠する API プロキシ構成スキーマのバージョン。現在サポートされている値は、majorVersion 4 と minorVersion 0 のみです。この設定は、API プロキシフォーマットの進化を可能にするため将来使用される可能性があります。	4.0	×
`Description`	API プロキシのテキストによる説明。指定すると、Apigee UI に説明が表示されます。	なし	×
`DisplayName`	API プロキシ構成の `name` 属性とは異なる場合がある、わかりやすい名前。	なし	×
`Policies`	この API プロキシの `/policies` ディレクトリにあるポリシーのリスト。通常、Apigee UI を使用して API プロキシを作成した場合にのみこの要素が表示されます。これは単なるマニフェスト設定であり、API プロキシの内容を可視化するように設計されています。	なし	×
`ProxyEndpoints`	この API プロキシの `/proxies` ディレクトリにあるプロキシエンドポイントのリスト。通常、Apigee UI を使用して API プロキシを作成した場合にのみこの要素が表示されます。これは単なるマニフェスト設定であり、API プロキシの内容を可視化するように設計されています。	なし	×
`Resources`	この API プロキシの `/resources` ディレクトリにあるリソース（JavaScript、Python、Java、XSLT）のリスト。通常、Apigee UI を使用して API プロキシを作成した場合にのみこの要素が表示されます。これは単なるマニフェスト設定であり、API プロキシの内容を可視化するように設計されています。	なし	×
`Spec`	API プロキシに関連付けられている OpenAPI 仕様を識別します。値は、URL または仕様ストア内のパスに設定されます。	なし	×
`TargetServers`	この API プロキシのターゲットエンドポイントで参照されるターゲットサーバーのリスト。通常、Apigee を使用して API プロキシを作成した場合にのみ、この要素が表示されます。これは単なるマニフェスト設定であり、API プロキシの内容を可視化するように設計されています。	なし	×
`TargetEndpoints`	この API プロキシの `/targets` ディレクトリにあるターゲットエンドポイントのリスト。通常、Apigee UI を使用して API プロキシを作成した場合にのみこの要素が表示されます。これは単なるマニフェスト設定であり、API プロキシの内容を可視化するように設計されています。	なし	×

ProxyEndpoint

次の図は、リクエスト / レスポンスのフローを示しています。

HTTP サービスを呼び出すクライアントの図。リクエストは HTTP サービスで処理される前に、プロキシエンドポイントを経由してターゲットエンドポイントに渡されます。レスポンスはクライアントに返される前に、ターゲットエンドポイントを経由してプロキシエンドポイントに渡されます。

`/apiproxy/proxies/default.xml`

ProxyEndpoint 構成では、API プロキシのインバウンド（クライアントに対する）インターフェースが定義されます。プロキシエンドポイントを構成する際、クライアントアプリケーション（アプリ）がプロキシされた API をどのように呼び出すかを定義するネットワーク構成を設定します。

次の ProxyEndpoint 構成のサンプルは、/apiproxy/proxies に保存されます。

<ProxyEndpoint name="default">
  <PreFlow/>
  <Flows/>
  <PostFlow/>
  <HTTPProxyConnection>
    <BasePath>/weather</BasePath>
    <Properties/>
  </HTTPProxyConnection>
  <FaultRules/>
  <DefaultFaultRule/>
  <RouteRule name="default">
    <TargetEndpoint>default</TargetEndpoint>
  </RouteRule>
</ProxyEndpoint>

基本的なプロキシエンドポイントに必要な構成要素は次のとおりです。

ProxyEndpoint 構成要素

名前説明デフォルト必須かどうか

ProxyEndpoint

name プロキシエンドポイントの名前。（まれなケースですが）複数のプロキシエンドポイントが定義されている場合、API プロキシ構成内で一意でなければなりません。名前に使用できる文字は、A-Za-z0-9._\-$ % のみです。なし ○

PreFlow リクエストやレスポンスの PreFlow 内のポリシーを定義します。なし ○

Flows

リクエストやレスポンスの条件付きフロー内のポリシーを定義します。

なし

○

PostFlow

リクエストやレスポンスの PostFlow 内のポリシーを定義します。

なし

○

HTTPProxyConnection API プロキシに関連付けられたネットワークアドレスと URI パスを定義します。

BasePath

受信メッセージを適切な API プロキシにルーティングする際に Apigee が使用する URI パスを、一意に識別する必須文字列。

BasePath は、API プロキシのベース URL（http://apifactory-test.apigee.netなど）に追加される URI フラグメント（/weatherなど）です。BasePath は環境内で一意である必要があります。一意性は、API プロキシが生成またはインポートされたときに検証されます。

ベースパスでのワイルドカードの使用

API プロキシのベースパスでワイルドカードとして 1 つ以上の「*」を使用できます。たとえば、ベースパスを /team/*/members にすると、新しいチームに対応するために新しい API プロキシを作成する必要なく、クライアントが https://[host]/team/blue/members と https://[host]/team/green/members を呼び出せるようになります。/**/ はサポートされていないことに注意してください。

重要: Apigee では、ベースパスの最初の要素としてワイルドカード「*」を使用できません。たとえば、/*/search は使用できません。ベースパスを「*」で開始すると、Apigee による有効なパスの識別方法が原因で、予期しないエラーが発生する可能性があります。

○

Properties

オプションの HTTP 構成設定のセットは、<ProxyEndpoint> のプロパティとして定義できます。

request.queryparams.ignore.content.type.charset プロパティを使用して、リクエスト URL の処理時に Content-Type ヘッダーの charset パラメータを無視するようにプロキシに指示します。次に例を示します。

<Property name= \
"request.queryparams.ignore.content.type.charset">true</>

次の表に、charset プロパティの設定と Content-Type ヘッダーの charset パラメータの要否に応じた出力例を示します。

プロパティの設定	ヘッダー値	出力例
`charset=false`	`charset` パラメータが設定されていない	john.doe+test@gmail.com
`charset=false`	`charset=utf-8`	john.doe test@gmail.com
ヘッダーに `charset=true` が存在し、`charset` パラメータが存在しません。	`charset` パラメータが設定されていない	john.doe+test@gmail.com
`charset=true`	`charset=utf-8` パラメータが設定されている	john.doe+test@gmail.com

なし

FaultRules

プロキシエンドポイントがエラーに対してどのように反応するかを定義します。障害ルールには以下の 2 つの事項を指定します。

あらかじめ定義されている障害のカテゴリ、サブカテゴリ、または名前に基づいて処理対象の障害を指定する条件。
対応する条件で使用する障害ルールの動作を定義する 1 つまたは複数のポリシー。

障害の処理をご覧ください。

なし

DefaultFaultRule

別の障害ルールによって明示的に処理されないエラー（システム、トランスポート、メッセージング、ポリシー）を処理します。

障害の処理をご覧ください。

なし

RouteRule ProxyEndpoint リクエストパイプラインによる処理後のインバウンドリクエストメッセージの宛先を定義します。通常、RouteRule は、名前付きターゲットエンドポイント、IntegrationEndpoint、または URL を指します。

Name RouteRule に名前を与える必須属性。名前に使用できる文字は、A-Za-z0-9._\-$ % のみです。たとえば、Cat2 %_ は正式名称です。なし ○

Condition 実行時の動的ルーティングに使用されるオプションの条件付きステートメント。条件付きの RouteRules は、コンテンツベースのルーティングでバックエンドのバージョニングをサポートできるようにする場合などに便利です。なし ×

TargetEndpoint

名前付き TargetEndpoint 構成を識別するオプションの文字列。名前付きターゲットエンドポイントは、/targets ディレクトリにある同じ API プロキシで定義されたターゲットエンドポイントです。

ターゲットエンドポイントに名前を付けることで、ProxyEndpoint リクエストパイプラインによる処理後にリクエストメッセージを転送する場所を指定します。これはオプションの設定であるので注意してください。

プロキシエンドポイントは、URL を直接呼び出すことができます。たとえば、HTTP クライアントのロールで機能する JavaScript または Java リソースは、リクエストをバックエンドサービスに転送するというターゲットエンドポイントの基本的な機能を実行できます。

なし

URL プロキシエンドポイントによって呼び出されるアウトバウンドネットワークアドレスを定義するオプションの文字列。/targets に保存されている TargetEndpoint 構成をバイパスします。なし ×

RouteRules の構成方法

名前付きターゲットエンドポイントは /apiproxy/targets にある構成ファイルを指し、RouteRule はプロキシエンドポイントによる処理後にリクエストをこの宛先に転送します。

たとえば、次の RouteRule は構成 /apiproxy/targets/myTarget.xml を指します。

<RouteRule name="default">
  <TargetEndpoint>myTarget</TargetEndpoint>
</RouteRule>

URL の直接呼び出し

プロキシエンドポイントは、バックエンドサービスを直接呼び出すこともできます。URL の直接呼び出しは、/apiproxy/targets にあるすべての名前付き TargetEndpoint 構成をバイパスします。そのため、TargetEndpoint はオプションの API プロキシ構成になっています。ただし、実際にはプロキシエンドポイントからの直接呼び出しは推奨されません。

たとえば、次の RouteRule は http://api.mycompany.com/v2 に対して HTTP 呼び出しを実行します。

<RouteRule name="default">
  <URL>http://api.mycompany.com/v2</URL> 
</RouteRule>

条件付きルート

実行時に動的ルーティングをサポートするために、RouteRules を連結できます。インバウンドリクエストは、URL に直接ルーティングしたり、あるいは HTTP ヘッダー、メッセージコンテンツ、クエリパラメータ、時刻やロケールなどのコンテキスト情報に基づいて指定された TargetEndpoint 構成にルーティングしたり、その 2 つの組み合わせにルーティングしたりできます。

条件付き RouteRules は、Apigee の他の条件文と同様に機能します。条件リファレンスとフロー変数リファレンスをご覧ください。

たとえば、次の RouteRule の組み合わせでは、まずインバウンドリクエストを評価して HTTP ヘッダーの値が確認されます。HTTP ヘッダー routeTo の値が TargetEndpoint1 の場合、リクエストは TargetEndpoint1 というターゲットエンドポイントに転送されます。そうでない場合、インバウンドリクエストは http://api.mycompany.com/v2 に転送されます。

<RouteRule name="MyRoute">
  <Condition>request.header.routeTo = "TargetEndpoint1"</Condition>
  <TargetEndpoint>TargetEndpoint1</TargetEndpoint>
</RouteRule>
<RouteRule name="default">
  <URL>http://api.mycompany.com/v2</URL>
</RouteRule>

null ルート

null の RouteRule を定義して、リクエストメッセージをターゲットエンドポイントに転送する必要がないシナリオをサポートできます。これは、プロキシエンドポイントが JavaScript を使用して外部サービスを呼び出したり、Apigee の Key-Value ストアを参照してデータを取得したりするなど、プロキシエンドポイントが必要なすべての処理を行う場合に役立ちます。

たとえば、次のように null ルートを定義します。

<RouteRule name="GoNowhere"/>

条件付きの null ルートは便利です。次の例では、HTTP ヘッダー request.header.X-DoNothing に null 以外の値が設定されている場合は null ルートを実行するように構成します。

<RouteRule name="DoNothingOnDemand">
  <Condition>request.header.X-DoNothing != null</Condition>
</RouteRule>

RouteRules は連鎖させることができるので、条件付きの null ルートは通常、条件付きルーティングをサポートするように設計された一連の RouteRules を構成する 1 つのコンポーネントになります。

条件付き null ルートを実際に使用すると、キャッシュをサポートすることになります。キャッシュポリシーによって設定された変数の値を使用することにより、エントリがキャッシュから提供されたときに null ルートを実行するように API プロキシを構成できます。

<RouteRule name="DoNothingUnlessTheCacheIsStale">
  <Condition>lookupcache.LookupCache-1.cachehit is true</Condition>
</RouteRule>

TargetEndpoint

ターゲットエンドポイントは、プロキシエンドポイントのアウトバウンドに相当します。ターゲットエンドポイントは、バックエンドサービスまたは API のクライアントとして機能します。つまり、リクエストを送信してレスポンスを受け取ります。

API プロキシにターゲットエンドポイントは必ずしも必要ではありません。プロキシエンドポイントから URL を直接呼び出すように構成できます。ターゲットエンドポイントを持たない API プロキシには通常、バックエンドサービスを直接呼び出すか、Java または JavaScript を使用してなんらかのサービスを呼び出すように構成されたプロキシエンドポイントが含まれています。

TargetEndpoint 構成

`/targets/default.xml`

ターゲットエンドポイントは、Apigee から別のサービスまたはリソースへのアウトバウンド接続を定義します。

TargetEndpoint の構成例を次に示します。

<TargetEndpoint name="default">
  <PreFlow/>
  <Flows/>
  <PostFlow/>
  <HTTPTargetConnection>
    <URL>http://mocktarget.apigee.net</URL>
    <SSLInfo/>
    <Authentication/>
  </HTTPTargetConnection>
  <FaultRules/>
  <DefaultFaultRule/>
  <ScriptTarget/>
  <LocalTargetConnection/>
</TargetEndpoint>

TargetEndpoint の構成要素

ターゲットエンドポイントは、次のいずれかの方法でターゲットを呼び出すことができます。

HTTP または HTTPS 呼び出し用の HTTPTargetConnection
ローカルプロキシとプロキシ間のチェーン接続用の LocalTargetConnection

これらのいずれかをターゲットエンドポイントで構成します。

名前	説明	デフォルト	必須かどうか
`TargetEndpoint`
`name`	ターゲットエンドポイントの名前。API プロキシ構成内で一意である必要があります。ターゲットエンドポイントの名前は、アウトバウンド処理のためにリクエストを転送する宛先として ProxyEndpoint RouteRule で使用されます。名前に使用できる文字は、`A-Za-z0-9._\-$ %` のみです。	なし	○
`PreFlow`	リクエストやレスポンスの PreFlow 内のポリシーを定義します。	なし	○
`Flows`	リクエストやレスポンスの条件付きフロー内のポリシーを定義します。	なし	○
`PostFlow`	リクエストやレスポンスの PostFlow 内のポリシーを定義します。	なし	○
`HTTPTargetConnection`	その子要素を使用して、HTTP 経由でバックエンドリソースのリーチを指定します。 HTTPTargetConnection を使用する場合は、他のタイプのターゲット接続（ScriptTarget や LocalTargetConnection）を構成しないでください。注: `<LocalTargetConnection>` 要素は、メッセージテンプレートと呼ばれる動的な文字列置換機能をサポートしています。 `<Authentication>` 子要素を使用して、Cloud Functions や Cloud Run などの Google Cloud プロダクトで実行されている Google サービスまたはカスタムサービスへの認証済み呼び出しを行うことができます。`<Authentication>` 要素を使用するには、Google 認証システムの使用で説明されている設定とデプロイの手順が必要です。適切に設定すると、ポリシーは認証トークンを作成し、それをサービスリクエストに追加します。`<Authentication>` 要素の使用もご覧ください。
`URL`	ターゲットエンドポイントがリクエストメッセージを転送する宛先バックエンドサービスのネットワークアドレスを定義します。	なし	×
`LoadBalancer`	1 つ以上の名前付き TargetServer 構成を定義します。名前付き TargetServer 構成は、2 つ以上のエンドポイント構成接続を定義するロードバランシングに使用できます。ターゲットサーバーを使用して、具体的なバックエンドサービスのエンドポイント URL から API プロキシ構成を切り離すこともできます。	なし	×
`Properties`	オプションの HTTP 構成設定のセットは、`<TargetEndpoint>` のプロパティとして定義できます。	なし	×
`SSLInfo`	必要に応じてターゲットエンドポイントに TLS / SSL 設定を定義して、API プロキシとターゲットサービス間の TLS / SSL 接続を制御します。TLS / SSL TargetEndpoint 構成をご覧ください。注: `<SSLInfo>` 要素は、メッセージテンプレートと呼ばれる動的な文字列置換機能をサポートしています。	なし	×
`LocalTargetConnection`	その子要素により、ロードバランシングやメッセージプロセッサなどのネットワーク特性を考慮することなく、ローカルでアクセスするリソースを指定します。ターゲットリソースを指定するには、APIProxy 子要素（ProxyEndpoint 要素を含む）または Path 子要素のいずれかを含めます。詳細については、チェーンによる API プロキシの接続をご覧ください。 HTTPTargetConnection を使用する場合は、他のタイプのターゲット接続（LocalTargetConnection や ScriptTarget）を構成しないでください。
`APIProxy`	リクエストのターゲットとして使用する API プロキシの名前を指定します。ターゲットプロキシは、リクエストを送信するプロキシと同じ組織と環境に属している必要があります。これは Path 要素を使用する代わりに用いられる方法です。	なし	×
`ProxyEndpoint`	APIProxy とともに使用して、ターゲットプロキシのプロキシエンドポイントの名前を指定します。	なし	×
`Path`	リクエストのターゲットとして使用する API プロキシのエンドポイントパスを指定します。ターゲットプロキシは、リクエストを送信するプロキシと同じ組織と環境に属している必要があります。これは、APIProxy を使用する代わりに用いられる方法です。	なし	×
`FaultRules`	ターゲットエンドポイントがエラーに対してどのように反応するかを定義します。障害ルールには以下の 2 つの事項を指定します。あらかじめ定義されている障害のカテゴリ、サブカテゴリ、または名前に基づいて処理対象の障害を指定する条件。対応する条件で使用する障害ルールの動作を定義する 1 つまたは複数のポリシー。障害の処理をご覧ください。	なし	×
`DefaultFaultRule`	別の FaultRule によって明示的に処理されないエラー（システム、トランスポート、メッセージング、ポリシー）を処理します。障害の処理をご覧ください。	なし	×

`<Authentication>` 要素の使用

<TargetEndpoint> での <Authentication> 要素の使用方法は、ServiceCallout ポリシーでの <Authentication> 要素の使用方法と同じです。<TargetEndpoint> と ServiceCallout の両方で、<Authentication> は <HttpTargetConnection> の部分要素です。詳しくは、ServiceCallout ポリシーリファレンスの Authentication 要素をご覧ください。

`<Authentication>` 要素のエラーリファレンス

<Authentication> 要素を使用している場合は、ServiceCallout ポリシードキュメントのエラーセクションに、デプロイエラーとランタイムエラーのエラーメッセージとトラブルシューティングのヒントが記載されています。

`<Authentication>` 要素の例

次の例は、Authentication 要素を使用して、ターゲットとして Cloud Run にデプロイされたサービスを呼び出し、呼び出しの認証に必要な OpenID Connect トークンを生成する方法を示しています。

<TargetEndpoint name="TargetEndpoint-1">
  <HTTPTargetConnection>
      <Properties/>
      <URL>https://cloudrun-hostname.a.run.app/test</URL>
      <Authentication>
          <GoogleIDToken>
             <Audience>https://cloudrun-hostname.a.run.app/test</Audience>
          </GoogleIDToken>
     </Authentication>
  </HTTPTargetConnection>
</TargetEndpoint>

次の例は、Authentication 要素を使用して Cloud Run を指す TargetService を呼び出し、この呼び出しの認証に必要な OpenID Connect トークンを生成する方法を示しています。HeaderName 要素は、生成された署名なしトークンを X-Serverless-Authorization というヘッダーに追加し、ターゲットシステムに送信します。Authorization ヘッダーが存在する場合は、変更されずにリクエストで送信されます。

<TargetEndpoint name="TargetEndpoint-1">
   <HTTPTargetConnection>
     <Authentication>
        <HeaderName>X-Serverless-Authorization</HeaderName>
        <GoogleIDToken>
            <Audience ref="flow.variable.audience">https://cloudrun-hostname.a.run.app</Audience>
        </GoogleIDToken>
     </Authentication>
      <LoadBalancer>
         <Server name="cloud-run-target" />
      </LoadBalancer>
   </HTTPTargetConnection>
</TargetEndpoint>

次の例は、Google Secret Manager サービスを参照する TargetService を呼び出す方法を示しています。この例では、GoogleAccessToken 要素は、ターゲットリクエストを認証するための Google Auth Token を生成するように構成されています。

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

次の例は、GoogleIDToken のオーディエンスを自動的に設定する方法を示しています。useTargetUrl が true で、参照される変数が有効な変数に解決されない場合、ターゲット（クエリパラメータを除く）の URL がオーディエンスとして使用されます。リクエストパスが /foobar で、ターゲットサーバーの URL が https://xyz.com の場合、GoogleIDToken のオーディエンスは自動的に https://xyz.com/foobar に設定されます。

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

<TargetEndpoint name="TargetEndpoint-1">
  <HTTPTargetConnection>
    <Authentication>
      <GoogleIDToken>
        <Audience ref='myvariable' useTargetUrl="true"/>
      </GoogleIDToken>
    </Authentication>
    <LoadBalancer>
      <Server name="TS" />
    </LoadBalancer>
  </HTTPTargetConnection>
</TargetEndpoint>

TLS / SSL TargetEndpoint 構成

多くの場合、ターゲットエンドポイントでは異種のバックエンドインフラストラクチャで HTTPS 接続を管理する必要があります。このため、多くの TLS / SSL 構成設定がサポートされています。

TLS / SSL TargetEndpoint 構成要素

名前	説明	デフォルト	必須かどうか
`SSLInfo`	`<SSLInfo>` ブロックは、一方向 TLS / SSL と双方向 TLS / SSL の両方で使用できます。
`Enabled`	`<Enabled>` を `true` に設定すると、`<SSLInfo>` ブロックが使用されます。`false` に設定すると、`<SSLInfo>` ブロックは無視されます。 `<Enabled>` のデフォルト値は、`<URL>` で HTTPS プロトコルが指定されている場合は `true`、`<URL>` で HTTP が指定されている場合は `false` です。	`<URL>` で HTTPS が指定されている場合は true	×
`Enforce`	Apigee とターゲットバックエンドの間に厳格な SSL を適用します。 `true` に設定すると、無効な証明書、期限切れの証明書、自己署名証明書、ホスト名の一致しない証明書、信頼できないルートの証明書を使用するターゲットが接続に失敗します。エラーコード `4xx` または `5xx` が返されます。未設定または `false` に設定すると、証明書に問題があるターゲットバックエンドへの接続結果は、`<IgnoreValidationErrors>` の設定によって異なります（以下をご覧ください）。`<IgnoreValidationErrors>` が `true` に設定されている場合、特定の条件下で成功レスポンス（`2xx`）が発生することがあります。	`false`	×
`TrustStore`	信頼できるルートサーバー証明書を含むキーストア。Apigee から送信された証明書チェーンがこのキーストアに含まれる証明書で終了する場合、リモートピアは信頼できるものとして扱われます。	なし	×
`ClientAuthEnabled`	`true` に設定すると、Apigee とリモートピア（API クライアントまたはターゲットバックエンド）間の双方向 TLS（相互 TLS または mTLS）が有効になります。双方向 TLS を有効にするには、通常、Apigee にトラストストアとキーストアの両方を設定する必要があります。	`false`	×
`KeyStore`	アウトバウンドクライアント認証に使用される秘密鍵を含むキーストア	なし	○（ClientAuthEnabled が true の場合）
`KeyAlias`	アウトバウンドクライアント認証に使用される秘密鍵のエイリアス	なし	○（ClientAuthEnabled が true の場合）
`IgnoreValidationErrors`	検証エラーが無視されるかどうかを示します。バックエンドシステムが SNI を使用し、ホスト名と一致しないサブジェクトの識別名 (DN) を持つ証明書を返す場合、エラーを無視する方法がなく、接続が失敗します。注: `<Enforce>` が `true` に設定されている場合、`<IgnoreValidationErrors>` の値は無視されます。	`false`	×
`Ciphers`	アウトバウンド TLS / SSL でサポートされている暗号。暗号が指定されていない場合、JVM で使用可能なすべての暗号が許可されます。暗号を制限するには、以下のサポートされた暗号リストから要素を追加します。 <Ciphers> <Cipher>TLS_RSA_WITH_3DES_EDE_CBC_SHA</Cipher> <Cipher>TLS_RSA_WITH_DES_CBC_SHA</Cipher> </Ciphers>	なし	×
`Protocols`	アウトバウンド TLS / SSL でサポートされているプロトコル。プロトコルを指定されていない場合は、JVM で使用可能なすべてのプロトコルが許可されます。プロトコルを制限するには、明示的に指定します。たとえば、TLS v1.2 または TLS v1.3 のみを許可するには、次のようにします。 <Protocols> <Protocol>TLSv1.2</Protocol> <Protocol>TLSv1.3</Protocol> </Protocols>	なし	×
`CommonName`	Apigee は、この値をリモートピア証明書の CN（共通名）または SAN（サブジェクト代替名）と照合します。	なし	×

アウトバウンドクライアント認証を有効にしたターゲットエンドポイントの例

<TargetEndpoint name="default">
  <HttpTargetConnection>
        <URL>https://myservice.com</URL>
    <SSLInfo>
      <Enabled>true</Enabled>
      <Enforce>true</Enforce>
      <ClientAuthEnabled>true</ClientAuthEnabled>
      <KeyStore>myKeystore</KeyStore>
      <KeyAlias>myKey</KeyAlias>
      <TrustStore>myTruststore</TrustStore>
    </SSLInfo>
  </HttpTargetConnection>
</TargetEndpoint>

詳細な手順については、TLS を構成するためのオプションをご覧ください。

フロー変数を使用した TLS / SSL 値の動的設定

TLS / SSL の詳細を動的に設定して、ランタイム要件を柔軟にサポートすることもできます。たとえば、プロキシが 2 つの異なるターゲット（テストターゲットと本番環境ターゲット）に接続する場合、API プロキシがプログラムによって呼び出し元の環境を検出し、適切なキーストアとトラストストアへの参照を動的に設定できます。この事例の詳細については、変数リファレンスを使用した TargetEndpoint の動的 SSLInfo という Apigee コミュニティにある記事をご覧ください。ここでは、デプロイ可能な API プロキシの例も示されています。

TargetEndpoint 構成で <SSLInfo> タグが設定される仕組みを示す次の例では、Java Callout、JavaScript ポリシー、AssignMessage ポリシーなど、ランタイムで値を指定できます。設定する値を含むメッセージ変数を使用します。

変数は次の要素にのみ使用できます。

<SSLInfo>
    <Enabled>{myvars.ssl.enabled}</Enabled>
    <ClientAuthEnabled>{myvars.ssl.client.auth.enabled}</ClientAuthEnabled>
    <KeyStore>{myvars.ssl.keystore}</KeyStore>
    <KeyAlias>{myvars.ssl.keyAlias}</KeyAlias>
    <TrustStore>{myvars.ssl.trustStore}</TrustStore>
</SSLInfo>

参照を使用した TLS / SSL 値の動的設定

HTTPS を使用するターゲットエンドポイントを構成する際は、TLS / SSL 証明書の有効期限が切れる場合や、システム構成の変更で証明書を更新しなければならなくなる場合を考慮する必要があります。

詳細については、期限切れの証明書の処理をご覧ください。

ただし、ターゲットエンドポイントでキーストアまたはトラストストアへの参照を使用するように構成することもできます。参照を使用する利点は、別のキーストアまたはトラストストアを参照するように更新して、メッセージプロセッサを再起動することなく TLS / SSL 証明書を更新できることです。

たとえば、キーストアへの参照を使用するターゲットエンドポイントの例を次に示します。

<SSLInfo>
  <Enabled>true</Enabled>
  <ClientAuthEnabled>false</ClientAuthEnabled>
  <KeyStore>ref://keystoreref</KeyStore>
  <KeyAlias>myKeyAlias</KeyAlias>
</SSLInfo>

次の POST API 呼び出しを使用して、keystoreref という名前の参照を作成します。

curl "https://apigee.googleapis.com/v1/organizations/{org}/environments/{org}/references" \
  -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -d '<ResourceReference name="keystoreref">
    <Refers>myTestKeystore</Refers>
    <ResourceType>KeyStore</ResourceType>
</ResourceReference>'

ここで、OAuth 2.0 アクセストークンの取得で説明されているように、$TOKEN は OAuth 2.0 アクセストークンに設定されます。この例で使用されている curl オプションの詳細については、curl の使用をご覧ください。使用される環境変数の説明については、Apigee API リクエストの環境変数の設定をご覧ください。

この参照では、キーストアの名前とそのタイプを指定しています。

次の GET API 呼び出しを使用してリファレンスを表示します。

curl "https://apigee.googleapis.com/v1/organizations/{org}/environments/{org}/references/keystoreref" \
  -H "Authorization: Bearer $TOKEN"

curl "https://apigee.googleapis.com/v1/organizations/{org}/environments/{org}/references/keystoreref" \
  -H "Authorization: Bearer $TOKEN"

後で別のキーストアを参照するように変更し、エイリアスの名前が同じになるようにするには、次の PUT 呼び出しを使用します。

curl "https://apigee.googleapis.com/v1/organizations/{org}/environments/{org}/references/keystoreref" \
  -X PUT \
  -H "Authorization: Bearer $TOKEN" \
  -d '<ResourceReference name="keystoreref">
    <Refers>myNewKeystore</Refers>
    <ResourceType>KeyStore</ResourceType>
  </ResourceReference>'

ターゲットロードバランシングを行う TargetEndpoint

ターゲットエンドポイントは、3 種類のロードバランシングアルゴリズムを使用した複数の名前付きターゲットサーバー間のロードバランシングをサポートしています。

詳細な手順については、バックエンドサーバー間のロードバランシングをご覧ください。

IntegrationEndpoint

IntegrationEndpoint は、Apigee Integration を特別に実行するターゲットエンドポイントです。IntegrationEndpoint が構成されている場合、Apigee は、リクエストを実行するためにリクエストオブジェクトを Apigee Integration Platform に送信します。統合を実行するには、IntegrationEndpoint を構成するだけでなく、プロキシフローに SetIntegrationRequest ポリシーを追加する必要もあります。

IntegrationEndpoint 構成で <AsyncExecution> 要素を設定すると、同期的または非同期的に実行するように統合を構成できます。詳しくは、同期的実行と非同期的実行をご覧ください。統合の実行後、Apigee はレスポンスをレスポンスメッセージに保存します。

注: IntegrationEndpoint を実行するには、認証トークンが必要です。ただし、IntegrationEndpoint の定義に明示的な <Authentication> 要素はありません。Apigee は、内部でリクエストに認証トークンを追加します。IntegrationEndpoint が正常に認証されるようにするには、統合の実行に必要な IAM ロールを持つサービスアカウントで API プロキシをデプロイする必要があります。必要なロールについては、統合の IAM ロールをご覧ください。API プロキシのデプロイの詳細については、Apigee にデプロイするをご覧ください。

IntegrationEndpoint の構成

統合エンドポイントをターゲットエンドポイントとして構成するには、IntegrationEndpoint 要素を ProxyEndpoint 構成に追加します。ProxyEndpoint 構成の例を次に示します。

<ProxyEndpoint name="default">
    <Description/>
    <FaultRules/>
    <PreFlow name="PreFlow">
        <Request>
            <Step>
                <Name>my-set-integration-request-policy</Name>
            </Step>
        </Request>
    </PreFlow>
    <Flows/>
    <PostFlow name="PostFlow"/>
    <HTTPProxyConnection>
        <BasePath>/integration-endpoint-test</BasePath>
        <Properties/>
    </HTTPProxyConnection>
    <RouteRule name="default">
        <IntegrationEndpoint>my-int-endpoint</IntegrationEndpoint>
    </RouteRule>
</ProxyEndpoint>

この ProxyEndpoint 構成の例では、Apigee は次のタスクを行います。

PreFlow で、my-set-integration-request-policy という名前のポリシーを実行します。これにより、統合リクエストオブジェクトと統合フロー変数が設定されます。
RouteRule で指定されているように、my-int-endpoint をターゲットエンドポイントとして使用します。
my-set-integration-request-policy によって作成された統合リクエストオブジェクトを読み取ります。
SetIntegrationRequest ポリシーで設定されたリクエストオブジェクトとフロー変数を使用して、リクエストを Apigee Integration Platform に送信します。
統合のレスポンスをレスポンスメッセージに保存します。

<IntegrationEndpoint> 宣言を含む XML ファイルは APIGEE_BUNDLE_DIRECTORY/apiproxy/integration-endpoints/ ディレクトリにありますDevelop > API Proxies > CREATE NEW > Integration target オプションを使用して API プロキシを作成すると、Apigee は宣言を /apiproxy/integration-endpoints/default.xml ファイルに保存します。UI から統合エンドポイント XML を作成する場合は、XML ファイルにカスタム名を指定できます。

次の例では、XML ファイル内の <IntegrationEndpoint> 要素の宣言を示します。

<IntegrationEndpoint name="my-int-endpoint">
    <AsyncExecution>false</AsyncExecution>
</IntegrationEndpoint>

IntegrationEndpoint の構成要素

名前	説明	デフォルト	必須かどうか
`IntegrationEndpoint`
`name`	IntegrationEndpoint の名前。名前に使用できる文字は `A-Za-z0-9._\-$ %` のみです。	なし	○
`AsyncExecution`	統合を同期モードと非同期モードのどちらで実行するかを指定するブール値。詳しくは、同期的実行と非同期的実行をご覧ください。	false	×

同期実行と非同期実行

この統合は、同期モードまたは非同期モードのいずれかで実行されるように構成できます。同期実行モードと非同期実行モードの相違については、<AsyncExecution> をご覧ください。

</IntegrationEndpoint> 内で <AsyncExecution> 要素を使用して、同期的実行または非同期的実行を指定します。<AsyncExecution> を true に設定すると、統合は非同期的に実行されます。false に設定すると、統合は同期的に実行されます。

次の例では、AsyncExecution を true に設定しています。

<IntegrationEndpoint name="my-int-endpoint">
    <AsyncExecution>true</AsyncExecution>
</IntegrationEndpoint>

ポリシー

API プロキシの /policies ディレクトリには、API プロキシのフローに接続できるすべてのポリシーが含まれています。

ポリシー構成要素

名前	説明	デフォルト	必須かどうか
`Policy`
`name`	ポリシーの内部名。名前に使用できる文字は `A-Za-z0-9._\-$ %` のみです。ただし、Apigee UI には追加の制限があり、英数字以外の文字は自動的に削除されます。必要に応じて、`<DisplayName>` 要素を使用して、Apigee UI プロキシエディタでポリシーに別の自然言語名でラベルを付けます。	なし	○
`enabled`	ポリシーを適用するには、`true` に設定します。ポリシーを無効にするには、`false` に設定します。ポリシーがフローに接続されている場合でも適用されません。	`true`	×
`continueOnError`	ポリシーが失敗したときにエラーを返す場合は、`false` に設定します。これは、ほとんどのポリシーで想定される動作です。ポリシーが失敗した後もフローの実行を続行する場合は、`true` に設定します。	`false`	×
`async`	注: この属性によってポリシーが非同期に実行されることはありません。ほとんどの場合、デフォルトの `false` のままにしておきます。 `true` に設定すると、ポリシーの実行が別のスレッドにオフロードされ、メインスレッドは追加のリクエストを処理できるようになります。オフライン処理が完了すると、メインスレッドが戻ってメッセージフローの処理を終了します。場合によっては、非同期を `true` に設定すると、API プロキシのパフォーマンスが向上することがあります。だだし、非同期を過度に使用すると、スレッド切り替えが多くなりすぎてパフォーマンスが低下する可能性があります。 API プロキシで非同期の動作を使用するには、JavaScript オブジェクトモデルをご覧ください。	`false`	×

ポリシー接続

次の図は、API プロキシフローの実行順序を示しています。

HTTP サービスを呼び出すクライアントの図。リクエストはプロキシエンドポイントとターゲットエンドポイントを通過します。これらの各エンドポイントに、ポリシーをトリガーするステップが含まれています。HTTP サービスからレスポンスが返されると、そのレスポンスはターゲットエンドポイントで処理され、続いてプロキシエンドポイントで処理されてからクライアントに返されます。リクエストの場合と同じく、レスポンスはステップ内でポリシーによって処理されます。

上記のフローの説明:

ポリシーは Flow への処理ステップとして接続されます。ポリシーの名前は、処理ステップとして実施されるポリシーを参照するために使用されます。ポリシー接続の形式は次のとおりです。

<Step><Name>MyPolicy</Name></Step>

ポリシーは Flow に接続されている順序で適用されます。次に例を示します。

<Step><Name>FirstPolicy</Name></Step>
<Step><Name>SecondPolicy</Name></Step>

ポリシー接続の構成要素

名前	説明	デフォルト	必須かどうか
`Step`
`Name`	このステップ定義によって実行されるポリシーの名前。	なし	○
`Condition`	ポリシーが適用されているかどうかを判断する条件文。ポリシーに関連する条件がある場合、条件文が true と評価されればポリシーが実行されます。	なし	×

フロー

ProxyEndpoint と TargetEndpoint は、リクエストとレスポンスのメッセージを処理するためのパイプラインを定義します。処理パイプラインは、リクエストフローとレスポンスフローで構成されます。各リクエストフローとレスポンスフローは PreFlow、1 つ以上のオプションの条件または名前付フローと PostFlow に細分化されます。

PreFlow: 常に実行します。条件付きフローの前に実行されます。
PostFlow: 常に実行されます。条件付きフローの後に実行されます。

さらに、プロキシエンドポイントに PostClientFlow を追加できます。このフローは、レスポンスが要求元のクライアントアプリに返された後に実行されます。このフローには、MessageLogging ポリシーのみを接続できます。PostClientFlow により、API プロキシのレイテンシが短縮されます。このフローでは、レスポンスがクライアントに返されるまで計算されないロギングの情報（client.sent.start.timestamp や client.sent.end.timestamp など）を使用できます。このフローは主に、レスポンスメッセージの開始と終了のタイムスタンプの間隔を測定するために使用されます。

Message Logging ポリシーが接続されている PostClientFlow の例を次に示します。

...
  <PostFlow name="PostFlow">
      <Request/>
      <Response/>
  </PostFlow>
  <PostClientFlow>
      <Request/>
      <Response>
          <Step>
              <Name>Message-Logging-1</Name>
          </Step>
      </Response>
  </PostClientFlow>
  ...

API プロキシ処理パイプラインは、次の順序でフローを実行します。

リクエストパイプライン:

プロキシリクエスト PreFlow
プロキシリクエストの条件付きフロー（オプション）
プロキシリクエスト PostFlow
ターゲットリクエスト PreFlow
ターゲットリクエストの条件付きフロー（オプション）
ターゲットリクエスト PostFlow

レスポンスパイプライン:

ターゲットレスポンス PreFlow
ターゲットレスポンスの条件付きフロー（オプション）
ターゲットレスポンス PostFlow
プロキシレスポンス PreFlow
プロキシレスポンスの条件付きフロー（オプション）
プロキシレスポンス PostFlow
PostClientFlow レスポンス（オプション）

ProxyEndpoint または TargetEndpoint の構成では、ポリシー接続を持つフローのみを構成する必要があります。PreFlow または PostFlow 処理中にポリシーを適用する必要がある場合は、PreFlow と PostFlow を ProxyEndpoint または TargetEndpoint 構成でのみ指定します。

条件フローとは対照的に、PreFlow 要素と PostFlow 要素の順序は重要ではありません。API プロキシは、エンドポイント構成のどこに表示されるかにかかわらず、パイプラインの適切なポイントでそれぞれを常に実行します。

条件フロー

プロキシエンドポイントとターゲットエンドポイントは、条件フロー（または名前付きフロー）を無制限にサポートします。

API プロキシでは、条件フローに指定されている条件がテストされます。条件が満たされると、条件フローの処理ステップが API プロキシによって実行されます。条件が満たされない場合は、条件付きフローのその処理ステップは省略されます。条件付きフローは API プロキシで定義されている順に評価され、条件が最初に満たされたフローが実行されます。

条件付きフローを定義することにより、次に基づいて、API プロキシに処理ステップを適用できます。

リクエスト URI
HTTP 動詞（GET / PUT / POST / DELETE）
クエリパラメータ、ヘッダー、フォームパラメータの値
その他多くのタイプの条件

たとえば、次の条件付きフローは、リクエストリソースのパスが /accesstoken の場合にのみ実行されるように指定します。パスが /accesstoken のインバウンドリクエストの場合、このフローは、フローに追加されているすべてのポリシーとともに実行されます。リクエストパスに接尾辞 /accesstoken が含まれていない場合、フローは実行されません（ただし、別の条件きフローが実行される可能性があります）。

<Flows>
  <Flow name="TokenEndpoint">
    <Condition>proxy.pathsuffix MatchesPath "/accesstoken"</Condition>
    <Request>
      <Step>
        <Name>GenerateAccessToken</Name>
      </Step>
    </Request> 
  </Flow>
</Flows>

フロー構成要素

名前	説明	デフォルト	必須かどうか
`Flow`	プロキシエンドポイントまたはターゲットエンドポイントによって定義されたリクエストまたはレスポンス処理パイプライン
`Name`	フローの一意の名前。	なし	○
`Condition`	true または false を評価するための変数を評価する条件文。事前定義済みの PreFlow と PostFlow タイプ以外のすべてのフローは、実行条件を定義する必要があります。ただし、一連のフローの末尾に条件のない単一のフローを含めると、そのフローは、一連のフローの末尾に配置された「Else」ステートメントとして機能します。	なし	○
`Request`	リクエストメッセージ処理に関連するパイプライン	なし	×
`Response`	レスポンスメッセージ処理に関連するパイプライン	なし	×

ステップ処理

条件フローの順序づけは、Apigee によって適用されます。条件フローは上から下に実行されます。条件が true と評価される最初の条件付きフローが実行され、1 つの条件付きフローのみが実行されます。

たとえば、次のフロー構成では、パス接尾辞 /first または /second を含まないインバウンドリクエストの場合、ThirdFlow が実行され、Return404 というポリシーが適用されます。

<Flows>
  <Flow name="FirstFlow">
    <Condition>proxy.pathsuffix MatchesPath "/first"</Condition>
    <Request>
      <Step><Name>FirstPolicy</Name></Step>
    </Request>
  </Flow>
  <Flow name="SecondFlow">
    <Condition>proxy.pathsuffix MatchesPath "/second"</Condition>
    <Request>
      <Step><Name>FirstPolicy</Name></Step>
      <Step><Name>SecondPolicy</Name></Step>
    </Request>
  </Flow>
  <Flow name="ThirdFlow">
    <Request>
      <Step><Name>Return404</Name></Step>
    </Request>
  </Flow>
</Flows>

リソース

「リソース」（API プロキシで使用するリソースファイル）は、ポリシーを使用してフローに接続できるスクリプト、コード、XSL 変換です。これらは、Apigee UI の API プロキシエディタの [Scripts] セクションに表示されます。

サポートされるリソースタイプについては、リソースの管理をご覧ください。

リソースは、API プロキシ、環境、組織のいずれかに保存できます。いずれの場合も、リソースはポリシー内で名前によって参照されます。Apigee は、API プロキシから環境、組織レベルに移動して名前を解決します。

組織レベルで格納されたリソースは、どの環境のポリシーでも参照できます。環境レベルで格納されたリソースは、その環境のポリシーによって参照されます。API プロキシレベルで格納されたリソースは、その API プロキシ内のポリシーによってのみ参照できます。