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

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

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

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

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

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

次のセクションで説明するように、Edge UI または Classic Edge UI を使用して [Create Proxy] ウィザードにアクセスします。

Edge

[Create Proxy] ウィザードにアクセスするには:

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

Classic Edge

[Create Proxy] ウィザードにアクセスするには:

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

[Create Proxy] ウィザードが表示されます。このウィザードによって、API プロキシを生成し、その API プロキシに最小限の機能を追加するために必要となる手順が示されます。

ウィザード フローをカスタマイズするために、Reverse proxy、Node.js App、SOAP service、No Target、または Proxy bundle を選択するように求める [Create Proxy] ウィザードの最初のページ。

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

タイプ 説明
Reverse proxy (most common)

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

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

Node.js App

Edge 上で実行中の Node.js バックエンド ターゲットにルーティングする API プロキシ。Apigee Edge で Node.js の使用を開始するをご覧ください。

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

SOAP service WSDL ファイルから生成された API プロキシ。SOAP ベースのウェブサービスの API プロキシとしての公開をご覧ください。
No Target

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

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

Proxy bundle 既存の API プロキシ バンドル(たとえば GitHub に用意されているサンプル API プロキシのいずれか)。API プロキシ バンドルからの API プロキシの読み込みをご覧ください。

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

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

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

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

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

  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 の推奨事項については、『ウェブ API 設計: ミッシング リンク』電子ブックのバージョニングをご覧ください。

    ベースパスの後ろには、追加のリソース 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 プロキシの読み込みの方法については、次の動画をご覧ください。

API プロキシ バンドルから API プロキシを読み込むには:

  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 プロキシとしての公開

[Build a Proxy] ウィザードで、[Soap Service] を選択し、ウィザードの手順に従って SOAP サービス用のパススルー プロキシまたは REST ベースプロキシを作成します。

詳しくは、API プロキシとしての SOAP サービスの公開をご覧ください。

セキュリティの追加

[Build a Proxy] ウィザードの [Security] ページで、追加する認証のタイプを選択します。次の表は、使用可能なオプションをまとめたものです。

項目 説明
Pass through (none) 認証は不要です。リクエストは、Apigee Edge によるセキュリティ チェックが一切行われずにバックエンドに渡されます。
API Key 定義中の 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 をご覧ください。

API キーまたは OAuth 2.0 認証を選択すると、さらに次の選択が可能になります。

項目 説明
Impose Quota per Developer 有効にすると、特定の期間に個別のアプリが API プロキシに送信できるリクエスト メッセージの数を制限する Quota ポリシーが追加されます。
Publish API Product 有効にすると、新しい API プロキシを作成するときに API プロダクトが自動的に生成されます。自動生成される API プロダクトは、新しい API プロキシに関連付けられた状態で作成されます。プロダクトについて詳しくは、API プロダクトとはをご覧ください。

CORS サポートの追加

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

