シンプルな API プロキシの構築

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

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

Apigee を使用すると、バックエンドサービスを API として迅速に公開できます。そのためには、公開するバックエンドサービスのファサードを提供する API プロキシを作成します。デベロッパーに公開する API プロキシを作成するには、バックエンドサービスのネットワークアドレスと Apigee が使用する情報のみを指定する必要があります。

API プロキシは、デベロッパーが利用する API からバックエンドサービスの実装を分離します。これにより、今後バックエンドサービスに変更があってもデベロッパーには意識されません。バックエンドサービスが更新されても、デベロッパーはこうした変更の影響を受けないため、中断されずに API の呼び出しを利用し続けることができます。

このトピックでは、さまざまなタイプのプロキシとその設定について説明します。プロキシの作成手順については、次のトピックをご覧ください。

チュートリアル: 最初の API プロキシを構築する
API プロキシの作成

UI を使用して API プロキシを作成する

API プロキシを作成する最も簡単な方法は、[Create Proxy] ウィザードを使用することです。

Apigee UI を使用して [Create Proxy] ウィザードにアクセスするには、次の手順を行います。

Apigee UI にログインします。
ナビゲーションバーで、[Develop] > [API Proxies] を選択します。
[CREATE NEW] をクリックします。

[Create Proxy] ウィザードが表示され、API プロキシを生成し、最小限の機能を追加する手順が示されます。

[Create Proxy] ウィザードの最初のページ。リバースプロキシ、ターゲットなし、プロキシバンドルを選択してウィザードのフローをカスタマイズする。

ウィザードの最初のページで、以下のソースから API プロキシを作成できます。

種類	説明
Reverse proxy (most common)	受信リクエストを既存の HTTP バックエンドサービスに転送する API プロキシ。JSON API または XML API を使用できます。このセクションで後述する HTTP サービス用のリバースプロキシを作成するをご覧ください。有効な OpenAPI 仕様からプロキシを生成するには、[Use OpenAPI Spec] をクリックします。このオプションの詳細については、このセクションで後述する OpenAPI 仕様を使用してプロキシを生成するをご覧ください。
No target	API バックエンドがない（「ターゲットなし」）API プロキシ。API プロキシの詳細を定義するときに既存の API を指定しない点を除き、前述の HTTP サービス用のリバースプロキシを作成すると同様です。有効な OpenAPI 仕様からプロキシを生成するには、[Use OpenAPI Spec] をクリックします。このオプションの詳細については、このセクションで後述する OpenAPI 仕様を使用してプロキシを生成するをご覧ください。
Upload proxy bundle	既存の API プロキシバンドル（たとえば、GitHub で入手可能なサンプル API プロキシのいずれか）。API プロキシバンドルから API プロキシをインポートするをご覧ください。

種類

説明

Reverse proxy (most common)

受信リクエストを既存の HTTP バックエンドサービスに転送する API プロキシ。JSON API または XML API を使用できます。このセクションで後述する HTTP サービス用のリバースプロキシを作成するをご覧ください。

有効な OpenAPI 仕様からプロキシを生成するには、[Use OpenAPI Spec] をクリックします。このオプションの詳細については、このセクションで後述する OpenAPI 仕様を使用してプロキシを生成するをご覧ください。

No target

API バックエンドがない（「ターゲットなし」）API プロキシ。API プロキシの詳細を定義するときに既存の API を指定しない点を除き、前述の HTTP サービス用のリバースプロキシを作成すると同様です。

Upload proxy bundle

既存の API プロキシバンドル（たとえば、GitHub で入手可能なサンプル API プロキシのいずれか）。API プロキシバンドルから API プロキシをインポートするをご覧ください。

以降のセクションでは、各プロキシタイプについて詳しく説明します。

HTTP サービス用のリバースプロキシを作成する

Apigee は、次の情報に基づいてリバースプロキシを生成します。

バックエンドサービスの URL
API プロキシによってユーザーアプリに公開される API を一意に識別する URI パス

