API センターで API 分析を有効にする - Microsoft マネージド
この記事では、自分で管理することなく、Azure API Center の API 分析を有効にする方法 (プレビュー) について説明します。 API 分析には、組織の API センター内の API 定義を分析するためのリンティング機能が用意されています。 リンティングにより、API 定義が組織のスタイル ルールに準拠していることを確認し、個々のレポートと概要レポートの両方を生成できます。 API 分析を使用して、API 定義の一般的なエラーと不整合を特定して修正します。
重要
API Center のマネージド API 分析では、リンティング エンジンと必要な依存関係が自動的に設定されます。 また、カスタム Azure 関数を使用して、手動でリンティングと分析を有効にすることもできます。 マネージド API 分析を有効にする前に、手動リンティングに使用するすべての関数を無効にします。
このシナリオでは:
- Azure API Center 用の Visual Studio Code 拡張機能を使用して、API センターにリンティング ルールセット (API スタイル ガイド) を追加します。
- API 定義を追加または更新すると、Azure API Center によってリンティングが自動的に実行されます。 また、API センターにルールセットをデプロイした場合も、すべての API 定義に対してトリガーされます。
- Azure portal で API 分析レポートを確認し、API 定義がスタイル ガイドにどのように準拠しているかを確認します。
- 必要に応じて、組織の API 用にルールセットをカスタマイズします。 カスタム ルールセットを API センターにデプロイする前に、ローカルでテストします。
制限事項
- 現時点では、JSON または YAML 形式の OpenAPI 仕様ドキュメントのみが分析されます。
- 既定では、
spectral:oasルールセットを使用して分析を行います。 組み込みルールの詳細については、Spectral GitHub リポジトリを参照してください。 - 現時点では、1 つのルールセットを構成すると、API センター内のすべての OpenAPI 定義に適用されます。
- 4 時間あたりの API 定義の linted の最大数の制限を次に示します。
- Free レベル: 10
- Standard レベル: 100
前提条件
Azure サブスクリプション内の API センター。 まだ作成していない場合は、「クイック スタート: API センターを作成する」を参照してください。
次の Visual Studio Code 拡張機能。
Visual Studio Code 用 Azure API Center 拡張機能
重要
API Center 拡張機能のプレリリース バージョンを使用して、マネージド API 分析を有効にします。 拡張機能をインストールするときに、プレリリース バージョンを選択します。 [Extensions]\(拡張機能\) ビューにある拡張機能の [Manage]\(管理\) ボタンから、いつでもリリース バージョンとプレリリース バージョンを切り替えることができます。
Visual Studio Code を使用して API 分析を有効にする
既定のリンティング ルールセットを使用して API 分析を有効にするには、以下の手順を実行します。
Visual Studio Code で、Azure API Center のルールセットの管理に使用するフォルダーを開きます。
アクティビティ バーから Azure API Center アイコンを選択します。
[API Center] ペインで、API 分析を有効にする API センター リソースを展開します。
[Rules]\(ルール\) を右クリックし、[Enable API Analysis]\(API 分析の実行\) を選択します。
API 分析が正常に有効になると、メッセージが通知されます。 作業フォルダーのルートにある .api-center-rules に、API センターのフォルダーが作成されます。 API センターのフォルダーには以下が含まれます。
- リンティング エンジンで使用する既定の API スタイル ガイドを定義する
ruleset.ymlファイル。 - ルールセットを拡張するために使用できるカスタム関数の例を含む
functionsフォルダー。
分析を有効にすると、リンティング エンジンは、既定のルールセットに基づいて API センターの API 定義を分析し、API 分析レポートを生成します。
API 分析レポートを表示する
API 定義の分析サマリーと分析レポートは、Azure portal に表示されます。 API 定義の分析が完了すると、構成されている API スタイル ガイドに基づいて、エラー、警告、情報の一覧がレポートに表示されます。
API センターで分析の概要を表示するには、以下の手順を実行します。
ポータルで、API Center に移動します。
左側のメニューの [ガバナンス] で、[API 分析] を選択します。 概要が表示されます。
必要に応じて、API 定義の API 分析レポート アイコンを選択します。 次のスクリーンショットに示すように、定義の API 分析レポートが表示されます。
ヒント
API 分析レポートは、API 定義のメニュー バーにある [Analysis]\(分析\) を選択して表示することもできます。
ルールセットをカスタマイズする
既定のルールセットをカスタマイズしたり、組織の API スタイル ガイドとして置き換えたりすることができます。 たとえば、ルールセットを拡張したり、カスタム関数を追加したりできます。
ルールセットをカスタマイズまたは置き換えるには、以下の手順を実行します。
- Visual Studio Code で、作業フォルダーのルートにある
.api-center-rulesフォルダーを開きます。 - API センター リソースのフォルダーで、
ruleset.ymlファイルを開きます。 - 必要に応じてコンテンツを変更または置き換えます。
- 変更を
ruleset.ymlに保存します。
ローカルでルールセットをテストする
カスタム ルールセットを API センターにデプロイする前に、ローカルで検証します。 Visual Studio Code 用 Azure API Center 拡張機能では、Spectral を使用した API 仕様のリンティングが統合サポートされています。
Visual Studio Code で、キーボード ショートカット Ctrl + Shift + P を使ってコマンド パレットを開きます。
「Azure API Center: Set active API Style Guide」と入力して、Enter キーを押します。
[Select Local File]\(ローカル ファイルの選択\) を選択し、カスタマイズした
ruleset.ymlファイルを指定します。 Enter キーを押します。この手順により、このカスタム ルールセットをリンティングに使用するアクティブな API スタイル ガイドに指定できます。
これで、OpenAPI ベースの API 定義ファイルを開くと、Visual Studio Code でローカル リンティング操作が自動的にトリガーされます。 結果はエディターと [Problems]\(問題\) ウィンドウ ([View]\(表示\) > [Problems]\(問題\) または Ctrl + Shift + M) にインラインで表示されます。
リンティングの結果を確認します。 ルールセットに必要な調整を加え、想定通りの動作になるまでローカルでテストを続けます。
API センターにルールセットをデプロイする
カスタム ルールセットを API センターにデプロイするには、以下の手順を実行します。
- Visual Studio Code のアクティビティ バーから Azure API Center アイコンを選択します。
- [API Center] ペインで、ルールセットをカスタマイズした API センター リソースを展開します。
- [Rules]\(ルール\) を右クリックし、[Deploy Rules to API Center]\(API Center へルールをデプロイする\) を選択します。
ルールが API センターに正常にデプロイされると、メッセージが通知されます。 リンティング エンジンは、更新されたルールセットを使用して API 定義を分析します。
更新されたルールセットを使用したリンティングの結果を表示するには、ポータルで API 分析レポートを表示します。