チュートリアル: Visual Studio Code 用の Azure API Management 拡張機能を使用して API をインポートおよび管理する

  • [アーティクル]

適用対象: Consumption | Developer | Basic | Standard | Premium

このチュートリアルでは、Visual Studio Code 用の API Management 拡張機能を使用して、API Management の一般的な操作を行う方法について説明します。 使い慣れた Visual Studio Code 環境を使用して、API のインポート、更新、テスト、管理を行います。

学習内容は次のとおりです。

  • API Management に API をインポートする
  • API を編集する
  • API Management のポリシーを適用する
  • API のテスト

API Management 拡張機能の API のスクリーンショット。

その他の API Management 機能の概要については、Azure portal を使用して API Management のチュートリアルを参照してください。

前提条件

API をインポートする

以下の例では、JSON 形式の OpenAPI 仕様を API Management にインポートします。 この例で使用されるバックエンド API は Microsoft から提供されており、Azure (https://conferenceapi.azurewebsites.net) でホストされています。

  1. Visual Studio Code のアクティビティ バーから Azure アイコンを選択します。
  2. 作成した API Management インスタンスをエクスプローラー ペインで展開します。
  3. [API] を右クリックし、 [Import from OpenAPI Link](OpenAPI リンクからインポート) を選択します。
  4. 確認を求められたら、次の値を入力します。

    1. JSON 形式のコンテンツの OpenAPI リンク。 この例では「 https://conferenceapi.azurewebsites.net?format=json 」とします。

      このファイルは、この例の API を実装するバックエンド サービスを指定します。この場合は https://conferenceapi.azurewebsites.net です。 要求は、API Management によってこの Web サービスに転送されます。

    2. API Management インスタンスにおける一意の API 名 (demo-conference-api など)。 この名前には、英文字、数字、ハイフンのみを含めることができます。 最初と最後の文字は、英数字にする必要があります。 API を呼び出す際のパスに、この名前が使用されます。

API は、正常にインポートされるとエクスプローラー ペインに表示され、利用できる API 操作が [Operations](操作) ノードに表示されます。

Explorer ウィンドウのインポートされた API のスクリーンショット。

API を編集する

API は、Visual Studio Code で編集することができます。 たとえば、API の Resource Manager JSON 記述をエディター ウィンドウで編集し、API へのアクセスに使用される http プロトコルを削除します。

Visual Studio Code での JSON の説明の編集のスクリーンショット。

OpenAPI 形式を編集するには、エクスプローラー ペインで API 名を右クリックし、 [Edit OpenAPI]\(OpenAPI の編集\) を選択します。 変更を行ってから、 [ファイル]>[保存] を選択します。

API にポリシーを適用する

API Management には、API 向けに構成できるポリシーが用意されています。 ポリシーはステートメントのコレクションです。 これらのステートメントは、API の要求または応答に対して順番に実行されます。 ポリシーは、グローバルにして API Management インスタンスのすべての API に適用することも、特定の製品、API、または API 操作に限定することもできます。

このセクションでは、API 応答を変換する一般的なアウトバウンド ポリシーを API に適用する方法を紹介します。 この例のポリシーは、応答ヘッダーを変更し、応答本文に出現する元のバックエンド URL を非表示にするものです。

  1. エクスプローラー ペインで、インポートした demo-conference-api の [ポリシー] を選択します。 エディター ウィンドウでポリシー ファイルが開きます。 このファイルによって構成されるポリシーの対象は、この API のすべての操作です。

  2. ファイルの <outbound> 要素を次の内容で更新します。

    [...]
<outbound>
    <set-header name="Custom" exists-action="override">
        <value>"My custom value"</value>
    </set-header>
    <set-header name="X-Powered-By" exists-action="delete" />
    <redirect-content-urls />
    <base />
</outbound>
[...]
    • 1 つ目の set-header ポリシーは、デモンストレーション用のカスタム応答ヘッダーを追加するものです。
    • 2 つ目の set-header ポリシーは、X-Powered-By ヘッダーが存在する場合に、そのヘッダーを削除するものです。 API バックエンドで使用されているアプリケーション フレームワークがこのヘッダーから明らかになる可能性があることから、このヘッダーは発行元によって削除されるのが一般的です。
    • redirect-content-urls ポリシーは、応答本文内のリンクを、API Management ゲートウェイを経由して同等のリンクをポイントするように書き換える (マスクする) ものです。

  3. ファイルを保存します。 確認を求められた場合は、[アップロード] を選択してファイルをクラウドにアップロードしてください。

API のテスト

API をテストするには、サブスクリプション キーを取得し、API Management ゲートウェイに要求を行います。

サブスクリプション キーを取得する

インポートした API と適用されるポリシーをテストするには、API Management インスタンスのサブスクリプション キーが必要です。

  1. エクスプローラー ペインで、API Management インスタンスの名前を右クリックします。

  2. [Copy Subscription Key](サブスクリプション キーのコピー) を選択します。 このキーは、API Management インスタンスの作成時に作成される組み込みのオールアクセス サブスクリプション用です。

    Visual Studio Code のサブスクリプション キーのコピー コマンドのスクリーンショット。

    注意事項

    オールアクセス サブスクリプションを使用すると、この API Management インスタンス内のすべての API へのアクセスが可能になります。これは、承認されたユーザーのみが使用する必要があります。 これを定期的な API アクセスに使用したり、クライアント アプリにオールアクセス キーを埋め込んだりしないでください。

API 操作をテストする

  1. インポートした demo-conference-api の [Operations](操作) ノードをエクスプローラー ペインで展開します。
  2. GetSpeakers などの操作を選択してから、操作を右クリックして [テスト操作] を選択します。
  3. エディター ウィンドウで、Ocp-Apim-Subscription-Key の横にある {{SubscriptionKey}} を、コピーしたサブスクリプション キーに置き換えます。
  4. Ocp-Apim-Trace の横に false と入力します。 この設定により、要求トレースが無効になります。
  5. [要求の送信] をクリックします。

Visual Studio Code からの API 要求送信のスクリーンショット。

要求が成功すると、バックエンドから 200 OK およびいくつかのデータが応答として返されます。

Visual Studio Code での API テスト応答のスクリーンショット。

この応答について、次の点に注目してください。

  • 応答に Custom ヘッダーが追加されています。
  • 応答に X-Powered-By ヘッダーがありません。
  • API バックエンドへの URL が API Management ゲートウェイ (このケースでは https://apim-hello-world.azure-api.net/demo-conference-api) にリダイレクトされています。

トレース要求の処理

必要に応じて、API のデバッグとトラブルシューティングに役立つ詳細な要求トレース情報を取得できます。

要求処理を追跡するには、まず API のデバッグに使用するサブスクリプションの [トレースを許可] 設定を有効にしてください。 ポータルを使用してこの設定を有効にする手順については、「トレース許可の設定を確認する」を参照してください。 機密情報の意図しない開示を制限するために、トレースは 1 時間だけ許可されます。

サブスクリプションでトレースを許可した後、次の手順に従います。

  1. インポートした demo-conference-api の [Operations](操作) ノードをエクスプローラー ペインで展開します。
  2. GetSpeakers などの操作を選択してから、操作を右クリックして [テスト操作] を選択します。
  3. エディター ウィンドウで、Ocp-Apim-Subscription-Key の横にある {{SubscriptionKey}} を、使用したいサブスクリプション キーに置き換えます。
  4. Ocp-Apim-Trace の横に true と入力します。 この設定により、この要求のトレースが有効になります。
  5. [要求の送信] をクリックします。

要求が成功すると、バックエンド応答には Ocp-APIM-Trace-Location ヘッダーが含まれます。

Visual Studio Code での API テスト応答のトレースの場所のスクリーンショット。

Ocp-APIM-Trace-Location の横にあるリンクを選択して、受信、バックエンド、および送信のトレース情報を表示します。 トレース情報は、要求後、問題の発生場所の特定に役立ちます。

ヒント

API 操作のテスト時は、オプションのポリシーのデバッグが API Management 拡張機能によって許可されます (Developer サービス レベルでのみ利用可能)。

リソースをクリーンアップする

API Management インスタンスが必要なくなった場合にこれを削除するには、右クリックして [ポータルで開く] を選択し、API Management サービスとそのリソース グループを削除します。

または、 [Delete API Management](API Management の削除) を選択して、API Management インスタンスのみを削除することもできます (この操作では、そのリソース グループは削除されません)。

Visual Studio Code からの API Management インスタンス削除のスクリーンショット。

関連するコンテンツ

このチュートリアルでは、Visual Studio Code 用 API Management 拡張機能の、いくつかの機能を紹介しました。 これらの機能を使用して API をインポートおよび管理できます。 以下の方法を学習しました。

  • API Management に API をインポートする
  • API を編集する
  • API Management のポリシーを適用する
  • API のテスト

API Management 拡張機能には、API を操作するための機能が他にも用意されています。 たとえば、デバッグのポリシー (Developer サービス レベルで利用可能) が利用できるほか、名前付きの値を作成して管理することができます。