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

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

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

プロキシ構成を編集する一般的な方法は次のとおりです。

プロキシ構成のローカル開発

プロキシ構成をダウンロードして、ローカルマシン上で編集できます。作業が終わったら、その結果を Edge にアップロードします。この方法により、プロキシ構成をソース管理やバージョン管理などの共有ワークフローに統合できます。さらに、プロキシ構成をローカルで処理する場合は、ローカルマシン上の自分がよく使う XML エディタと検証ツールを使用できます。

このセクションでは、UI を使って既存のプロキシ構成をダウンロードして編集し、編集後のプロキシ構成をデプロイできるよう Edge にアップロードする方法を説明します。apigeetool を使用して、新しいプロキシ構成をダウンロードしてデプロイすることもできます(ダウンロードには fetchproxy コマンド、デプロイには deployproxy コマンドを使用します)。

UI を使用してプロキシ構成をローカルで編集するには:

  1. Edge UI で現在のプロキシ構成をダウンロードします([API Proxies] ビューで [Project] > [Download Revision] を選択します)。
  2. ローカルマシン上に新しいディレクトリを作成し、ダウンロードした ZIP ファイルをそのディレクトリ内に展開します。

    ZIP ファイルを展開するには、unzip などのユーティリティを使用できます。次に例を示します。

    mkdir myappdir
        unzip ./my-app_app_rev3_2019_04_20.zip -d myappdir

    展開された ZIP ファイルのコンテンツは、API プロキシの構造で説明されているような構造になっているはずです。

  3. 必要に応じてソースファイルを編集します。プロキシ構成に含まれるソースファイルの説明については、API プロキシの構成ファイルとディレクトリ構造をご覧ください。

    たとえば、API プロキシでヘルス モニタリングを有効にするには、/apiproxy/targets/ ディレクトリ内にある TargetEndpoint 構成ファイルを編集します。このディレクトリ内にあるデフォルトのファイルは default.xml です。ただし、条件付きターゲットを使用している場合は、これとは異なる名前のファイルが存在することもあります。

    この例の場合、TargetEndpoint 構成ファイルとそのディレクトリが存在しなければ、新しく作成します。

  4. プロキシ構成ファイルの編集が終わったら、忘れずに変更を保存します。
  5. 現在のディレクトリを、ZIP ファイルを展開したときに新しく作成したディレクトリ(展開された構成ファイルのルート)に変更します。

    たとえば、/myappdir ディレクトリにファイルを展開した場合、カレント ディレクトリをそのディレクトリに変更するには、次の例に示すコマンドを使用します。

    cd myappdir

    プロキシ構成を再度アーカイブする前に、カレント ディレクトリをこのディレクトリに変更する必要がありあす。これは、/myappdir ディレクトリが ZIP ファイルに格納されないようにするためです。ZIP ファイル内の最上位のディレクトリは /apiproxy でなければなりません。

  6. プロキシ構成ファイルを、新しいファイルと変更後のファイルを含めて再度アーカイブします。それには、zip などのユーティリティを使用できます。次に例を示します。
    zip my-new-proxy.zip -r .

    ZIP ファイル内の最上位のディレクトリは /apiproxy でなければなりません。

    ZIP ファイル名に関する特別な要件はありません。たとえば、リビジョン番号をインクリメントしたり、ファイル名に日付を含めて指定したりする必要はありません。ただし、このようなファイル名にすると、デバッグやソース管理の際に役立ちます。

    新しいプロキシ構成をアップロードすると、Edge によってプロキシ構成のリビジョン番号が自動的にインクリメントされます。

  7. Edge UI を使用して新しいプロキシ構成をアップロードします([API Proxies] ビューで [Project] > [Upload a New Revision] を選択します)。

    「Bundle is invalid.」、「Empty bundle.」などのエラー メッセージを受け取った場合は、ZIP ファイルの最上位ディレクトリが /apiproxy であることを確認してください。そうなっていない場合は、ZIP ファイルを展開したディレクトリのルートからプロキシ構成ファイルを再度アーカイブします。

    新しいプロキシ構成をアップロードすると、Edge によってリビジョン番号がインクリメントされて [Revision Summary] ビューに表示されます。

    UI を使用してアップロードした後、Edge によって新しいリビジョンが自動的にデプロイされることはありません。

  8. 新しいリビジョンをデプロイします。

