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

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

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

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

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

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

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

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

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

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

[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 プロキシをインポートするをご覧ください。

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

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 プロキシに転送します。

ベースパスには、任意の追加のリソース URL が続きます。クライアントが API プロキシを呼び出すために使用する完全な URL 構造は次のとおりです。

https://[host]/BASE_PATH/CONDITIONAL_FLOW_PATH

ベースパスでワイルドカードを使用する

将来の変化にも柔軟な API プロキシにするために、API プロキシのベースパスに 1 つ以上の「/*/」ワイルドカードを使用できます。たとえば、ベースパスを /team/*/members としておけば、クライアントは https://[host]/team/blue/membershttps://[host]/team/green/members を呼び出せるため、新しいチームに対応する API プロキシをわざわざ新しく作成せずに済みます。/**/ はサポートされていないことに注意してください。

Description (省略可)API の説明。
Target (Existing API) この API プロキシが呼び出すバックエンド サービスの URL。

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

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

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

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

    項目 説明
    ZIP bundle API プロキシ構成を含む ZIP ファイル。ファイルをドラッグ&ドロップするか、クリックしてファイルに移動します。
    Name API に表示される名前。デフォルトは、拡張子のない ZIP ファイルの名前です。
  4. [Next] をクリックします。
  5. [Summary] ページで、必要に応じてデプロイ環境を選択し、[Create and deploy] をクリックします。

    新しい API プロキシが正常に作成されたことを示す確認応答が表示されます。

  6. [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.namerequest.grpc.service.name)を使用する。
  • gRPC 固有の Apigee Analytics 変数x_apigee_grpc_rpc_namex_apigee_grpc_service_namex_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

セキュリティを追加する

[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 プロキシの新しいリビジョンを作成するには、次の手順を行います。

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

  5. [Save] ボタンをクリックし、[Save as New Revision] を選択します。

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

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

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

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