通常、バックエンドサービス URL は、サービスに対応したアプリケーションを表し、お客様の組織が所有します。一般公開された API を指すこともあります。この API やサービスは、お客様の管理下に置くことも（内部の HR アプリケーション、Cloud の Rails アプリケーションなど）、サードパーティの API やサービス（Twitter や Instagram など）にすることもできます。

次のプロキシの詳細は、[Create Proxy] ウィザードにアクセスして、プロキシのタイプを選択すると表示されます。

項目	説明
Name	API に表示される名前。英数字、ハイフン（-）、アンダースコア（_）で指定します。
Base path	API プロキシの「`http://[host]`」アドレスや「`https://[host]`」アドレスの後に現われる URI の一部分。Apigee は、ベースパス URI を使用して受信リクエストメッセージを照合し、適切な API プロキシに転送します。注: API プロキシのベースパスのデフォルトの値は、`Name` フィールドに指定された値をすべて小文字に変換したものです。ベースパスには、任意の追加のリソース URL が続きます。クライアントが API プロキシを呼び出すために使用する完全な URL 構造は次のとおりです。 `https://[host]/BASE_PATH/CONDITIONAL_FLOW_PATH` 注: ベースパスは一意にする必要があります。同じベースパスを持つ 2 つの API プロキシをデプロイすることはできません。デプロイされた API プロキシを編集して、そのベースパスを別の API プロキシのベースパスと同じ値に設定すると、Apigee は保存時に API プロキシを自動的にデプロイ解除します。API プロキシを再デプロイするには、ベースパスが一意になるように編集しておく必要があります。ベースパスでワイルドカードを使用する将来の変化にも柔軟な API プロキシにするために、API プロキシのベースパスに 1 つ以上の「`//`」ワイルドカードを使用できます。たとえば、ベースパスを `/team//members` としておけば、クライアントは `https://[host]/team/blue/members` や `https://[host]/team/green/members` を呼び出せるため、新しいチームに対応する API プロキシをわざわざ新しく作成せずに済みます。`/**/` はサポートされていないことに注意してください。
Description	（省略可）API の説明。
Target (Existing API)	この API プロキシが呼び出すバックエンドサービスの URL。

API プロキシバンドルから API プロキシをインポートする

多くの場合、API プロキシは、他のサポートファイルとともに XML ファイルの集合として定義します。API プロキシを、Apigee の外部にある一連のファイルとして定義することで、それらをソース管理システムで維持し、Apigee へはテストとデプロイのためにインポートすることが可能になります。

API プロキシバンドルから API プロキシをインポートするには、次の手順を行います。

このセクションで前述した UI を使用して API プロキシを作成するの手順で、[Create Proxy] ウィザードにアクセスします。
[Upload proxy bundle] をクリックします。

プロキシウィザードの [Upload proxy bundle] ページで、次の情報を入力します。

項目	説明
ZIP bundle	API プロキシ構成を含む ZIP ファイル。ファイルをドラッグ＆ドロップするか、クリックしてファイルに移動します。
Name	API に表示される名前。デフォルトは、拡張子のない ZIP ファイルの名前です。

[Next] をクリックします。
[Summary] ページで、必要に応じてデプロイ環境を選択し、[Create and deploy] をクリックします。

新しい API プロキシが正常に作成されたことを示す確認応答が表示されます。
[Edit proxy] をクリックして、API プロキシの詳細ページを表示します。

gRPC API プロキシを作成する

Apigee では REST API プロキシに加えて gRPC API プロキシがサポートされていますが、gRPC API については現在のところパススルーのみに対応しています。パススルーサポートでは、gRPC のペイロード自体が Apigee にとって不透明であり、トラフィックが gRPC クライアントからターゲット構成で事前に構成された gRPC ターゲットサーバーにルーティングされます。

現在のところ、Apigee の gRPC API プロキシには次の特徴があります。

