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

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

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

学習内容

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

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

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

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 プロキシを作成するには:

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

従来の Apigee UI を使用している場合: [Develop] > [API Proxies] を選択して、[Proxies] ペインでプロキシの環境を選択します。
メインウィンドウで [API Proxies] をクリックします。
または、左側のナビゲーションバーで [Develop] > [API Proxies] を選択することもできます。
[Create new] をクリックします。
[Create Proxy] ウィザードで、[Reverse proxy (most common)] テンプレートの [Use OpenAPI Spec] をクリックします。
[URL] をクリックして次の情報を入力します。
OpenAPI Spec URL: [URL] フィールドに、OpenAPI 仕様の GitHub にある未加工コンテンツへのパスを入力します。
```
https://raw.githubusercontent.com/apigee/api-platform-samples/master/default-proxies/helloworld/openapi/mocktarget3.0.yaml
```

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

[Proxy details] ページで、[Description] フィールドを次のように編集します。
```
API proxy for the Apigee mock target service endpoint.
```
[Next] をクリックします。
[Common policies] ページで、[Security: Authorization] の [Pass through (no authorization)] が選択されていることを確認して [Next] をクリックします。
[Flows] ページで、すべてのオペレーションが選択されていることを確認します。
ヒント: 条件付きフローは、OpenAPI 仕様の paths オブジェクト内で定義されているオペレーションから自動的に生成されます。条件付きフローにより、「条件付きフローが定義されている場合に、該当ロジックを行う」ということが Apigee に指示されます。たとえば、API 呼び出しが /xml リソース（条件）に対する GET である場合、条件付きフローに接続されたポリシーを介してレスポンスを JSON に変換します。トランザクションごとに 1 つのフロー（最初に true と評価される条件を持つフロー）のみが実行されます。
[Next] をクリックします。
[Summary] ページの [Optional Deployment] で環境が選択されていることを確認し、[Create and deploy] をクリックします。

新しい API プロキシが作成され、環境にデプロイされます。
[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] 条件付きフローに追加します。

新しいプロキシエディタ

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

[View XML Response] を選択

左側のペインで、[Proxy Endpoints] > [default] の下の [View XML Response] 条件付きフローをクリックします。
左側のペインで、[Policies] 行の [+] ボタンをクリックします。
[Create policy] ダイアログで、[Select policy type] フィールドをクリックし、[Mediation] まで下にスクロールし、[XMLToJSON] を選択します。[Display Name] と [Name] はデフォルト値のままにします。
[Create] をクリックしてポリシーを作成します。
[レスポンス] で、[View XML response] フローの横にある [+] ボタンをクリックします。
[Add Policy Step] ダイアログで [Select existing policy] フィールドをクリックし、[XML to JSON-1] を選択します。
[Add] をクリックします。XML to JSON ポリシーがレスポンスに適用されます。

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

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

Apigee UI の [Mock-Target-API Overview] ページで [Develop] タブをクリックします。
左側のナビゲーションパネルで、[Proxy Endpoints] > [default] の下の [View XML Response] 条件付きフローをクリックします。
画面下部で、フローの [レスポンス] に対応する [+ Step] ボタンをクリックします。

[Add Step] ダイアログが開き、追加できるすべてのポリシーの分類リストが表示されます。
[Mediation] カテゴリまでスクロールし、[XML to JSON] を選択します。
[Display Name] と [Name] はデフォルト値のままにします。
[Add] をクリックします。XML to JSON ポリシーがレスポンスに適用されます。
[Save] をクリックします。

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

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