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

Apigee X のドキュメントが表示されています。
Apigee Edge のドキュメントを参照する。

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

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

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

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

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

apiproxy をルート ディレクトリとするディレクトリ構造を表示apiproxy ディレクトリの直下には、ポリシー、プロキシ、リソース、ターゲットの各ディレクトリと 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 ディレクトリにある ProxyEndpoints のリスト。通常、Apigee UI を使用して API プロキシを作成した場合にのみこの要素が表示されます。これは単なるマニフェスト設定であり、API プロキシの内容を可視化するように設計されています。 該当なし ×
Resources この API プロキシの /resources ディレクトリにあるリソース(JavaScript、Python、Java、XSLT)のリスト。通常、Apigee UI を使用して API プロキシを作成した場合にのみこの要素が表示されます。これは単なるマニフェスト設定であり、API プロキシの内容を可視化するように設計されています。 該当なし ×
Spec API プロキシに関連付けられている OpenAPI 仕様を識別します。値は、URL または仕様ストア内のパスに設定されます。
なし ×
TargetServers この API プロキシの TargetEndpoints で参照される TargetServers のリスト。通常、Apigee を使用して API プロキシを作成した場合にのみ、この要素が表示されます。これは単なるマニフェスト設定であり、API プロキシの内容を可視化するように設計されています。 該当なし ×
TargetEndpoints この API プロキシの /targets ディレクトリにある TargetEndpoints のリスト。通常、Apigee UI を使用して API プロキシを作成した場合にのみこの要素が表示されます。これは単なるマニフェスト設定であり、API プロキシの内容を可視化するように設計されています。 該当なし ×

ProxyEndpoint

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

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

/apiproxy/proxies/default.xml

ProxyEndpoint 構成では、API プロキシのインバウンド(クライアントに対する)インターフェースが定義されます。ProxyEndpoint を構成するときに、プロキシされた 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 構成要素

名前 説明 デフォルト 必須
ProxyEndpoint
name ProxyEndpoint の名前。複数の ProxyEndpoints が定義されている場合(まれです)、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/membershttps://[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
ProxyEndpoint がエラーに対してどのように反応するかを定義します。障害ルールには以下の 2 つの事項を指定します。
  • あらかじめ定義されている障害のカテゴリ、サブカテゴリ、または名前に基づいて処理対象の障害を指定する条件。
  • 対応する Condition で使用する障害ルールの動作を定義する 1 つまたは複数のポリシー。

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

なし ×
DefaultFaultRule

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

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

なし ×
RouteRule ProxyEndpoint リクエスト パイプラインによる処理後のインバウンド リクエスト メッセージの宛先を定義します。通常、RouteRule は指定された TargetEndpoint の構成を指しますが、URL を直接指すこともできます。
Name RouteRule に名前を与える必須属性。名前に使用できる文字は、A-Za-z0-9._\-$ % のみです。たとえば、Cat2 %_ は正式名称です。 なし
Condition 実行時の動的ルーティングに使用されるオプションの条件付きステートメント。条件付きの RouteRules は、コンテンツ ベースのルーティングでバックエンドのバージョニングをサポートできるようにする場合などに便利です。 なし ×
TargetEndpoint

指定された TargetEndpoint 構成を識別するオプションの文字列。名前付き TargetEndpoint は、/targets ディレクトリの下にある同じ API で定義された TargetEndpoint です。

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

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

なし いいえ
URL ProxyEndpoint によって呼び出されるアウトバウンド ネットワーク アドレスを定義するオプションの文字列。/targets に格納されている可能性のある TargetEndpoint 構成をバイパスします。 なし ×

RouteRules の構成方法

名前付き TargetEndpoint は、/apiproxy/targets の下にある構成ファイルを参照し、RouteRule は ProxyEndpoint による処理後にリクエストをこのファイルに転送します。

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

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

URL の直接呼び出し

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

たとえば、次の 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 という名前の TargetEndpoint に転送されます。そうでない場合、受信リクエストは 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 を定義して、リクエスト メッセージを TargetEndpoint に転送する必要がないシナリオをサポートできます。これは、ProxyEndpoint が JavaScript を使用して外部サービスを呼び出したり、API サービスの Key-Value ストアを参照してデータを取得したりするなど、ProxyEndpoint が必要なすべての処理を行う際に便利です。

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

<RouteRule name="GoNowhere"/>

条件付きの Null ルートは便利です。次の例では、HTTP ヘッダー request.header.X-DoNothingnull 以外の値が設定されている場合は 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

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

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

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

TargetEndpoint の構成

/targets/default.xml

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

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

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

TargetEndpoint の構成要素

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

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

これらのうち 1 つのみを TargetEndpoint に構成します。

