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

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

API プロキシは、バックエンドサービス実装とデベロッパーが使用する API とを分離します。これにより、バックエンドサービスに対する今後の変更がデベロッパーから隠されます。バックエンドサービスを更新しても、そうした変更はデベロッパーから隠されているため、API の呼び出しが中断されることはありません。

API プロキシの作成過程の概要を説明する動画をご覧ください。

UI を使用した API プロキシの作成

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

Edge

Edge UI を使用して [Create Proxy] ウィザードにアクセスするには:

apigee.com/edge にログインします。
左側のナビゲーションバーで [Develop] > [API Proxies] を選択します。
[+Proxy] をクリックします。

[Create Proxy] ウィザードが表示されます。このウィザードに従って API プロキシを生成し、その API プロキシに最小限の機能を追加します。

[Create Proxy] ウィザードの最初のページ。[Reverse proxy]、[SOAP service]、[No Target]、または [Proxy bundle] を選択します。選択した項目により、ウィザードフローが変わります。

Classic Edge（Private Cloud）

Classic Edge UI を使用して Create Proxy ウィザードにアクセスするには:

http://ms-ip:9000 にログインします。ここで、ms-ip は、Management Server ノードの IP アドレスまたは DNS 名です。
上部のナビゲーションバーで [APIs] > [API Proxies] を選択します。
[+ API Proxy] をクリックします。

[Create Proxy] ウィザードが表示されます。このウィザードに従って API プロキシを生成し、その API プロキシに最小限の機能を追加します。

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

タイプ	説明
Reverse proxy (most common)	受信リクエストを既存の HTTP バックエンドサービスにルーティングする API プロキシ。JSON API または XML API となります。このセクションで後述する HTTP サービス用のリバースプロキシの作成をご覧ください。 [Use OpenAPI Spec] をクリックして、有効な OpenAPI 仕様からプロキシを生成します。このオプションについて詳しくは、このセクションで後述する OpenAPI 仕様を使用したプロキシの生成をご覧ください。
SOAP service	WSDL ファイルから生成された API プロキシ。SOAP ベースのウェブサービスの API プロキシとしての公開をご覧ください。
No Target	API バックエンドなし（「ターゲットなし」）の API プロキシ。前述の HTTP サービス用のリバースプロキシの作成と同様ですが、API プロキシの詳細を定義するときに既存の API を指定しません。 [Use OpenAPI Spec] をクリックして、有効な OpenAPI 仕様からプロキシを生成します。このオプションについて詳しくは、このセクションで後述する OpenAPI 仕様を使用したプロキシの生成をご覧ください。
Hosted Target	Hosted Targets 環境にデプロイされた Node.js アプリケーションにルーティングする API プロキシ。Hosted Targets の概要をご覧ください。
Upload proxy bundle	既存の API プロキシバンドル（たとえば GitHub に用意されているサンプル API プロキシのいずれか）。API プロキシバンドルからの API プロキシの読み込みをご覧ください。

以降では、各ソースを使用して API プロキシを作成する方法を説明します。

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

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

バックエンドサービスの URL
API プロキシによってコンシューマアプリに公開されることになる API を一意に指定する URI パス

バックエンドサービス URL は、通常、組織が所有するサービス対応アプリケーションを表します。また、一般公開される API を参照することもあります。API またはサービスがご自分の管理下にあるもの（内部 HR アプリケーション、Cloud にある Rails アプリケーションなど）か、サードパーティの API またはサービス（Twitter や Instagram など）かは問いません。

Edge

このセクションの UI を使用した API プロキシの作成で説明したように、[Create Proxy] ウィザードにアクセスします。
[Create Proxy] ウィザードで、[Reverse proxy (most common)] をクリックします。既存の有効な OpenAPI 仕様からプロキシを生成するには、[Use OpenAPI] をクリックします。このオプションについて詳しくは、後述の OpenAPI 仕様を使用したプロキシの生成をご覧ください。

ウィザードの [Details] ページで、次の情報を入力します。

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

ウィザードの [Common policies] ページで、次のように構成します。
- Security: Authorization - セキュリティ承認要件。このセクションで後述するセキュリティの追加をご覧ください。
- Security: Browser - クロスオリジンリソースシェアリング（CORS）のサポート。このセクションで後述する CORS サポートの追加をご覧ください。
- Quota - バックエンドサービスを高トラフィックから保護するための割り当て。割り当てをご覧ください（パススルー認可が選択されている場合は使用できません）。
- Monetization - 収益化を有効にしている組織での収益化制限の適用。API プロキシに収益化制限を適用するをご覧ください。
ウィザードの [Virtual hosts] ページで、API プロキシがデプロイされるときにバインドする仮想ホストを選択します。詳しくは、仮想ホストについてをご覧ください。
[Summary] ページで、必要に応じてデプロイ環境を選択し、[Create and deploy] をクリックします。
新しい API プロキシが作成され、選択した環境にデプロイされます。
[Edit proxy] をクリックして、API プロキシの詳細ページを表示します。

