API センターで API を分析する - Microsoft マネージド
組織の API センターには、組織のスタイル ルールに準拠するために API 定義を分析し、個別および概要レポートの両方を生成するための、組み込みで Microsoft マネージドのリンティング機能 (プレビュー) が用意されています。 API 分析は、API 定義の一般的なエラーと不整合を特定して修正するのに役立ちます。
API 分析を使用すると:
- API 定義を追加または更新するたびに、Azure API Center によって API 定義が自動的に分析されます。 API 定義は、spectral:oas ruleset (API スタイル ガイド) を使用して既定でリンティングされます。
- Azure portal で API 分析レポートが生成され、API 定義がスタイル ガイドにどの程度準拠しているかが表示されます。
- Visual Studio Code 用の Azure API Center 拡張機能を使用して、独自の API スタイル ガイドをローカルでカスタマイズしてテストし、それを API センターにデプロイできます。
重要
必要に応じて、カスタム Azure 関数を使用して、セルフマネージドのリンティングと分析を有効にして、組み込みの機能をオーバーライドできます。 マネージド API 分析を有効にする前に、セルフマネージド リンティングに使用するすべての関数を無効にしてください。
制限事項
- 現在、JSON または YAML 形式の OpenAPI と AsyncAPI 仕様ドキュメントのみが分析されます。
- 現時点では、1 つのルールセットを構成すると、API センター内のすべての OpenAPI 定義に適用されます。
- 分析される API 定義の最大数には制限があります。 分析が完了するまでに、数分から最大 24 時間かかることがあります。
前提条件
- Azure サブスクリプション内の API センター。 まだ作成していない場合は、「クイック スタート: API センターを作成する」を参照してください。
- ルールセットをカスタマイズするには、 Visual Studio Code と次の Visual Studio Code 拡張機能を使用します。
API 分析レポートを表示する
API 定義の分析サマリーと分析レポートは、Azure portal に表示されます。 API 定義の分析が完了すると、構成されている API スタイル ガイドに基づいて、エラー、警告、情報の一覧がレポートに表示されます。
API 分析レポートでは、分析に使用されたルールセットと、リンティング パスの履歴も確認できます。
API センターで分析の概要を表示するには、以下の手順を実行します。
ポータルで、API Center に移動します。
左側のメニューの [ガバナンス] で、[API 分析] を選択します。 概要が表示されます。
必要に応じて、API 定義の API 分析レポート アイコンを選択します。 次のスクリーンショットに示すように、定義の API 分析レポートが表示されます。
ヒント
API 分析レポートは、API 定義のメニュー バーにある [Analysis]\(分析\) を選択して表示することもできます。
ルールセットをカスタマイズする
Visual Studio Code 用の Azure API Center 拡張機能を使用すると、API センターの既定のルールセットをカスタマイズしたり、組織の API スタイル ガイドとして置き換えたりすることができます。 たとえば、ルールセットを拡張したり、カスタム関数を追加したりできます。
ルールセットをカスタマイズまたは置き換えるには、以下の手順を実行します。
- Visual Studio Code のアクティビティ バーから Azure API Center アイコンを選択します。
- 作業フォルダーのルートにある
.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 センターに API を登録する前に API 定義を改善することもできます。
リンティングの結果を確認します。 ルールセットに必要な調整を加え、想定通りの動作になるまでローカルでテストを続けます。
API センターにルールセットをデプロイする
カスタム ルールセットを API センターにデプロイするには、以下の手順を実行します。
- Visual Studio Code のアクティビティ バーから Azure API Center アイコンを選択します。
- [API Center] ペインで、ルールセットをカスタマイズした API センター リソースを展開します。
- [Rules]\(ルール\) を右クリックし、[Deploy Rules to API Center]\(API Center へルールをデプロイする\) を選択します。
ルールが API センターに正常にデプロイされると、メッセージが通知されます。 リンティング エンジンは、更新されたルールセットを使用して API 定義を分析します。
更新されたルールセットを使用したリンティングの結果を表示するには、ポータルで API 分析レポートを表示します。
関連するコンテンツ
- 既定の組み込みルールセットの詳細については、Spectral GitHub リポジトリを参照してください。
- API センターで API 分析を有効にする - セルフマネージド