構成可能なプロキシの構成例

このページは Apigee と Apigee ハイブリッドに適用されます。

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

構成可能な API プロキシ^{プレビュー}のスキーマには、プロキシに機能を追加するためのさまざまなオプションがあります。以降のセクションでは、一般的なユースケースをサポートするために使用されるプロキシ構成の例を示します。構成オプションの詳細については、ApiConfig スキーマのリファレンスページをご覧ください。ApiConfig スキーマは、構成可能なプロキシを定義する YAML ファイルを構造化するために使用されます。

構成可能な API プロキシ^{プレビュー}の開発は、Apigee 有料サブスクリプションの組織を使用しているお客様のみが行えます。従量課金制の組織を使用している Apigee のお客様は、プログラム可能な API プロキシを作成できます。

パススループロキシ

構成可能な API プロキシ^{プレビュー}の最も単純な構成モデルは、パススループロキシ構成です。この構成では、プロキシは basePath でトラフィックを受信し、情報をバックエンドターゲットにルーティングします。

次に例を示します。

#config.yaml
basepath: "/helloworld"

target:
  uri: https://mocktarget.apigee.net

この例では、構成の最初の行にベースパスが含まれています。これは必須のパラメータです。

構成のルールのセクションには、すべての受信リクエストをルーティングするターゲットエンドポイントが含まれています。このプロキシバンドルの例では、セキュリティ情報や追加のエンドポイントへのルーティングに関する情報を適用しません。

注: 上の構成は説明のみを目的としています。オペレーションが含まれていないプロキシでは 404 エラーコードが返されます。詳細については、Apigee の既知の問題をご覧ください。

オペレーションが含まれるプロキシ

この構成例ではオペレーション（メソッドとパスの組み合わせ）が宣言されています。API プロキシのデベロッパーは、リクエストされたオペレーションに基づいてさまざまなアクションを実装したり、異なるポリシーを適用したりできます。

次に例を示します。

#config.yaml
basepath: "/helloworld"

target:
  uri: https://mocktarget.apigee.net

operations:  # First match wins
- id: help
  http_match:
  - path_template: "/help"
    method: GET
- id: status
  http_match:
  - path_template: "/status/*" # A single "*" matches a single path segment
    method: GET

この構成例の operations セクションは、プログラム可能なプロキシバンドルのフロー条件のように機能します。フロー条件の使用方法については、条件付きフローによるコードの条件付き実行をご覧ください。

セキュリティが適用されるプロキシ

API セキュリティの重要な部分は、API へのアクセスの制御、暗号化された機密データへのアクセスと実行時のマスキング、バックエンドサービスへの直接アクセスからの保護です。構成可能な API プロキシ^{プレビュー}では、次の例のように、いくつかのセキュリティ適用オプションを実装できます。

API キー検証を有効にする

この構成例では、公開されているすべてのオペレーションに対して API キー検証が有効になります。API キー検証を適用するルールは consumer_authorization です。この構成ルールは、所定の場所に API キーが存在するかを確認します。キーが存在する場合は、その API キーの有効性と、その API キーが API にアクセスできるかどうか（つまり、API プロキシにアクセスできる API プロダクトに登録しているかどうか）を確認します。

次に例を示します。

#config.yaml
basepath: "/helloworld"

operations:
- id: help
  http_match:
  - path_template: "/help"
    method: GET
- id: status
  http_match:
  - path_template: "/status/*"
    method: GET

target:
  uri: https://mocktarget.apigee.net

consumer_authorization:  # API Key enforcement
  locations:
  - header: x-api-key

consumer_authorization ルールはプロキシのグローバルセクションにあるため、プロキシバンドル内のすべてのオペレーションに適用されます。

OAuth を有効にする

構成可能な API プロキシ^{プレビュー}での OAuth の有効化には、次の 2 つの側面があります。

OAuth アクセストークンの取得
API へのアクセスの検証 / 付与

以降のセクションで、それぞれの側面について説明します。

OAuth アクセストークンを取得する

構成可能なプロキシの OAuth アクセストークンを取得するプロセスは、プログラム可能なプロキシの場合と同じです。プログラム可能な API プロキシバンドルを使用して、OAuth アクセストークンを取得します。OAuth2 ポリシーの構成に必要な手順の例については、アクセストークンと認可コードのリクエストをご覧ください。

API へのアクセスの検証と承認

Apigee で OAuth アクセストークンを検証して承認するには、次の手順を実行します。

JWT 認証の要件を定義します。このセクションでは、プロキシが JWT トークンを検証する方法を定義します。

次に例を示します。

#config.yaml
authentication:
  jwt:
    id: apigee_oauth
    audiences: ["developer-app1"]
    issuer: "SERVICE_ACCOUNT_EMAIL"
    remote_jwks:
      uri: "https://www.googleapis.com/service_accounts/v1/jwk/serviceaccount"
      cache_duration: 600s
    locations:
    - header: Authorization
      transformation:
        template: "Bearer {token}"
        substitution: "{token}"