単項 gRPC リクエストをサポートする。
ペイロードに影響するポリシーは使用できない。
GraphQL または REST プロキシに関連付けられていない API プロダクトで使用できる。API プロダクト固有の割り当てとその他のオペレーション設定は、プロダクト内のすべてのプロキシに適用される。
Apigee ハイブリッドではサポートされていない。
gRPC 固有の 2 つのフロー変数（request.grpc.rpc.name と request.grpc.service.name）を使用する。
gRPC 固有の Apigee Analytics 変数（x_apigee_grpc_rpc_name、x_apigee_grpc_service_name、x_apigee_grpc_status）を使用してモニタリングできる。
gRPC ステータスコードを返す。

また、ロードバランサが gRPC をサポートするように構成する必要があります。アプリケーションでの gRPC の使用に関する記事と gcloud CLI コマンドを使用して gRPC のルーティングを作成するをご覧ください。

gRPC API プロキシを作成するには、まず gRPC ターゲットサーバーを定義し（TargetServer の作成を参照）、新しいプロキシを作成するときにそのターゲットサーバーを指定します。

gcloud CLI コマンドを使用して gRPC のルーティングを作成する

このセクションでは、gcloud CLI を使用して gRPC プロキシのルーティングを作成するコマンドの例を紹介します。この手順には、ロードバランサ、ターゲットサーバー、MIG の設定が含まれます。

このセクションは、ルーティングの作成に関する包括的なガイドではありません。これらの例は、すべてのユースケースに適しているとは限りません。また、以下の手順は、外部ルーティング（MIG）と Cloud ロードバランサの gRPC 構成を理解していることを前提としています。

環境変数を設定する

これらの環境変数は、サブセクションのコマンドで使用されます。

PROJECT_ID=YOUR_PROJECT_ID
MIG_NAME=YOUR_MIG_NAME
VPC_NAME=default
VPC_SUBNET=default
REGION=REGION_NAME
APIGEE_ENDPOINT=ENDPOINT
CERTIFICATE_NAME=CERTIFICATE_NAME
DOMAIN_HOSTNAME=DOMAIN_HOSTNAME

新しいロードバランサを使用して gRPC プロキシのルーティングを作成する gcloud CLI コマンドの例

このセクションでは、gcloud CLI と新しいロードバランサを使用して gRPC プロキシを作成するコマンドの例を紹介します。この手順には、ロードバランサ、ターゲットサーバー、MIG の設定が含まれます。

インスタンステンプレートを作成する

gcloud compute instance-templates create $MIG_NAME \
--project $PROJECT_ID \
--region $REGION \
--network $VPC_NAME \
--subnet $VPC_SUBNET \
--tags=https-server,apigee-mig-proxy,gke-apigee-proxy \
--machine-type e2-medium --image-family debian-12 \
--image-project debian-cloud --boot-disk-size 20GB \
--no-address \
--metadata ENDPOINT=$APIGEE_ENDPOINT,startup-script-url=gs://apigee-5g-saas/apigee-envoy-proxy-release/latest/conf/startup-script.sh

マネージドインスタンスグループを作成する

gcloud compute instance-groups managed create $MIG_NAME \
--project $PROJECT_ID --base-instance-name apigee-mig \
--size 2 --template $MIG_NAME --region $REGION

自動スケーリングを構成する

gcloud compute instance-groups managed set-autoscaling $MIG_NAME \
--project $PROJECT_ID --region $REGION --max-num-replicas 50 \
--target-cpu-utilization 0.75 --cool-down-period 90

名前付きポートを定義する

gcloud compute instance-groups managed set-named-ports $MIG_NAME \
--project $PROJECT_ID --region $REGION --named-ports https:443

ロードバランサの Google マネージド SSL 証明書と鍵を作成する

gcloud compute ssl-certificates create $CERTIFICATE_NAME \
--domains=$DOMAIN_HOSTNAME \
--project $PROJECT_ID \
--global

証明書がプロビジョニングされていることを確認する