名前 説明 デフォルト 必須
TargetEndpoint
name API プロキシの構成内で一意でなければならない TargetEndpoint の名前。TargetEndPoint の名前は、アウトバウンド処理のリクエストを指示するために ProxyEndpoint RouteRule で使用されます。名前に使用できる文字は、A-Za-z0-9._\-$ % のみです。 なし
PreFlow リクエストやレスポンスの PreFlow 内のポリシーを定義します。 なし
Flows
リクエストやレスポンスの条件付きフロー内のポリシーを定義します。
なし
PostFlow
リクエストやレスポンスの PostFlow 内のポリシーを定義します。
なし
HTTPTargetConnection

その子要素を使用して、HTTP 経由でバックエンド リソースのリーチを指定します。

HTTPTargetConnection を使用する場合は、他のタイプのターゲット接続(ScriptTarget や LocalTargetConnection)を構成しないでください。

<Authentication> 子要素を使用して、特定の Google Cloud プロダクト(Cloud FunctionsCloud Run)で実行されている Google サービスまたはカスタム サービスに対して認証済みの呼び出しを行います。 <Authentication> 要素を使用するには、Google 認証の使用で説明されている設定とデプロイの手順が必要です。適切に設定した場合、ポリシーによって認証トークンが作成され、サービス リクエストに追加されます。 <Authentication> 要素の使用もご覧ください。

URL TargetEndpoint がリクエスト メッセージを転送するバックエンド サービスのネットワーク アドレスを定義します。 なし ×
LoadBalancer

1 つ以上の名前付き TargetServer 構成を定義します。名前付き TargetServer 構成は、2 つ以上のエンドポイント構成接続を定義するロード バランシングに使用できます。

TargetServers を使用して、具体的なバックエンド サービスのエンドポイント URL から API プロキシ構成を切り離すこともできます。

なし ×
Properties オプションの HTTP 構成設定のセットは、<TargetEndpoint> のプロパティとして定義できます。 なし いいえ
SSLInfo 必要に応じて、TargetEndpoint に TLS / SSL 設定を定義して、API プロキシとターゲット サービス間の TLS / SSL 接続を制御します。TLS /SSL TargetEndpoint 構成をご覧ください。 該当なし ×
LocalTargetConnection その子要素により、ロード バランシングやメッセージ プロセッサなどのネットワーク特性を考慮することなく、ローカルでリーチするリソースを指定します。

ターゲット リソースを指定するには、APIProxy 子要素(ProxyEndpoint 要素を含む)または Path 子要素のいずれかを含めます。

詳細については、チェーンによる API プロキシの接続をご覧ください。

HTTPTargetConnection を使用する場合は、他のタイプのターゲット接続(LocalTargetConnection や ScriptTarget)を構成しないでください。

APIProxy リクエストのターゲットとして使用する API プロキシの名前を指定します。ターゲット プロキシは、リクエストを送信するプロキシと同じ組織と環境に属している必要があります。これは Path 要素を使用する代わりに用いられる方法です。 なし ×
ProxyEndpoint APIProxy とともに使用して、ターゲット プロキシの ProxyEndpoint の名前を指定します。 なし ×
Path リクエストのターゲットとして使用する API プロキシのエンドポイント パスを指定します。ターゲット プロキシは、リクエストを送信するプロキシと同じ組織と環境に属している必要があります。これは、APIProxy を使用する代わりに用いられる方法です。 なし ×
FaultRules
TargetEndpoint がエラーに対してどのように反応するかを定義します。障害ルールには以下の 2 つの事項を指定します。
  • あらかじめ定義されている障害のカテゴリ、サブカテゴリ、または名前に基づいて処理対象の障害を指定する条件。
  • 対応する Condition で使用する障害ルールの動作を定義する 1 つまたは複数のポリシー。

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

なし ×
DefaultFaultRule

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

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

なし ×

<Authentication> 要素の使用

<TargetEndpoint> での <Authentication> 要素の使用は、ServiceCallout ポリシーでの <Authentication> 要素の使用と同じです。<TargetEndpoint> と ServiceCallout の両方で、<Authentication><HttpTargetConnection> のサブ要素です。詳細については、ServiceCallout ポリシー リファレンスの認証要素をご覧ください。

<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</Audience>
          </GoogleIDToken>
     </Authentication>
  </HTTPTargetConnection>
</TargetEndpoint>

次の例は、Authentication 要素を使用して Cloud Run を指す TargetService を呼び出し、この呼び出しの認証に必要な OpenID Connect トークンを生成する方法を示しています。


<TargetEndpoint name="TargetEndpoint-1">
   <HTTPTargetConnection>
     <Authentication>
        <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 認証トークンを生成するように構成されています。


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

TLS / SSL TargetEndpoint 構成

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

TLS / SSL TargetEndpoint 構成要素

