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

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

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

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

• Edge UI 内で XML エディタを使用する
• 構成をダウンロードしてローカルで編集する（プロキシ構成のローカル開発をご覧ください）

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

プロキシ構成をダウンロードして、ローカルマシン上で編集できます。作業が終わったら、その結果を 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 プロキシ ディレクトリ構造とコンテンツ

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

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

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

• 基本構成
• ProxyEndpoint
• TargetEndpoint
  • TLS / SSL TargetEndpoint 構成
• ポリシー
• フロー
• リソース

基本構成

/apiproxy/weatherapi.xml

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

構成の例:

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

基本構成の要素

ProxyEndpoint

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

/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 構成要素

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 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 サービスの Key-Value ストアを参照してデータを取得したりするなど、ProxyEndpoint が必要な処理をすべて実行する場合に便利です。

たとえば、次のように 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

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 に構成します。

TLS / SSL TargetEndpoint 構成

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

TLS / SSL TargetEndpoint 構成要素

<Ciphers>
 <Cipher>TLS_RSA_WITH_3DES_EDE_CBC_SHA</Cipher>
 <Cipher>TLS_RSA_WITH_DES_CBC_SHA</Cipher>
</Ciphers>

<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 コミュニティ記事では、このシナリオについて詳細に説明されており、デプロイ可能な API プロキシの例が提供されています。https://community.apigee.com/articles/21424/dynamic-sslinfo-for-targetendpoint-using-variable.html

TargetEndpoint 構成で <SSLInfo> タグが設定される仕組みを示す次の例では、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 証明書の有効期限が切れる場合や、システム構成の変更で証明書を更新しなければならなくなる場合を考慮する必要があります。Edge for Private Cloud のインストールでは、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 プロキシのフローに追加できるすべてのポリシーが含まれています。

ポリシー構成要素

ポリシーの接続

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

上記のフローの説明:

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

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

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

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

ポリシー接続ファイルの構成要素

フロー

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

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

さらに、ProxyEndpoint に PostClientFlow を追加できます。ProxyEndpoint は、レスポンスがリクエスト元のクライアント アプリに返された後に実行されます。MessageLogging ポリシーと Google Stackdriver Logging 拡張機能のみをこのフローに追加できます。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 プロキシ処理パイプラインは、次の順序でフローを実行します。

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

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>

フロー構成要素

ステップ処理

条件付きフローの順序づけは、Apigee Edge によって適用されます。条件付きフローは上から下に実行されます。条件が 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 変換です。これらは、管理 UI の API プロキシ エディタの「スクリプト」セクションに表示されます。

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

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

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