詳しくは、Apigee コミュニティチュートリアル: UI および Management API を使用してプロキシをダウンロードする方法をご覧ください。

API プロキシの構造

API プロキシは、次のように構成されています。

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

API プロキシ ディレクトリ構造とコンテンツ

上記の表内のコンポーネントは、次のディレクトリ構造の構成ファイルによって定義されています。

ディレクトリ構造を示す図。この構造のルートは apiproxy です。apiproxy ディレクトリの直下には、ポリシー、プロキシ、リソース、ターゲットの各ディレクトリと weatherapi.xml ファイルがあります。

API プロキシの構成ファイルとディレクトリ構造

このセクションでは、API プロキシの構成ファイルとディレクトリ構造について説明します。

基本構成

/apiproxy/weatherapi.xml

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

構成の例:

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

基本構成の要素

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

注: 仕様ストアは、New Edge エクスペリエンス のみで利用できます。仕様ストアの詳細については、仕様の管理と共有を参照してください。
なし ×
TargetServers この API プロキシの TargetEndpoints で参照される TargetServers のリスト。通常、Edge 管理 UI を使用して API プロキシを作成した場合にのみ、この要素が表示されます。これは、単に「マニフェスト」設定であって、API プロキシの内容を視認できるように設計されています。 なし ×
TargetEndpoints この API プロキシの /targets ディレクトリにある TargetEndpoints のリスト。通常、Edge 管理 UI を使用して API プロキシを作成した場合にのみ、この要素が表示されます。これは、単に「マニフェスト」設定であって、API プロキシの内容を視認できるように設計されています。 なし ×

ProxyEndpoint

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

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

/apiproxy/proxies/default.xml

ProxyEndpoint 構成では、API プロキシのインバウンド(クライアントに対する)インターフェースが定義されます。ProxyEndpoint を構成するときに、プロキシされた API をクライアントアプリケーション(「apps」)が呼び出す方法を定義するネットワーク構成を設定します。

次の ProxyEndpoint 構成の例は、/apiproxy/proxies に格納されます。

    <ProxyEndpoint name="default">
      <PreFlow/>
      <Flows/>
      <PostFlow/>
      <HTTPProxyConnection>
        <BasePath>/weather</BasePath>
        <VirtualHost>default</VirtualHost>
      </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 Edge が使用する、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 はサポートされていません。"*" でベースパスを開始すると、Edge が有効なパスを識別するために予期しないエラーが発生する可能性があります。

/
VirtualHost

API プロキシを環境の特定のベース URL に関連付けます。VirtualHost は、ある環境に 1 つ以上の URL を定義する名前付きの構成です。

ProxyEndpoint のために定義され名前がつけられた VirtualHosts では、API プロキシが公開されているドメインとポートが定義されています。さらに、拡張機能により、アプリが API プロキシを呼び出すのに使用する URL が定義されています。

デフォルトでは、1 つの環境で defaultsecure の 2 つの名前付き VirtualHosts を定義しています。組織はカスタム ドメインを定義することもできます。たとえば HTTPS 経由でのみ API プロキシを使用できるようにするには、HTTPProxyConnection 内の VirtualHost の値を secure に設定します。

デフォルト
Properties オプションで一連の HTTP 構成設定を、<ProxyEndpoint> プロパティとして定義できます。 なし ×
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 /targets 下に格納されている可能性のある TargetEndpoint の構成をバイパスして、ProxyEndpoint によって呼び出されるアウトバウンド ネットワーク アドレスを定義するオプションの文字列 なし ×

RouteRules の構成方法

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

たとえば、次の 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 Edge の他の条件文と同様に機能します。条件リファレンス変数リファレンスをご覧ください。

たとえば、次の 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 サービスのキー / 値ストアを参照してデータを取得したりするなど、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 Edge から別のサービスやリソースへのアウトバウンド接続を定義します。

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

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

TargetEndpoint 構成要素

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

  • HTTP(S) 呼び出しのための HTTPTargetConnection
  • ローカル プロキシとプロキシ間の chaining のための LocalTargetConnection
  • Edge でホスティングされた Node.js スクリプト呼び出しのための ScriptTarget

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

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

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

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

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

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

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

なし ×
ScriptTarget
ResourceURL