名前 説明 デフォルト 必須
SSLInfo
Enabled エンドポイントに対して TLS / SSL が有効かどうかを示します。 デフォルト値は、<URL> で HTTPS プロトコルが指定されている場合は true<URL> で HTTP が指定されている場合は false です。 <URL> で HTTPS が指定されている場合は true ×
TrustStore 信頼できるサーバー証明書を含むキーストア。 なし ×
ClientAuthEnabled アウトバウンド クライアント認証(双方向 TLS / SSL)を有効にする設定。 false ×
KeyStore アウトバウンド クライアント認証に使用されるプライベート キーを含むキーストア なし ○(ClientAuthEnabled が true の場合)
KeyAlias アウトバウンド クライアント認証に使用されるプライベート キーのエイリアス なし ○(ClientAuthEnabled が true の場合)
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 で使用可能なすべてのプロトコルが許可されます。

プロトコルを制限するには、サポート対象のプロトコルをリストする以下の要素を追加します。


<Protocols>
 <Protocol>TLSv1.1</Protocol>
 <Protocol>TLSv1.2</Protocol>
</Protocols>
なし ×

アウトバウンド クライアント認証を有効にした TargetEndpoint の例

<TargetEndpoint name="default">
  <HttpTargetConnection>
        <URL>https://myservice.com</URL>
    <SSLInfo>
      <Enabled>true</Enabled>
      <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 を使用する TargetEndpoint を構成する際は、TLS / SSL 証明書の有効期限が切れる場合や、システム構成の変更で証明書を更新しなければならなくなる場合を考慮する必要があります。

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

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

たとえば、キーストアへの参照を使用する TargetEndpoint を次に示します。

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

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

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

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

後で別のキーストアを参照するように変更し、エイリアスの名前が同じになるようにするには、次の 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>'

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

ターゲット負荷分散を行う TargetEndpoint

TargetEndpoints は、3 つの負荷ポリシーを使用して、複数の名前付き TargetServer 間の負荷分散をサポートします。

詳細な手順については、バックエンド サーバー間の負荷分散をご覧ください。

ポリシー

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

ポリシー構成要素

名前 説明 デフォルト 必須
Policy
name

ポリシーの内部名。名前に使用できる文字は A-Za-z0-9._\-$ % のみです。ただし、Apigee UI では、英数字以外の文字を自動的に削除するなど、追加の制限が適用されます。

必要に応じて、<DisplayName> 要素を使用して、Apigee UI プロキシ エディタのポリシーに別の自然言語の名前でラベルを付けます。

なし
enabled

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

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

true ×
continueOnError

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

ポリシーが失敗してもフロー実行を続行するには、true に設定します。

false ×
async

true に設定すると、ポリシーの実行が別のスレッドにオフロードされ、メインスレッドは追加のリクエストを処理できるようになります。オフライン処理が完了すると、メインスレッドが戻ってメッセージ フローの処理を終了します。場合によっては、非同期を true に設定すると、API プロキシのパフォーマンスが向上することがあります。だだし、非同期を過度に使用すると、スレッド切り替えが多くなりすぎてパフォーマンスが低下する可能性があります。

API プロキシで非同期の動作を使用するには、JavaScript オブジェクト モデルをご覧ください。

false ×

ポリシーの適用(アタッチ)

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

HTTP サービスを呼び出すクライアントを示す図。リクエストは ProxyEndpoint と TargetEndpoint に渡されます。これら 2 つのエンドポイントのそれぞれに、ポリシーをトリガーするステップが含まれています。HTTP サービスからレスポンスが返されると、そのレスポンスは TargetEndpoint で処理され、続いて ProxyEndpoing で処理されてからクライアントに返されます。リクエストの場合と同じく、レスポンスはステップ内でポリシーによって処理されます。

上記のフローの説明:

ポリシーは 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: 常に実行されます。条件付きフローの後に実行されます。

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

クイック ハウツー動画を見る

動画: PostClientFlow での MessageLogging ポリシーの使用については、この短い動画をご覧ください。

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

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

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

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

  1. プロキシ リクエスト PreFlow
  2. プロキシ リクエストの条件付きフロー(オプション)
  3. プロキシ リクエスト PostFlow
  4. ターゲット リクエスト PreFlow
  5. ターゲット リクエストの条件付きフロー(オプション)
  6. ターゲット リクエスト PostFlow

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

  1. ターゲット レスポンス PreFlow
  2. ターゲット レスポンスの条件付きフロー(オプション)
  3. ターゲット レスポンス PostFlow
  4. プロキシ レスポンス PreFlow
  5. プロキシ レスポンスの条件付きフロー(オプション)
  6. プロキシ レスポンス PostFlow
  7. PostClientFlow レスポンス(オプション)

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

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

条件フロー

ProxyEndpoints と TargetEndpoints は、条件フロー(または名前付きフロー)を無制限にサポートします。

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 ProxyEndpoint または TargetEndpoint によって定義されたリクエストまたはレスポンス処理パイプライン
Name フローの一意の名前。 なし
Condition true または false と評価するための変数を評価する条件文。事前定義済みの PreFlow と PostFlow タイプ以外のすべてのフローは、実行の条件を定義する必要があります。 なし
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 プロキシ内のポリシーによってのみ参照できます。