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

このページは ApigeeApigee ハイブリッドに適用されます。

Apigee Edge のドキュメントを表示する

学習内容

このチュートリアルでは、次の方法を学習します。

  • OpenAPI 仕様から Apigee API プロキシを作成する
  • cURL を使用して API プロキシを呼び出す
  • 条件付きフローにポリシーを追加する
  • cURL を使用してポリシー呼び出しをテストする

Apigee UI を使用して OpenAPI 仕様から Apigee API プロキシを作成する方法を学びます。cURL などの HTTP クライアントで API プロキシを呼び出すと、API プロキシはリクエストを Apigee 疑似ターゲット サービスに送信します。

Open API Initiative について

Open API Initiative

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

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

Apigee 疑似ターゲット サービスについて

このチュートリアルで使用される Apigee 疑似ターゲット サービスは、Apigee でホストされ、単純なデータを返します。API キーやアクセス トークンは必要ありません。ウェブブラウザでアクセスできます。次をクリックして、試してみましょう。

http://mocktarget.apigee.net

ターゲット サービスから「Hello, guest!」というあいさつが返されます。

疑似ターゲット サービスがサポートする完全な API の一覧については、Apigee サンプル API をご覧ください。

必要なもの

  • 始める前に、概要と前提条件の手順を完了してください
  • OpenAPI 仕様。このチュートリアルでは、Apigee の疑似ターゲット サービス http://mocktarget.apigee.net を記述した mocktarget.yaml OpenAPI 仕様を使用します。詳細については、apigee/api-platform-samples をご覧ください。
  • コマンドラインまたはウェブブラウザから API 呼び出しを行うためにマシンにインストールされた cURL

API プロキシを作成する

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

  1. Cloud コンソールの Apigee UI を使用している場合: [プロキシ開発] > [API プロキシ] を選択します。

    従来の Apigee UI を使用している場合: [Develop] > [API Proxies] を選択して、[Proxies] ペインでプロキシの環境を選択します。

  2. メイン ウィンドウで [API Proxies] をクリックします。

    または、左側のナビゲーション バーで [Develop] > [API Proxies] を選択することもできます。

    ランディング ページの [API Proxies] をクリック

  3. [Create new] をクリックします。

    API プロキシの追加
  4. [Create Proxy] ウィザードで、[Reverse proxy (most common)] テンプレートの [Use OpenAPI Spec] をクリックします。

    プロキシタイプの作成
  5. [URL] をクリックして次の情報を入力します。

    OpenAPI Spec URL: [URL] フィールドに、OpenAPI 仕様の GitHub にある未加工コンテンツへのパスを入力します。

    https://raw.githubusercontent.com/apigee/api-platform-samples/master/default-proxies/helloworld/openapi/mocktarget3.0.yaml
  6. [Select] をクリックします。

    [Create Proxy] ウィザードの [Proxy details] ページが表示されます。以下に示すように、OpenAPI 仕様で定義されている値がフィールドに入力されます。

    次の表に、OpenAPI 仕様を使用して事前に入力されるデフォルト値を示します。

    フィールド 説明 デフォルト
    Name API プロキシの名前。例: Mock-Target-API OpenAPI 仕様の title プロパティ(スペースはダッシュに置き換えられる)
    Base path この API プロキシを組織内で一意に識別するパス コンポーネント。この API プロキシの公開 URL は、外部または内部のドメイン名と、このベースパスで構成されます。例: http://apitest.acme.com/mock-target-api すべて小文字に変換された [Name] フィールド コンテンツ
    Description API プロキシの説明。 OpenAPI 仕様の description プロパティ
    Target (Existing API) API プロキシに代わって呼び出されるターゲット URL。オープンなインターネット経由でアクセスできる任意の URL を使用できます。例: http://mocktarget.apigee.net OpenAPI 仕様の servers プロパティ

    以下に示す 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
    ...
    servers:
      - url: http://mocktarget.apigee.net
      - url: https://mocktarget.apigee.net
    ...
    
  7. [プロキシの詳細] ページで、[説明] フィールドを次のように編集します。
    API proxy for the Apigee mock target service endpoint.
  8. [次へ] をクリックします。
  9. [Common policies] ページで、[Security: Authorization] の [Pass through (no authorization)] が選択されていることを確認して [Next] をクリックします。

    [Common policies] ページで [Pass through (no authorization)] が選択されている

  10. [Flows] ページで、すべてのオペレーションが選択されていることを確認します。プロキシフローの作成
  11. [Next] をクリックします。
  12. [Summary] ページの [Optional Deployment] で環境が選択されていることを確認し、[Create and deploy] をクリックします。

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

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