Classic Edge（Private Cloud）

このセクションの UI を使用した API プロキシの作成で説明したように、[Create Proxy] ウィザードにアクセスします。
[Build a Proxy] ウィザードで、[Reverse proxy (most common)] を選択します。既存の有効な OpenAPI 仕様からプロキシを生成するには、[Use OpenAPI] をクリックします。このオプションについて詳しくは、後述の OpenAPI 仕様を使用したプロキシの生成をご覧ください。
[Next] をクリックします。

ウィザードの [Details] ページで、次の情報を入力します。

フィールド	説明
Proxy Name	API に表示される名前。
Proxy Base Path	プロキシベースパスは、ユーザーの API プロキシの http(s)://[host] アドレスの後ろにある URI フラグメントです。Edge は、ベースパス URI を使って、受信リクエストメッセージの照合と正しい API プロキシへのルーティングを行います。注: API のバージョニングに関する Apigee の推奨事項については、電子ブック『Web API Design: The Missing Link』の Versioning をご覧ください。ベースパスの後ろには、追加のリソース URL があります。次に、クライアントが API プロキシを呼び出すために使用する完全な URL 構造を示します。 `https://[host]/base_path/conditional_flow_path` 注: ベースパスは一意である必要があります。このプロキシを後で編集し、そのベースパスを別の API プロキシと同じになるように設定した場合、この API プロキシは保存時に自動的にデプロイ解除されます。再デプロイする前にベースパスを編集する必要があります。ベースパスでのワイルドカードの使用プロキシを将来の変更に柔軟に対応させるために、API プロキシのベースパスで 1 つ以上の `//` ワイルドカードを使用できます。たとえば、ベースパスを `/team//members` にすると、新しいチームに対応するために新しい API プロキシを作成する必要なく、クライアントが `https://[host]/team/blue/members` と `https://[host]/team/green/members` を呼び出すことができます。/**/ はサポートされていないことに注意してください。注: プロキシベースパスは、[Proxy Base Path] フィールドのコンテンツを明示的に編集しない限り、[Proxy Name] に指定された値がすべて小文字に変換されたものになります。
Existing API	API プロキシ URL を介して API を呼び出すアプリに代わって API Platform が呼び出す URL。
Description	API の説明。

ウィザードの [Security] ページで、以下を構成します。
- セキュリティ認証要件。このセクションで後述するセキュリティの追加をご覧ください。
- クロスオリジンリソースシェアリング（CORS）のサポート。このセクションで後述する CORS サポートの追加をご覧ください。
ウィザードの [Virtual Hosts] ページで、API プロキシがデプロイされるときにバインドする仮想ホストを選択します。詳しくは、仮想ホストについてをご覧ください。
デプロイ環境を選択し、[Build and Deploy] をクリックします。
選択した環境に新しい API プロキシが正常に作成されてデプロイされたことを示す確認が送信されます。
[View the <proxy name> proxy in the editor] をクリックして、API プロキシの詳細ページを表示します。

API プロキシバンドルからの API プロキシの読み込み

API プロキシを他のサポートファイルと合わせて XML ファイルの集合として定義することがよくあります。API プロキシを Edge 外のファイルセットとして定義することで、それらをソース管理システムで保守し、テストやデプロイの際に Edge に読み込めるようになります。

API プロキシの作成と API プロキシバンドルからの API プロキシの読み込みの方法については、次の動画をご覧ください。

Edge

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 プロキシの詳細ページを表示します。

Classic Edge（Private Cloud）

このセクションの UI を使用した API プロキシの作成で説明したように、[Create Proxy] ウィザードにアクセスします。
[Build a Proxy] ウィザードで、[Proxy bundle] を選択します。
[Next] をクリックします。

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

フィールド	説明
ZIP Bundle	[Choose File] をクリックして、API プロキシ構成を含む ZIP ファイルに移動します。
Proxy Name	API に表示される名前。

ビルド情報を確認して、[Build] をクリックします。
成功した場合はメッセージが表示され、読み込まれた API プロキシは、Edge によって自動的に組織内の選択された環境にデプロイされます。API プロキシによって公開された API は、呼び出しに利用できます。
[View the <proxy name> proxy in the editor] をクリックして、API プロキシの詳細ページを表示します。
プロキシをデプロイするには、[Deployment] プルダウンをクリックし、デプロイ先の環境を選択して、プロンプトに応答します。

SOAP ベースのウェブサービスの API プロキシとしての公開

[Create Proxy] ウィザードで [SOAP Service] をクリックし、ウィザードに従って SOAP サービスにパススループロキシまたは REST ベースのプロキシを作成します。詳しくは、API プロキシとしての SOAP サービスの公開をご覧ください。

セキュリティの追加

[Create Proxy] ウィザードの [Common policies]（Edge）または [Security]（Classic Edge）ページで、追加するセキュリティ認可のタイプを選択します。次の表は、使用可能なオプションをまとめたものです。

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