API に CORS サポートを追加するには、[Add a Proxy] ウィザードの [Security] ページで [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 をご覧ください。

    swagger: '2.0'
    info:
      description: 'OpenAPI Specification for the Apigee mock target service endpoint.'
      version: 1.0.0
      title: Mock Target API
    host: mocktarget.apigee.net
    schemes:
      - http
      - https
    paths:
      /:
        get:
          summary: View personalized greeting
          operationId: View a personalized greeting
          description: View a personalized greeting for the specified or guest user.
          produces:
            - text/plain
          parameters:
            - name: user
              in: query
              description: Your user name.
              required: false
              type: string
          responses:
            '200':
              description: Success
      /help:
        get:
          summary: Get help
          operationId: Get help
          description: View help information about available resources in HTML format.
          produces:
            - text/html
          responses:
            '200':
              description: Success
    ...
    

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

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

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

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

OpenAPI 仕様から API プロキシを作成するには:

  1. このセクションの UI を使用した API プロキシの作成で説明したように、[Create Proxy] ウィザードにアクセスします。
  2. [Build a Proxy] ウィザードで、作成するプロキシのタイプを選択します。リバース プロキシ、Node.js、ターゲットなしプロキシ用の OpenAPI がサポートされています。
  3. [Use OpenAPI] をクリックします。
  4. ダイアログで、既存の有効な OpenAPI 仕様を指す URL を入力します。たとえば、次の URL を試してテストできます。

    https://raw.githubusercontent.com/apigee/api-platform-samples/master/default-proxies/helloworld/openapi/mocktarget.yaml
  5. [Apply] をクリックします。
    Edge により、仕様が読み取られ、それを使用してプロキシが生成されます。
  6. [Next] をクリックします。

  7. [Build a Proxy] ウィザードの [Details] ページが表示されます。項目は、OpenAPI 仕様で定義されている値を使用して事前に入力されています。たとえば、リバース プロキシを選択した場合は次のようになります。
    [Build a Proxy] の [Details] ページ。詳細は下の図で説明されています。
    次の表に、OpenAPI 仕様のプロパティを使用して事前に入力されるデフォルトの項目値を示します。表の後に、使用されるプロパティを示す OpenAPI 仕様の抜粋があります。
    項目 説明 デフォルト
    Proxy Name API プロキシの名前。たとえば、Mock-Target-API です。 スペースをダッシュで置き換えた OpenAPI 仕様の title プロパティ
    Proxy Base Path

    組織内でこの API プロキシを一意に識別するパス コンポーネント。この API プロキシの一般公開される URL は、組織名、この API プロキシがデプロイされる環境、この [Proxy Base Path] の値で構成されます。たとえば、https://myorg-test.apigee.net/mock-target-api です。

    : プロキシ ベースパスのデフォルトは、[Proxy Base Path] 項目で明示的に編集しない限り、[Proxy Name] に対して指定された値をすべて小文字に変換した値です。

    すべて小文字に変換された [Proxy Name] 項目の内容
    Existing API

    : 項目はリバース プロキシのみに有効です。

    この API プロキシに代わって呼び出されるターゲット URL。オープンなインターネット経由でアクセスできる任意の URL を使用できます。たとえば、https://mocktarget.apigee.net です。

    OpenAPI 仕様のプロパティが組み合わされて、ターゲット URL が作成されます。
    • http:// または https://schemes プロパティに基づきます)
    • host プロパティ
    • basePath プロパティ(指定された場合)
    Description API プロキシの説明。 description プロパティ

    次に示すのは、OpenAPI 仕様からの抜粋であり、項目に事前に入力するために使用されるプロパティがハイライト表示されています。

        swagger: '2.0'
        info:
          description: 'OpenAPI Specification for the Apigee mock target service endpoint.'
          version: 1.0.0
          title: Mock Target API
        host: mocktarget.apigee.net
        schemes:
          - http
          - https
        ...
    
        
  8. [Next] をクリックします。
  9. [Flows] ページで、条件フローを生成する対象のオペレーションを選択します。条件フローは、OpenAPI 仕様の paths オブジェクト内で定義されているオペレーションから自動的に生成されます。条件フローでは「条件フローが定義されている場合、該当ロジックを実行する」ということを Edge に指示します。フローでプロキシの実行方法を制御するをご覧ください。次に例を示します。
    Mock Target API の各オペレーションのパス、動詞、オペレーション ID、要約が表示された [Build a Proxy] の [Flows] ページ。/help 以外のすべてが選択されています。
  10. ウィザードの [Security] ページで、以下を構成します。
    • セキュリティ認証要件。このセクションで後述するセキュリティの追加をご覧ください。
    • クロスオリジン リソース シェアリング(CORS)のサポート。このセクションで後述する CORS サポートの追加をご覧ください。
  11. ウィザードの [Virtual Hosts] ページで、API プロキシがデプロイされるときにバインドする仮想ホストを選択します。詳しくは、仮想ホストについてをご覧ください。
  12. デプロイ環境を選択して、[Build and Deploy] をクリックします。
    選択した環境に新しい API プロキシが正常に作成されてデプロイされたことを確認する肯定応答が送信されます。
  13. [View the <proxy name> proxy in the editor] をクリックして、API プロキシの詳細ページを表示します。

次の図は、Mock-Target-API プロキシの場合の Edge UI の [Develop] ビューです(Get help オペレーションに対して条件付きフローが自動的に生成されないことに注意してください)。

Mock-Target-API プロキシの場合の Edge UI の [Develop] ビュー。

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 プロキシの新しいリビジョンの作成

次のセクションで説明するように、Edge UI または Classic Edge UI を使用して API プロキシの新しいリビジョンを作成します。

Edge

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

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

Classic Edge

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

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

API プロキシのコピー

次のセクションで説明するように、Edge UI または Classic Edge UI を使用して、既存の API プロキシを新しい API プロキシにコピーします。

Edge

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

API プロキシをコピーするには:

  1. enterprise.apigee.com にログインします。
  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 プロキシをご覧ください。