チュートリアル:最初の API のインポートと発行

対象: すべてのAPI Management層

このチュートリアルでは、JSON 形式で OpenAPI 仕様バックエンド API をAzure API Managementにインポートする方法について説明します。 この例では、open source Petstore API をインポートします。

バックエンド API をAPI Managementにインポートすると、API Management API がバックエンド API のゲートウェイになります。 バックエンド API を変更することなく、API Managementでニーズに合わせてゲートウェイをカスタマイズできます。 詳しくは、「API を変換および保護する」をご覧ください。

このチュートリアルでは、以下の内容を学習します。

インポート後、Azure portalで API を管理できます。

前提条件

• Azure API Managementの用語について理解します。
• Azure API Management インスタンスを作成します。

API Management インスタンスに移動する

1. Azure portalで、API Management サービス

   

2. API Management サービス ページで、API Management インスタンスを選択します。

   

バックエンド API のインポートと発行

このセクションでは、OpenAPI の仕様のバックエンド API をインポートおよび発行する方法を示します。

1. API Management インスタンスのサイドバー メニューの APIs で、APIs を選択します。

2. [OpenAPI] タイルを選択します。

3. [OpenAPI 仕様から作成する] ウィンドウで [Full](すべて) を選択します。

4. 以下の表の値を入力します。

   API の値は、作成時に、または後で [設定] タブに移動して設定できます。

   

   設定	値	説明
   OpenAPI の仕様	https://petstore3.swagger.io/api/v3/openapi.json -または- https://petstore.swagger.io/v2/swagger.json	API を実装するバックエンド サービスと、API がサポートする操作を指定します。 バックエンド サービス URL は、後で API の [設定] ページに [Web サービス URL] として表示されます。 インポート後、仕様で操作を追加、編集、名前変更、または削除できます。
   操作テンプレートにクエリ パラメーターを含める	選択済み (既定値)	仕様で必要なクエリ パラメーターをテンプレート パラメーターとしてAPI Managementにインポートするかどうかを指定します。
   表示名	OpenAPI 仕様 URL を入力すると、API Management によって JSON に基づいてこのフィールドが自動的に入力されます。	開発者ポータルに表示される名前。
   名前	OpenAPI 仕様の URL を入力すると、API Management は JSON に基づいてこのフィールドを自動的に入力します。	API の一意の名前。
   説明	OpenAPI 仕様の URL を入力すると、API Management が JSON に基づいてこのフィールドを自動的に埋めます。	API の説明 (省略可)。
   URL スキーム	HTTPS	API にアクセスできるプロトコルはどれか。
   API URL サフィックス	petstore	API Management サービスのベース URL に追加されたサフィックス。 API Managementは、サフィックスによって API を区別してルーティングするため、サフィックスは特定のpublisherのすべての API に対して一意である必要があります。 API管理が要求をルーティングする方法について詳しく知る。
   タグ		検索、グループ化、フィルター処理を目的に API を整理するためのタグ。
   成果物	無制限	1 つまたは複数の API の関連付け。 特定のレベルでは、API Management インスタンスには、Starter と Unlimited の 2 つのサンプル製品が付属しています。 API を製品と関連付けることで、開発者ポータルで API を発行します。 1 つの製品に複数の API を追加し、開発者ポータルを通じて製品サブスクリプションを開発者に提供できます。 この API を別の成果物に追加するには、成果物名を入力または選択します。 複数の成果物に API を追加するには、この手順を繰り返します。 後で [設定] ページから成果物に API を追加することもできます。 成果物の詳細については、成果物の作成と発行に関する記事を参照してください。
   ゲートウェイ	マネージド	API を公開する API ゲートウェイ。 このフィールドは、Developer レベルおよび Premium レベルのサービスでのみ使用できます。 Managed は、API Management サービスに組み込まれており、Azureで Microsoft によってホストされているゲートウェイを示します。 セルフホステッド ゲートウェイは、Premium および Developer サービス レベルでのみ使用できます。 これらはオンプレミスまたは他のクラウドにデプロイできます。 ゲートウェイを選択しない場合、API は使用できないため、API 要求は成功しません。
   この API をバージョン管理しますか?	選択/解除	詳細については、複数のバージョンの API の公開に関する記事をご覧ください。