CORS サポートの追加

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

API に CORS のサポートを追加するには、[Create Proxy] ウィザードの [Common policies]（Edge）または [Security]（Classic Edge）ページで [Add CORS headers] を選択します。

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

OpenAPI 仕様を使用したプロキシの生成

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

OpenAPI 仕様とは

Open API Initiative のロゴ Open API Initiative（OAI）は、Swagger 仕様に基づく、ベンダーに依存しない API 記述形式の作成、進化、促進に注力しています。Open API Initiative について詳しくは、https://openapis.org をご覧ください。

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

次に、Apigee の疑似的なターゲットサービス（http://mocktarget.apigee.net）を記述した OpenAPI 仕様のフラグメントを示します。詳しくは、https://github.com/apigee/api-platform-samples/tree/master/default-proxies/helloworld/openapi をご覧ください。

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
...

[Create Proxy] ウィザードにより、OpenAPI 仕様を読み込み、それを使って API プロキシを生成できます。プロキシが生成されたら、あらゆる Edge プロキシと同様に、ポリシーを追加し、カスタムコードを実装するなどして、Edge UI を使用してさらに開発できます。

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

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

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

OpenAPI 仕様から API プロキシを作成する方法については、次の動画をご覧ください。

OpenAPI 仕様を使用した API プロキシのフローの更新

OpenAPI 仕様から API プロキシを作成した後に、仕様を変更してリソースパスを追加する場合は、仕様を使って関連する条件付きフローを API プロキシに追加できます。

OpenAPI 仕様を使用して API プロキシのフローを更新するには:

OpenAPI 仕様に新しいリソースパスを追加します。既存の OpenAPI 仕様の編集をご覧ください。
UI で API プロキシを開き、[Develop] タブをクリックします。
ナビゲータで、更新するプロキシエンドポイントの横にある [+] をクリックします。
[New Conditional Flow] ダイアログボックスが開きます。
[From OpenAPI] が選択されていない場合はクリックします。
OpenAPI 仕様に、API プロキシに対応する条件付きフローがないリソースがある場合は、次の図に示すように、ダイアログに一覧表示されます。
条件付きフローを追加するリソースをそれぞれ選択します。
[Add] をクリックします。

条件付きフローが API プロキシに追加されます。

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

次のように、API プロキシの新しいリビジョンを作成します。

Edge

Edge UI を使用して API プロキシの新しいリビジョンを作成するには:

apigee.com/edge にログインします。
左側のナビゲーションバーで [Develop] > [API Proxies] を選択します。
リスト内のコピーする API プロキシをクリックします。
[Project] > [Save as New Revision] を選択します。

Classic Edge（Private Cloud）

Classic Edge UI を使用して API プロキシの新しいリビジョンを作成するには:

http://ms-ip:9000 にログインします。ここで、ms-ip は、Management Server ノードの IP アドレスまたは DNS 名です。
上部のナビゲーションバーで [APIs] > [API Proxies] を選択します。
リスト内のコピーする API プロキシをクリックします。
[Project] > [Save as New Revision] を選択します。

API プロキシのコピー

次のように、既存の API プロキシを新しい API プロキシにコピーします。

Edge

Edge UI を使用して API プロキシをコピーするには:

apigee.com/edge にログインします。
左側のナビゲーションバーで [Develop] > [API Proxies] を選択します。
リスト内のコピーする API プロキシをクリックします。
[Project] > [Save as New API Proxy] を選択します。
[Save as New Proxy] ダイアログで、新しい API プロキシの名前を入力します。
[Add] をクリックします。

Classic Edge（Private Cloud）

Classic Edge UI を使用して API プロキシをコピーするには:

http://ms-ip:9000 にログインします。ここで、ms-ip は、Management Server ノードの IP アドレスまたは DNS 名です。
上部のナビゲーションバーで [APIs] > [API Proxies] を選択します。
リスト内のコピーする API プロキシをクリックします。
[Project] > [Save as New API Proxy] を選択します。
[Save as New Proxy] ダイアログで、新しい API プロキシの名前を入力します。
[Add] をクリックします。

API プロキシのバックアップ

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

API を使用した API プロキシの作成

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

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

UI を使用した API プロキシの作成

Edge

Classic Edge（Private Cloud）

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

Edge

Classic Edge（Private Cloud）

API プロキシ バンドルからの API プロキシの読み込み

Edge

Classic Edge（Private Cloud）

SOAP ベースのウェブサービスの API プロキシとしての公開

セキュリティの追加

CORS サポートの追加

OpenAPI 仕様を使用したプロキシの生成

OpenAPI 仕様とは

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

OpenAPI 仕様を使用した API プロキシのフローの更新

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

Edge

Classic Edge（Private Cloud）

API プロキシのコピー

Edge

Classic Edge（Private Cloud）

API プロキシのバックアップ

API を使用した API プロキシの作成

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

API プロキシバンドルからの API プロキシの読み込み