組織の API センターには、組織のスタイル ルールに準拠するために API 定義を分析し、個別および概要レポートの両方を生成するための、組み込みで Microsoft マネージドのリンティング機能 (プレビュー) が用意されています。 API 分析は、API 定義の一般的なエラーと不整合を特定して修正するのに役立ちます。
API 分析を使用すると:
- API 定義を追加または更新するたびに、Azure API Center によって API 定義が自動的に分析されます。 API 定義のリンティングは、
spectral:oasルールセット (API スタイル ガイド) を使用して既定で実行されます。 - Azure portal で API 分析レポートが生成され、API 定義がスタイル ガイドにどの程度準拠しているかが表示されます。
- 分析プロファイルを使用して、分析される API のルールセットとフィルター条件を指定します。 Visual Studio Code用の Azure API Center 拡張機能を使用して、プロファイルのルールセットをカスタマイズします。
重要
必要に応じて、カスタム Azure 関数を使用して、セルフマネージドのリンティングと分析を有効にして、組み込みの機能をオーバーライドできます。 マネージド API 分析を有効にする前に、セルフマネージド リンティングに使用するすべての関数を無効にしてください。
制限事項
- 現在、JSON または YAML 形式の OpenAPI と AsyncAPI 仕様ドキュメントのみが分析されます。
- 分析プロファイルの数と分析される 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]\(分析\) を選択して表示することもできます。
分析プロファイルの管理
Azure API Center では、api のリンティングと分析に analysis プロファイル を使用します。 分析プロファイルでは、ルール セットを指定し、必要に応じて、分析される API の条件をフィルター処理します。 既定の分析プロファイルでは、すべての OpenAPI および AsyncAPI 定義に spectral:oas ルール セットが適用されます。
ルールセットをカスタマイズし、既定のプロファイルでフィルター条件を定義することも、新しいプロファイルを作成することもできます。 たとえば、開発中の API には 1 つのプロファイルを使用し、運用環境の API には別のプロファイルを使用できます。
メモ
API センターの Standard プランでは、最大 3 つの分析プロファイルを作成できます。 Free プランでは、1 つのプロファイルのみがサポートされます。
分析プロファイルを作成するには:
- Azure portal で、API センターに移動します。
- 左側のメニューの [ ガバナンス] で、[ API 分析>管理分析プロファイル>+ 分析プロファイルの作成を選択します。
- [ 新しい分析プロファイルの作成 ] ウィンドウで、プロファイルの 名前 と 説明 を入力します。
- ルールセットでは、ルールセットのアナライザーの種類 (リンティング エンジン) が表示されます。 現在サポートされているのはスペクトラルのみです。
- [ フィルター条件の定義] で、プロファイルが適用される API 定義の 1 つ以上のフィルター条件を追加します。
- 作成を選択します。
プロファイルが作成され、ルールセットのスキャフォールドが作成されます。 現在のルールセットを表示するには、プロファイルを選択し、コンテキスト (...) メニューで [ ルールセットの表示] を選択します。
ルールセットをカスタマイズするには、次のセクションに進みます。
プロファイルのルール セットをカスタマイズする
Azure API Center のVisual Studio Code拡張機能を使用して、プロファイルのルールセットをカスタマイズします。 ルールセットをカスタマイズしてローカルでテストしたら、API センターにデプロイし直すことができます。
- Visual Studio Code のアクティビティ バーから Azure API Center アイコンを選択します。
- [API センター] ウィンドウで、使用している API センター リソースを展開し、[ プロファイル] を展開します。
- 変更するプロファイルを展開し、
ruleset.yaml選択します。 - 必要に応じてコンテンツを変更または置き換えます。
- 変更を
ruleset.yamlに保存します。
ローカルでルールセットをテストする
カスタム ルールセットを 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.yamlファイルを指定します。 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 センター リソースを展開します。
- [ プロファイル] を展開します。
- ルールセットをカスタマイズしたプロファイルを右クリックし、[ Deploy Rules to API Center]\(API センターへのルールのデプロイ\) を選択します。
ルールが API センターに正常にデプロイされると、メッセージが通知されます。 リンティング エンジンは、更新されたルールセットを使用して、プロファイル内の API 定義を分析します。
更新されたルールセットを使用したリンティングの結果を表示するには、ポータルで API 分析レポートを表示します。
関連するコンテンツ
- 既定の組み込みルールセットの詳細については、Spectral GitHub リポジトリを参照してください。
- API センターで API 分析を有効にする - セルフマネージド