gcloud compute ssl-certificates describe $CERTIFICATE_NAME \
--global \
--format="get(name,managed.status, managed.Status)"

グローバル Cloud ロードバランサ（GCLB）を作成する

ヘルスチェックの作成

gcloud compute health-checks create https hc-apigee-envoy-443 \
--project $PROJECT_ID --port 443 --global \
--request-path /healthz/ingress

http1 用のバックエンドサービスの作成

gcloud compute backend-services create YOUR_BACKEND_1 \
--project $PROJECT_ID \
--protocol HTTPS \
--health-checks hc-apigee-envoy-443 \
--port-name https \
--timeout 302s \
--connection-draining-timeout 300s \
--global

http2 用のバックエンドサービスの作成

gcloud compute backend-services create YOUR_BACKEND_2 \
--project $PROJECT_ID \
--protocol HTTP2 \
--health-checks hc-apigee-envoy-443 \
--port-name https \
--timeout 302s \
--connection-draining-timeout 300s \
--global

バックエンドサービスに MIG を追加します。この例では MIG を再利用していますが、MIG の新しいペアを作成することもできます。

gcloud compute backend-services add-backend YOUR_BACKEND_1 \
--project $PROJECT_ID --instance-group $MIG_NAME \
--instance-group-region $REGION \
--balancing-mode UTILIZATION --max-utilization 0.8 --global

gcloud compute backend-services add-backend YOUR_BACKEND_2 \
--project $PROJECT_ID --instance-group $MIG_NAME \
--instance-group-region $REGION \
--balancing-mode UTILIZATION --max-utilization 0.8 --global

ロードバランシングの URL マップを作成します。まず、URL マップがすでに存在するかどうかを確認します。すでに存在する場合は、上書きするのではなく、以下の要件に従ってマップを修正してください。

この構成で YAML ファイルを作成するか、/tmp/apigee-map.yaml にある既存のファイルを使用します。デフォルトは URL マップの http1 バックエンドです。
```
defaultService: projects/$PROJECT_ID/global/backendServices/YOUR_BACKEND_1
name: matcher1
routeRules:
- matchRules:
- headerMatches:
- headerName: Content-Type
prefixMatch: application/grpc
prefixMatch: /
priority: 100
routeAction:
weightedBackendServices:
- backendService: projects/$PROJECT_ID/global/backendServices/YOUR_BACKEND_2
weight: 100
```
URL マップを検証します。
```
gcloud compute url-maps validate --source /tmp/apigee-map.yaml --project $PROJECT_ID
```
ヘッダーベースのルーティングを使用して URL マップを作成します。
```
gcloud compute url-maps import apigee-http1-http2 \
--source /tmp/apigee-map.yaml  \
--global --project $PROJECT_ID
```

ロードバランシングのターゲット HTTPS プロキシを作成する

gcloud compute target-https-proxies create apigee-envoy-https-proxy \
--project $PROJECT_ID --url-map apigee-envoy-proxy-map \
--ssl-certificates $CERTIFICATE_NAME

IPv4 外部 IP を予約してロードバランサのファイアウォールルールを作成する

gcloud compute addresses create lb-ipv4-vip-1 \
--project $PROJECT_ID \
--network-tier=PREMIUM \
--ip-version=IPV4 \
--global

  gcloud compute addresses describe lb-ipv4-vip-1 \
--project $PROJECT_ID --format="get(address)" --global

  gcloud compute forwarding-rules create apigee-envoy-https-lb-rule \
--project $PROJECT_ID --address lb-ipv4-vip-1 --global \
--target-https-proxy apigee-envoy-https-proxy --ports 443

ファイアウォールルールを作成する

gcloud compute firewall-rules create k8s-allow-lb-to-apigee-envoy \
--description "Allow incoming from GLB on TCP port 443 to Apigee Proxy" \
--project $PROJECT_ID --network $VPC_NAME --allow=tcp:443 \
--source-ranges=130.211.0.0/22,35.191.0.0/16 --target-tags=gke-apigee-proxy