5. [作成] を選択して API を作成します。

API 定義のインポートに問題がある場合は、 API インポートの制限と既知の問題を参照してください。

API 設定の表示と変更

API をインポートした後、Azure portalでその設定と操作を表示および変更できます。

1. API Management インスタンスのサイドバー メニューの APIs で、APIs を選択します。

2. インポートした API ( Swagger Petstore など) を選択します。 ポータル内のAPI ManagementでのAPI設定のスクリーンショット。

3. OpenAPI 仕様で次のような API 操作を表示および変更するには、[ デザイン ] タブを選択します。

   • URL、メソッド、説明などの操作の詳細
   • 要求と応答の定義
   • 要求と応答を変更するポリシー

4. [ 設定] タブを選択して、次のような API 構成の詳細を表示および変更します。

   • 表示名、名前、および説明
   • Web サービス URL (バックエンド サービス)、URL スキーム、および API URL サフィックス
   • 製品、タグ、バージョン管理
   • サブスクリプションの要件、セキュリティ、監視など、より高度な設定

API Managementチュートリアルを進める際に、API 設定の構成の詳細について学習します。 これらの設定はいつでも更新して、API 構成をカスタマイズできます。

Azure portalで新しい API をテストする

API 操作は、Azure portalから直接呼び出すことができます。これによって、操作を表示およびテストするための便利な方法が提供されます。 ポータルのテスト コンソールでは、既定では、組み込みの all-access サブスクリプションのキーを使用して API が呼び出されます。 製品をスコープとするサブスクリプション キーを使用して、API 呼び出しをテストすることもできます。

1. API Management インスタンスで、APIs>APIs>Swagger Petstore を選択します。

2. [Test] タブを選択し、[状態別でペットを見つける] を選択します。 このページには、状態クエリ パラメーターが表示されます。 使用可能な値 ([保留中]など) のいずれかを選択します。 ここでクエリ パラメーターとヘッダーを追加することもできます。

   [HTTP 要求] セクションでは、Ocp-Apim-Subscription-Key ヘッダーが自動的に入力されます。これは、"目" アイコンを選択した場合に確認できます。

3. [Send] を選択します。

   Azure ポータルで API をテストしているスクリーンショット。

   バックエンドは 200 OK といくつかのデータで応答します。

API マネージメントが要求をルーティングする方法

API Managementは、API クライアントとバックエンド サービスの間のゲートウェイとして機能します。 クライアントが API Management によって管理される API に要求を行うと、ルーティングは次のパターンに従います。

クライアント要求 URL:
[API Management gateway URL] + [API URL suffix] + [Operation endpoint]

API Managementは、次のパターンを使用してバックエンド サービスに要求を転送します。

バックエンド サービス URL:
[Web service URL] + [Operation endpoint]

次の表では、このチュートリアルで使用する Petstore API の例のコンテキストにおける各ルーティング パラメーターについて説明します。

例: 状態によるペットの検索

このチュートリアルでインポートした Petstore API の使用:

• Client は API Management:
  https://apim-hello-world.azure-api.net/petstore/pet/findByStatus?status=pending

  • API Management ゲートウェイ URL: https://apim-hello-world.azure-api.net
  • API URL サフィックス: petstore
  • 操作エンドポイント: /pet/findByStatus

• API Management バックエンドへのルート:
  https://petstore3.swagger.io/api/v3/pet/findByStatus?status=pending

  • Web サービスの URL: https://petstore3.swagger.io/api/v3
  • 操作エンドポイント: /pet/findByStatus (API Management定義と同じ)

次のステップ

次のチュートリアルに進み、成果物を作成して発行する方法を学習してください。