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

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

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

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

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

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

Edge

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

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

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

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

Classic Edge(Private Cloud)

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

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

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

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

ウィザードの最初のページでは、以下のソースから 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

  1. このセクションの UI を使用した API プロキシの作成で説明したように、[Create Proxy] ウィザードにアクセスします。
  2. [Create Proxy] ウィザードで、[Reverse proxy (most common)] をクリックします。既存の有効な OpenAPI 仕様からプロキシを生成するには、[Use OpenAPI] をクリックします。このオプションについて詳しくは、後述の OpenAPI 仕様を使用したプロキシの生成をご覧ください。
  3. ウィザードの [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/membershttps://[host]/team/green/members を呼び出すことができます。/**/ はサポートされていないことに注意してください。

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

    新しい API プロキシが作成され、選択した環境にデプロイされます。

  7. [Edit proxy] をクリックして、API プロキシの詳細ページを表示します。

Classic Edge(Private Cloud)

  1. このセクションの UI を使用した API プロキシの作成で説明したように、[Create Proxy] ウィザードにアクセスします。
  2. [Build a Proxy] ウィザードで、[Reverse proxy (most common)] を選択します。既存の有効な OpenAPI 仕様からプロキシを生成するには、[Use OpenAPI] をクリックします。このオプションについて詳しくは、後述の OpenAPI 仕様を使用したプロキシの生成をご覧ください。
  3. [Next] をクリックします。
  4. ウィザードの [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/membershttps://[host]/team/green/members を呼び出すことができます。/**/ はサポートされていないことに注意してください。

    : プロキシ ベースパスは、[Proxy Base Path] フィールドのコンテンツを明示的に編集しない限り、[Proxy Name] に指定された値がすべて小文字に変換されたものになります。

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

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

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

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

Edge

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

Classic Edge(Private Cloud)

  1. このセクションの UI を使用した API プロキシの作成で説明したように、[Create Proxy] ウィザードにアクセスします。
  2. [Build a Proxy] ウィザードで、[Proxy bundle] を選択します。
  3. [Next] をクリックします。
  4. プロキシ ウィザードの [Details] ページで、次の情報を入力します。

    フィールド 説明
    ZIP Bundle [Choose File] をクリックして、API プロキシ構成を含む ZIP ファイルに移動します。
    Proxy Name API に表示される名前。
  5. ビルド情報を確認して、[Build] をクリックします。
    成功した場合はメッセージが表示され、読み込まれた API プロキシは、Edge によって自動的に組織内の選択された環境にデプロイされます。API プロキシによって公開された API は、呼び出しに利用できます。
  6. [View the <proxy name> proxy in the editor] をクリックして、API プロキシの詳細ページを表示します。
  7. プロキシをデプロイするには、[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 プロキシのフローを更新するには:

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

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

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

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

Edge

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

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

Classic Edge(Private Cloud)

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

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

API プロキシのコピー

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

Edge

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

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

Classic Edge(Private Cloud)

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

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

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

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

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

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