既存のロードバランサの gRPC プロキシのルーティングを作成する gcloud CLI コマンドの例

このセクションでは、gcloud CLI と既存のロードバランサを使用して gRPC プロキシを作成するコマンドの例を紹介します。この手順には、ロードバランサ、ターゲットサーバー、MIG の設定が含まれます。

http2 用の別のバックエンドサービスを作成する

# Create backend service for http2
    gcloud compute backend-services create YOUR_BACKEND_2 \
--project $PROJECT_ID \
--protocol HTTP2 \
--health-checks hc-apigee-envoy-443 \
--port-name https \
--timeout 302s \
--connection-draining-timeout 300s \
--global

2 番目のバックエンドサービスを MIG に接続する

gcloud compute backend-services add-backend YOUR_BACKEND_2 \
--project $PROJECT_ID --instance-group $MIG_NAME \
--instance-group-region $REGION \
--balancing-mode UTILIZATION --max-utilization 0.8 --global

既存の Apigee GCLB の URL マップを一覧表示する

gcloud compute url-maps list -project $PROJECT_ID

Apigee ロードバランシングに使用される正しい URL マップ名を取得する

gcloud compute url-maps export APIGEE_URL_MAP_NAME -project $PROJECT_ID

ロードバランシング URL マップの YAML ファイルを作成する

既存の URL マップがすでにある場合は、この設定をその URL マップに統合します。ない場合は、この構成を使用して /tmp/apigee-map.yaml に YAML ファイルを作成します。

defaultService: projects/dg-runtime-test1/global/backendServices/YOUR_BACKEND_1
name: matcher1
routeRules:
- matchRules:
- headerMatches:
- headerName: Content-Type
prefixMatch: application/grpc
prefixMatch: /
priority: 100
routeAction:
weightedBackendServices:
- backendService: projects/dg-runtime-test1/global/backendServices/YOUR_BACKEND_2
weight: 100

gRPC ルーティングに新しい YAML を適用する

gcloud compute url-maps import APIGEE_URL_MAP_NAME\
--source /tmp/apigee-map.yaml  \
--global -project $PROJECT_ID

セキュリティを追加する

[Create Proxy] ウィザードの [Common policies] ページで、追加するセキュリティ認可のタイプを選択します。次の表では、選択可能なタイプの要約を示します。

セキュリティ認可	説明
API キー	定義中の API プロキシに、単純な API キー検証を追加します。これに伴い、API Platform では、API プロキシに VerifyAPIKey ポリシーと AssignMessage ポリシーが追加されます。VerifyAPIKey ポリシーは、リクエスト側のアプリが提示する API キーを検証します。AssignMessage ポリシーは、バックエンドサーバーに転送されたリクエストから API キー（API 呼び出しでクエリパラメータとして指定されます）を削除します。
OAuth 2.0	API プロキシに OAuth 2.0 ベースの認可を追加します。API プロキシに、次のポリシーが Apigee によって自動的に追加されます。1 つはアクセストークンを検証するポリシー、もう 1 つはバックエンドサービスに転送する前にメッセージからアクセストークンを削除するポリシーです。アクセストークンの取得方法については、OAuth をご覧ください。
パススルー（認可なし）	認可は必要ありません。Apigee でセキュリティチェックを行うことなく、リクエストがバックエンドに渡されます。

CORS のサポートを追加する

クロスオリジンリソースシェアリング（CORS）は、ウェブブラウザが別のドメインにリクエストを直接発行できるようにする標準メカニズムです。CORS 標準では、クロスドメイン通信を実装するために、ウェブブラウザとサーバーが使用する一連の HTTP ヘッダーが定義されています。

CORS のサポートは、次のいずれかの方法で追加できます。

CORS ポリシーを ProxyEndpoint のリクエスト PreFlow に追加する
[Create Proxy] ウィザードの [Common policies] ページで [Add CORS headers] を選択する