リソースタイプ(ノード)と TargetEndpoint 機能を実装するメイン Node.js スクリプトの名前を定義します。

<ResourceURL>node://server.js</ResourceURL>

スクリプトは、API プロキシのリソース ファイルに含める必要があります。既存の API プロキシへの Node.js の追加をご覧ください。

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

なし
EnvironmentVariable

オプションで、環境変数をメインの Node.js スクリプトに渡します。

Node.js モジュールの Edge サポートについてをご覧ください。

なし ×
Arguments

オプションで、引数をメインの Node.js スクリプトに渡します。

Node.js モジュールの Edge サポートについてをご覧ください。

なし ×

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>
    

手順の詳細については、Edge からバックエンドへの TLS の構成(Cloud、Private Cloud)をご覧ください。

フロー変数を使用して TLS / SSL 値を動的に設定する

TLS / SSL の詳細を動的に設定して、ランタイム要件を柔軟にサポートすることもできます。たとえば、プロキシが潜在的に異なる 2 つのターゲット(テスト ターゲットと本番環境ターゲット)に接続する場合、API プロキシがプログラムによって呼び出し元の環境を検出し、適切なキーストアとトラストストアへの参照を動的に設定できます。次の Apigee Community の記事(https://community.apigee.com/articles/21424/dynamic-sslinfo-for-targetendpoint-using-variable.html)では、このシナリオについて詳しく説明し、デプロイ可能な API プロキシの例を示しています。

以下の <SSLInfo> タグが TargetEndpoint 構成で設定されている場合の例では、Java Callout、JavaScript ポリシー、Assign Message ポリシーなどの実行時に値を指定できます。設定する値を含むメッセージ変数を使用します。

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

    <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 証明書の有効期限が切れる場合や、システム構成の変更で証明書を更新しなければならなくなる場合を考慮する必要があります。Private Cloud 用 Edge のインストールでは、TLS / SSL を静的な値またはフロー変数を使用して構成する場合、メッセージ プロセッサを再起動する必要があります。

詳細については、TLS 証明書の更新をご覧ください。

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

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

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

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

    curl -X POST  -H "Content-Type:application/xml" https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/references \
    -d '<ResourceReference name="keystoreref">
        <Refers>myTestKeystore</Refers>
        <ResourceType>KeyStore</ResourceType>
    </ResourceReference>' -u email:password
    

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

次の GET API 呼び出しを使用して、参照を表示します。

    curl -X GET https://api.enterprise.apigee.com/v1/o/[org_name}/e/{env_name}/references/keystoreref -u uname:password
    

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

    curl -X PUT -H "Content-Type:application/xml" https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/references/keystoreref \
    -d '<ResourceReference name="keystoreref">
        <Refers>myNewKeystore</Refers>
        <ResourceType>KeyStore</ResourceType>
    </ResourceReference>' -u email:password
    

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

TargetEndpoints は、3 つの負荷分散アルゴリズムを使用して、複数の名前付き TargetServers 間の負荷分散をサポートします。

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

ポリシー

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

ポリシー構成要素

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

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

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

なし
enabled

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

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

true ×
continueOnError

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

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

false ×
async

: この属性では、ポリシーは非同期に実行されません。ほとんどの場合、これはデフォルトの false のままにしておきます。

true に設定すると、ポリシー実行は別のスレッドにオフロードされ、メインスレッドは自由に追加のリクエストを処理できます。オフライン処理が完了すると、メインスレッドが戻ってメッセージ フローの処理を終了します。場合によっては、async を 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 で Message Logging を使用する方法を紹介する短い動画をご覧ください。

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 Edge によって適用されます。条件付きフローは上から下に実行されます。条件が true と評価される最初の条件付きフローが実行され、1 つの条件付きフローのみが実行されます。

たとえば、次のフロー構成では、パス拡張子 /first/second が含まれないあらゆるインバウンド リクエストで Return404 というポリシーを適用して ThirdFlow を実行させます。

    <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 変換です。これらは、管理 UI の API プロキシ エディタの「スクリプト」セクションに表示されます。

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

リソースは、API プロキシ、環境、組織のいずれかに格納できます。いずれの場合も、リソースは名前でポリシーから参照されます。API サービスは、API プロキシから環境、組織レベルに移動して名前を決定します。

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