API プロキシをテストする

cURL またはウェブブラウザを使用して、Mock-Target-API API をテストできます。

curl -v YOUR_ENV_GROUP_HOSTNAME/myproxy

ここで、YOUR_ENV_GROUP_HOSTNAME は環境グループのホスト名です。環境グループのホスト名を探すをご覧ください。

次に例を示します。

curl -v -k https://apitest.acme.com/myproxy

レスポンス

次のようなレスポンスが表示されます。

Hello, Guest!

XML to JSON ポリシーを追加する

次に、OpenAPI 仕様から API プロキシを作成したときに自動的に生成された View XML Response 条件付きフローに XML to JSON ポリシーを追加します。このポリシーは、ターゲットの XML レスポンスを JSON レスポンスに変換します。

最初に、ポリシーの追加後に受け取る結果と元の結果を比較できるように、API を呼び出します。ターミナル ウィンドウで、次の cURL コマンドを実行します。ターゲット サービスの /xml リソースを呼び出していると、XML の単純なブロックがネイティブに返されます。

curl -v https://YOUR_ENV_GROUP_HOSTNAME/mock-target-api/xml

ここで、YOUR ENV_GROUP_HOSTNAME は環境グループのホスト名です。環境グループのホスト名を探すをご覧ください。

レスポンス

次のようなレスポンスが表示されます。

<root> 
  <city>San Jose</city> 
  <firstName>John</firstName> 
  <lastName>Doe</lastName> 
  <state>CA</state> 
</root>

次に、XML レスポンスを JSON に変換してみましょう。XML to JSON ポリシーを API プロキシの [View XML Response] 条件付きフローに追加します。

新しいプロキシ エディタ

  1. Apigee UI の [Mock-Target-API Overview] ページで [Develop] タブをクリックします。

  2. [View XML Response] を選択

  3. 左側のペインで、[Proxy Endpoints] > [default] の下の [View XML Response] 条件付きフローをクリックします。
  4. 左側のペインで、[Policies] 行の [+] ボタンをクリックします。
  5. [Create policy] ダイアログで、[Select policy type] フィールドをクリックし、[Mediation] まで下にスクロールし、[XMLToJSON] を選択します。[Display Name] と [Name] はデフォルト値のままにします。

  6. [Create] をクリックしてポリシーを作成します。
  7. [レスポンス] で、[View XML response] フローの横にある [+] ボタンをクリックします。

    [+Step] を選択

  8. [Add Policy Step] ダイアログで [Select existing policy] フィールドをクリックし、[XML to JSON-1] を選択します。
  9. [Add] をクリックします。XML to JSON ポリシーがレスポンスに適用されます。

    フローの XML to JSON ポリシー

    [View XML Response] 条件フローのコードを表示するには、[Switch To Code Editor] をクリックします。

  10. [Save] をクリックします。

従来バージョンのプロキシ エディタ

  1. Apigee UI の [Mock-Target-API Overview] ページで [Develop] タブをクリックします。

    [Developer] タブ
  2. 左側のナビゲーション パネルで、[Proxy Endpoints] > [default] の下の [View XML Response] 条件付きフローをクリックします。

    [View XML Response] を選択
  3. 画面下部で、フローの [レスポンス] に対応する [+ Step] ボタンをクリックします。

    [+Step] を選択

    [Add Step] ダイアログが開き、追加できるすべてのポリシーの分類リストが表示されます。

  4. [Mediation] カテゴリまでスクロールし、[XML to JSON] を選択します。

    [Add Step] ダイアログ
  5. [Display Name] と [Name] はデフォルト値のままにします。
  6. [Add] をクリックします。XML to JSON ポリシーがレスポンスに適用されます。

    フローの XML to JSON ポリシー
  7. [Save] をクリックします。

ポリシーを追加したら、cURL を使用して API をもう一度呼び出します。同じ /xml リソースを呼び出していることに注意してください。ターゲット サービスは依然として XML のブロックを返しますが、API プロキシのポリシーはレスポンスを JSON に変換します。次の呼び出しを行います。

curl -v https://YOUR_ENV_GROUP_HOSTNAME/mock-target-api/xml

ここで、YOUR ENV_GROUP_HOSTNAME は環境グループのホスト名です。環境グループのホスト名を探すをご覧ください。

XML レスポンスが JSON に変換されていることに注意してください。

{"root":{"city":"San Jose","firstName":"John","lastName":"Doe","state":"CA"}}