target:
  uri: https://mocktarget.apigee.net

consumer_authorization:
  locations:
  - jwt_claim:
      requirement: apigee_oauth
      name: client_id

API へのアクセスに使用する Apigee クライアント ID の場所を定義します。これは通常、Apigee がデベロッパーアプリケーションによる API プロダクトへのアクセスを承認するために使用する認証情報を含む JWT クレームです。

次に例を示します。

#config.yaml
authentication:
  jwt:
    id: apigee_oauth
    audiences: ["developer-app1"]
    issuer: "SERVICE_ACCOUNT_EMAIL"
    remote_jwks:
      uri: "https://www.googleapis.com/service_accounts/v1/jwk/serviceaccount"
      cache_duration: 600s
    locations:
    - header: Authorization
      transformation:
        template: "Bearer {token}"
        substitution: "{token}"

target:
  uri: https://mocktarget.apigee.net

consumer_authorization:
  locations:
  - jwt_claim:
      requirement: apigee_oauth
      name: client_id

API アクセスの検証と承認をまとめた構成は次のようになります。

#config.yaml
authentication:
  jwt:
      id: apigee_oauth
      audiences: ["developer-app1"]
      issuer: "SERVICE_ACCOUNT_EMAIL"
      remote_jwks:
        uri: "https://www.googleapis.com/service_accounts/v1/jwk/serviceaccount"
        cache_duration: 600s
      locations:
      - header: Authorization
        transformation:
          template: "Bearer {token}"
          substitution: "{token}"

target:
  uri: https://mocktarget.apigee.net

consumer_authorization:
  locations:
  - jwt_claim:
      requirement: apigee_oauth
      name: client_id

このプロキシ構成により、ターゲットエンドポイントに対するすべてのリクエストに次の内容が含まれることが確認されます。

次の条件を満たす JWT。
- 一致する issuer と audiences がある
- JWKS URI のコンテンツによって検証される
- Authorization ヘッダーにある
クライアント認証情報は、apigee_oauth と一致する JWT クレーム client_id 内にあります。

CORS を有効にする

このプロキシ構成の例では、CORS を有効にするルールを定義します。CORS（クロスオリジンリソースシェアリング）は、ウェブページで実行される JavaScript XMLHttpRequest（XHR）呼び出しがオリジン以外のドメインのリソースとやり取りできるようにする標準的なメカニズムです。CORS は、すべてのブラウザに組み込まれている同一オリジンポリシーに対する一般的な解決策です。

次に例を示します。

#config.yaml
basepath: "/helloworld"

cors:
  allow_origins:
  - "*"
  allow_methods:
  - "GET"
  allow_headers:
  - "Accept"
  max_age: 600
  allow_credentials: false

operations:
- id: help
  http_match:
  - path_template: "/help"
    method: GET
- id: status
  http_match:
  - path_template: "/status/*"
    method: GET

target:
  uri: https://mocktarget.apigee.net

ターゲットサーバーの使用

構成可能なプロキシモデルは、Apigee のターゲットサーバーのコンセプトをサポートしています。ターゲットサーバーを使用すると、実際のエンドポイントをターゲットエンドポイントから分離して、複数のバックエンドサーバーインスタンスにわたるロードバランシングとフェイルオーバーをサポートできます。アーカイブデプロイでターゲットサーバーを使用するには、次の例のような config.yaml ファイルと targetservers.json ファイルを使用します。

#config.yaml
basepath: "/mock"

operations:
- id: user
  http_match:
  - path_template: "/user"
    method: "GET"

target:
  target_server_id: mocktarget

targetservers.json ファイルは次のように設定します。

[
    {
        "name": "mocktarget",
        "host": "mocktarget.apigee.net",
        "port": 443,
        "isEnabled" : true,
        "sSLInfo": {
            "enabled": true
        }
    }
]

オペレーションをターゲットにルーティングする

この構成プロキシモデルの例では、ユーザーは各オペレーションを異なるターゲットエンドポイントにルーティングできます。

次に例を示します。

#config.yaml
basepath: "/mockhttpbin"

operations:
- id: user
  http_match:
  - path_template: "/user"
    method: "GET"
  target:
    target_server_id: mocktarget
- id: ip
  http_match:
  - path_template: "/ip"
    method: "GET"
  target:
    uri: https://httpbin.org

構成可能なプロキシの構成例

パススルー プロキシ

オペレーションが含まれるプロキシ

セキュリティが適用されるプロキシ

API キー検証を有効にする

OAuth を有効にする

OAuth アクセス トークンを取得する

API へのアクセスの検証と承認

CORS を有効にする

ターゲット サーバーの使用

オペレーションをターゲットにルーティングする

パススループロキシ

OAuth アクセストークンを取得する

ターゲットサーバーの使用