プロキシへの CORS プリフライトサポートの追加など、CORS サポートの詳細については、API プロキシへの CORS サポートの追加をご覧ください。

割り当てを追加する

バックエンドサービスは、割り当ての設定によって、高トラフィックから保護されます。割り当てをご覧ください（認可がパススルーに選択されている場合は利用できません）。

OpenAPI 仕様を使用してプロキシを生成する

このセクションでは、OpenAPI 仕様から API プロキシ（リバースまたはターゲットなしのタイプ）を生成するために使用できる [Use OpenAPI Spec] オプションについて説明します。

OpenAPI 仕様とは

Open API Initiative のロゴ「Open API Initiative（OAI）は、Swagger 仕様に基づいた、ベンダーに依存しない API 記述形式の作成、発展、促進に注力しています」詳しくは、OpenAPI Initiative をご覧ください。

OpenAPI 仕様では、標準形式を使用して RESTful API を記述します。JSON 形式または YAML 形式で記述された OpenAPI 仕様は、機械可読でありながら、人間も簡単に読んで理解できます。この仕様では、ベースパス、パスと動詞、ヘッダー、クエリパラメータ、オペレーション、コンテンツタイプ、レスポンス記述などの API 要素を記述します。また、OpenAPI 仕様は API ドキュメントの生成にもよく使用されます。

次の OpenAPI 仕様からの抜粋は、Apigee の疑似的なターゲットサービス（http://mocktarget.apigee.net）を記述したものです。詳細については、OpenAPI 仕様の helloworld サンプルをご覧ください。

openapi: 3.0.0
info:
  description: OpenAPI Specification for the Apigee mock target service endpoint.
  version: 1.0.0
  title: Mock Target API
paths:
  /:
    get:
      summary: View personalized greeting
      operationId: View a personalized greeting
      description: View a personalized greeting for the specified or guest user.
      parameters:
        - name: user
          in: query
          description: Your user name.
          required: false
          schema:
            type: string
      responses:
        "200":
          description: Success
  /help:
    get:
      summary: Get help
      operationId: Get help
      description: View help information about available resources in HTML format.
      responses:
        "200":
          description: Success
...

OpenAPI 仕様は、[Create Proxy] ウィザードを使用してインポートし、それを使って API プロキシを生成できます。プロキシが生成されたら、他の Apigee プロキシと同様に、ポリシーの追加、カスタムコードの実装など、Apigee UI を使用してさらに開発できます。

OpenAPI 仕様からの API プロキシの作成

OpenAPI 仕様から API プロキシを作成します。数回クリックするだけで、パス、パラメータ、条件付きフロー、ターゲットエンドポイントがある API プロキシが自動的に作成されます。その後、OAuth セキュリティ、レート制限、キャッシュ保存などの機能を追加できます。

[Create Proxy] ウィザードで [Use OpenAPI Spec] をクリックし、ウィザードに従って、OpenAPI 仕様からリバースプロキシまたは非ターゲットプロキシを作成します。詳細については、OpenAPI 仕様からの API プロキシの作成をご覧ください。

API プロキシの新しいリビジョンの作成

以下の説明に従って、API プロキシの新しいリビジョンを作成します。

API プロキシの新しいリビジョンを作成するには、次の手順を行います。

Apigee UI にログインします。
ナビゲーションバーで、[Develop] > [API Proxies] を選択します。
リスト内のコピーする API プロキシをクリックします。
[DEVELOP] タブをクリックします。
[Save] ボタンをクリックし、[Save as New Revision] を選択します。

API プロキシをバックアップする

既存の API プロキシは、API プロキシバンドルの一連の XML ファイルとしてバックアップできます。このセクションの API プロキシバンドルから API プロキシをインポートするで説明したとおり、バンドルにエクスポートすると、API プロキシを新しいプロキシに読み込むことができます。詳細については、API プロキシをダウンロードするをご覧ください。

API を使用して API プロキシを作成する

API を使用して API プロキシを作成するには、API プロキシの作成をご覧ください。