チュートリアル: 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 機能の概要については、Azure portal を使用して API Management のチュートリアルを参照してください。
前提条件
- Azure API Management の用語を理解する。
- Visual Studio Code と最新の Visual Studio Code 用 Azure API Management 拡張機能が確実にインストール済みであること。
- API Management インスタンスを作成する。
API をインポートする
以下の例では、JSON 形式の OpenAPI 仕様を API Management にインポートします。 この例で使用されるバックエンド API は Microsoft から提供されており、Azure (https://conferenceapi.azurewebsites.net
) でホストされています。
- Visual Studio Code のアクティビティ バーから Azure アイコンを選択します。
- 作成した API Management インスタンスをエクスプローラー ペインで展開します。
- [API] を右クリックし、 [Import from OpenAPI Link](OpenAPI リンクからインポート) を選択します。
- 確認を求められたら、次の値を入力します。
JSON 形式のコンテンツの OpenAPI リンク。 この例では「
https://conferenceapi.azurewebsites.net?format=json
」とします。このファイルは、この例の API を実装するバックエンド サービスを指定します。この場合は
https://conferenceapi.azurewebsites.net
です。 要求は、API Management によってこの Web サービスに転送されます。API Management インスタンスにおける一意の API 名 (demo-conference-api など)。 この名前には、英文字、数字、ハイフンのみを含めることができます。 最初と最後の文字は、英数字にする必要があります。 API を呼び出す際のパスに、この名前が使用されます。
API は、正常にインポートされるとエクスプローラー ペインに表示され、利用できる API 操作が [Operations](操作) ノードに表示されます。
API を編集する
API は、Visual Studio Code で編集することができます。 たとえば、API の Resource Manager JSON 記述をエディター ウィンドウで編集し、API へのアクセスに使用される http プロトコルを削除します。
OpenAPI 形式を編集するには、エクスプローラー ペインで API 名を右クリックし、 [Edit OpenAPI]\(OpenAPI の編集\) を選択します。 変更を行ってから、 [ファイル]>[保存] を選択します。
API にポリシーを適用する
API Management には、API 向けに構成できるポリシーが用意されています。 ポリシーはステートメントのコレクションです。 これらのステートメントは、API の要求または応答に対して順番に実行されます。 ポリシーは、グローバルにして API Management インスタンスのすべての API に適用することも、特定の製品、API、または API 操作に限定することもできます。
このセクションでは、API 応答を変換する一般的なアウトバウンド ポリシーを API に適用する方法を紹介します。 この例のポリシーは、応答ヘッダーを変更し、応答本文に出現する元のバックエンド URL を非表示にするものです。
エクスプローラー ペインで、インポートした demo-conference-api の [ポリシー] を選択します。 エディター ウィンドウでポリシー ファイルが開きます。 このファイルによって構成されるポリシーの対象は、この API のすべての操作です。
ファイルの
<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 ゲートウェイを経由して同等のリンクをポイントするように書き換える (マスクする) ものです。
- 1 つ目の
ファイルを保存します。 確認を求められた場合は、[アップロード] を選択してファイルをクラウドにアップロードしてください。
API のテスト
API をテストするには、サブスクリプション キーを取得し、API Management ゲートウェイに要求を行います。
サブスクリプション キーを取得する
インポートした API と適用されるポリシーをテストするには、API Management インスタンスのサブスクリプション キーが必要です。
エクスプローラー ペインで、API Management インスタンスの名前を右クリックします。
[Copy Subscription Key](サブスクリプション キーのコピー) を選択します。 このキーは、API Management インスタンスの作成時に作成される組み込みのオールアクセス サブスクリプション用です。
注意事項
オールアクセス サブスクリプションを使用すると、この API Management インスタンス内のすべての API へのアクセスが可能になります。これは、承認されたユーザーのみが使用する必要があります。 これを定期的な API アクセスに使用したり、クライアント アプリにオールアクセス キーを埋め込んだりしないでください。
API 操作をテストする
- インポートした demo-conference-api の [Operations](操作) ノードをエクスプローラー ペインで展開します。
- GetSpeakers などの操作を選択してから、操作を右クリックして [テスト操作] を選択します。
- エディター ウィンドウで、Ocp-Apim-Subscription-Key の横にある
{{SubscriptionKey}}
を、コピーしたサブスクリプション キーに置き換えます。 - [要求の送信] をクリックします。
要求が成功すると、バックエンドから 200 OK およびいくつかのデータが応答として返されます。
この応答について、次の点に注目してください。
- 応答に Custom ヘッダーが追加されています。
- 応答に X-Powered-By ヘッダーがありません。
- API バックエンドへの URL が API Management ゲートウェイ (このケースでは
https://apim-hello-world.azure-api.net/demo-conference-api
) にリダイレクトされています。
トレース要求の処理
必要に応じて、API のデバッグとトラブルシューティングに役立つ詳細な要求トレース情報を取得できます。
API のトレースを有効にする手順については、「API のトレースを有効にする」を参照してください。 機密情報の意図しない開示を制限するため、トレースは既定では 1 時間だけ許可されます。
リソースをクリーンアップする
API Management インスタンスが必要なくなった場合にこれを削除するには、右クリックして [ポータルで開く] を選択し、API Management サービスとそのリソース グループを削除します。
または、 [Delete API Management](API Management の削除) を選択して、API Management インスタンスのみを削除することもできます (この操作では、そのリソース グループは削除されません)。
関連するコンテンツ
このチュートリアルでは、Visual Studio Code 用 API Management 拡張機能の、いくつかの機能を紹介しました。 これらの機能を使用して API をインポートおよび管理できます。 以下の方法を学習しました。
- API Management に API をインポートする
- API を編集する
- API Management のポリシーを適用する
- API のテスト
API Management 拡張機能には、API を操作するための機能が他にも用意されています。 たとえば、デバッグのポリシー (Developer サービス レベルで利用可能) が利用できるほか、名前付きの値を作成して管理することができます。