API センターで API 分析を有効にする - セルフマネージド

[アーティクル]
12/03/2024

この記事では、リンティングエンジンとトリガーを手動で設定して Azure API Center で API 分析を有効にする方法について説明します。これらの機能により、API 定義が組織のスタイルルールに準拠しているかどうかを分析し、個々のレポートと概要レポートの両方を生成できます。 API 分析は、API 定義の一般的なエラーと不整合を特定して修正するのに役立ちます。

Note

プレビューでは、Azure API Center によって、API 分析のための既定のリンティングエンジンと依存関係が自動的に構成されます。この記事の説明に従って自己管理分析を有効にすると、これらの組み込み機能をオーバーライドすることになります。

シナリオの概要

このシナリオでは、オープンソースのリンティングエンジンである Spectral を使って、API センターで API 定義を分析します。 Azure Functions アプリは、API センターでのイベントに応答してリンティングエンジンを実行します。 Spectral は、JSON または YAML の仕様ドキュメントで定義されている API が、カスタマイズ可能な API スタイルガイドのルールに準拠していることをチェックします。 API センターで表示できる分析レポートが生成されます。

次の図は、API センターでリンティングと分析を有効にする手順を示したものです。

API 定義に対して Spectral リンティングエンジンを実行する Azure Functions アプリをデプロイします。
Azure API センターで、関数アプリをトリガーするようにイベントサブスクリプションを構成します。
API センターで API 定義を追加または置換することによって、イベントがトリガーされます。
イベントを受信すると、関数アプリは Spectral リンティングエンジンを呼び出します。
リンティングエンジンは、定義で定義されている API が組織の API スタイルガイドに準拠していることを確認し、レポートを生成します。
API センターで分析レポートを確認します。

リンティングエンジンとイベントサブスクリプションをデプロイするオプション

この記事では、API センターにリンティングエンジンとイベントサブスクリプションをデプロイする 2 つのオプションを示します。

自動デプロイ - Azure Developer CLI (azd) を使って、リンティングインフラストラクチャを 1 ステップでデプロイします。合理化されたデプロイプロセスのためには、このオプションをお勧めします。
手動デプロイ - ステップバイステップのガイダンスに従って、Azure Functions アプリをデプロイし、イベントサブスクリプションを構成します。リソースを手動でデプロイおよび管理する場合は、このオプションをお勧めします。

制限事項

現在、リンティングでサポートされているのは、OpenAPI や AsyncAPI の仕様ドキュメントなどの、JSON または YAML の仕様ファイルのみです。
既定では、リンティングエンジンは組み込みの spectral:oas ルールセットを使います。ルールセットの拡張や、カスタム API スタイルガイドの作成については、Spectral の GitHub リポジトリをご覧ください。
リンティングを呼び出す Azure 関数アプリは個別に課金され、ユーザーがその管理と保守を行います。

前提条件

Azure サブスクリプション内の API センター。まだ作成していない場合は、「クイックスタート: API センターを作成する」を参照してください。
サブスクリプションに登録されている Event Grid リソースプロバイダー。 Event Grid リソースプロバイダーを登録する必要がある場合は、「Azure Event Grid を使用して、パートナーによって発行されたイベントをサブスクライブする」をご覧ください。
Azure CLI の場合
- Azure Cloud Shell で Bash 環境を使用します。詳細については、「Azure Cloud Shell の Bash のクイックスタート」を参照してください。
- CLI リファレンスコマンドをローカルで実行する場合、Azure CLI をインストールします。 Windows または macOS で実行している場合は、Docker コンテナーで Azure CLI を実行することを検討してください。詳細については、「Docker コンテナーで Azure CLI を実行する方法」を参照してください。
  - ローカルインストールを使用する場合は、az login コマンドを使用して Azure CLI にサインインします。認証プロセスを完了するには、ターミナルに表示される手順に従います。その他のサインインオプションについては、Azure CLI でのサインインに関するページを参照してください。
  - 初回使用時にインストールを求められたら、Azure CLI 拡張機能をインストールします。拡張機能の詳細については、Azure CLI で拡張機能を使用する方法に関するページを参照してください。
  - az version を実行し、インストールされているバージョンおよび依存ライブラリを検索します。最新バージョンにアップグレードするには、az upgrade を実行します。
Note

az apic コマンドには、apic-extensionAzure CLI 拡張機能が必要です。 az apic コマンドを使用していない場合は、最初の az apic コマンドの実行時に拡張機能を動的にインストールするか、拡張機能を手動でインストールできます。 Azure CLI 拡張機能の詳細については、こちらを参照してください。

apic-extension の最新の変更と更新については、リリースノートを参照してください。

Note

この記事の Azure CLI コマンドの例は、PowerShell または bash シェルで実行できます。変数の構文が異なるために必要な場合は、2 つのシェルで個別のコマンド例が提供されています。

`azd` Azure Functions アプリのデプロイとイベントサブスクリプション

このセクションでは、Azure Developer CLI を使って、API センターでリンティングと分析を可能にする Azure Functions アプリとイベントサブスクリプションを構成する自動化された手順について説明します。リソースを手動で構成することもできます。

このオプションのその他の前提条件

Azure Developer CLI (azd)

`azd` を使ってサンプルを実行します

GitHub リポジトリをクローンし、Visual Studio Code で開きます。
ディレクトリをリポジトリ内の APICenter-Analyzer フォルダーに変更します。
resources/rulesets フォルダーに、oas.yaml ファイルがあります。このファイルは、現在の API スタイルガイドを反映しており、組織のニーズと要件に基づいて変更できます。
次のコマンドを使って、Azure Developer CLI と Azure CLI で認証します。
```
azd auth login

az login
```
次のコマンドを実行して、リンティングインフラストラクチャを Azure サブスクリプションにデプロイします。
```
azd up
```
プロンプトに従って、環境名や API センター名などの必要なデプロイ情報と設定を指定します。詳細については、「Azure Developer CLI (azd) を使ったサンプルの実行」を参照してください。

Note

デプロイには数分かかることがあります。
デプロイが完了したら、Azure portal で API センターに移動します。左側のメニューで [イベント]>[イベントサブスクリプション] を選び、作成されたイベントサブスクリプションを表示します。

これで、API 定義ファイルを API センターにアップロードしてイベントサブスクリプションをトリガーし、リンティングエンジンを実行できるようになりました。

Azure Functions アプリとイベントサブスクリプションを構成する手動の手順

このセクションでは、API センターでリンティングと分析を有効にするために Azure Functions アプリとイベントサブスクリプションを構成するための手動のデプロイ手順について説明します。 Azure Developer CLI を使って自動デプロイすることもできます。

このオプションのその他の前提条件

Azure Functions 拡張機能 v1.10.4 以降を含む Visual Studio Code。

ステップ 1. Azure Functions アプリをデプロイする

API 定義に対してリンティング関数を実行する Azure Functions アプリをデプロイするには:

GitHub リポジトリをクローンし、Visual Studio Code で開きます。
resources/rulesets フォルダーに、oas.yaml ファイルがあります。このファイルは、現在の API スタイルガイドを反映しており、組織のニーズと要件に基づいて変更できます。
必要なら、関数アプリをローカル環境で実行してテストします。詳しくは、リポジトリの README ファイルをご覧ください。
関数アプリを Azure にデプロイします。手順については、「クイックスタート: Visual Studio Code と TypeScript を使用して Azure に関数を作成する」をご覧ください。

Note

関数アプリのデプロイには数分かかる場合があります。
Azure portal にサインインして、関数アプリに移動します。
[概要] ページで、次の詳細を確認します。
- 関数アプリの [状態] が [実行中] であることを確認します。
- [関数] で、apicenter-analyzer 関数の [状態] が [有効] であることを確認します。

ステップ 2. 関数アプリでマネージド ID を構成する

関数アプリが API センターにアクセスできるようにするには、関数アプリ用にマネージド ID を構成します。次の手順では、Azure portal または Azure CLI を使って、関数アプリのシステム割り当てマネージド ID を有効にして構成する方法を示します。

ポータル
Azure CLI

Azure portal で関数アプリに移動し、[設定] セクションの下にある [ID] を選びます。
[システムが割り当て済み] タブで、[状態] を [オン] に設定してから、[保存] を選びます。

マネージド ID が有効になったので、API センターにアクセスするための Azure API Center コンプライアンスマネージャーロールをそれに割り当てます。

Azure portal で API センターに移動し、[アクセス制御 (IAM)] を選びます。
[+ 追加] > [ロールの割り当てを追加] を選びます。
[ジョブ関数ロール] を選んでから、[Azure API Center コンプライアンスマネージャー] を選びます。 [次へ] を選択します。
[メンバー] ページの [アクセスの割り当て先] で、[マネージド ID] > [+ メンバーの選択] を選びます。
[マネージド ID の選択] ページで、関数アプリのマネージド ID を検索して選びます。 [選択]、[次へ] の順にクリックします。
ロールの割り当てを確認し、[レビューと割り当て] を選択します。

az functionapp identity assign コマンドを使って、関数アプリのシステム割り当て ID を有効にします。 <function-app-name> と <resource-group-name> を、実際の関数アプリの名前とリソースグループ名に置き換えます。次のコマンドは、システム割り当てマネージド ID のプリンシパル ID を principalID 変数に格納します。

#! /bin/bash
principalID=$(az functionapp identity assign --name <function-app-name> \
    --resource-group <resource-group-name> --identities [system] \
    --query "principalId" --output tsv)

# PowerShell syntax
$principalID=$(az functionapp identity assign --name <function-app-name> `
    --resource-group <resource-group-name> --identities [system] `
    --query "principalId" --output tsv)

API センターのリソース ID を取得します。 <apic-name> と <resource-group-name> を、実際の API センターの名前とリソースグループ名に置き換えます。

#! /bin/bash
apicID=$(az apic show --name <apic-name> --resource-group <resource-group-name> \
    --query "id" --output tsv)

# PowerShell syntax
$apicID=$(az apic show --name <apic-name> --resource-group <resource-group-name> `
    --query "id" --output tsv)

API センターで az role assignment create コマンドを使って、関数アプリのマネージド ID に Azure API Center コンプライアンスマネージャーロールを割り当てます。

#! /bin/bash
az role assignment create \
    --role "Azure API Center Compliance Manager" \
    --assignee-object-id $principalID \
    --assignee-principal-type ServicePrincipal \
    --scope $apicID

# PowerShell syntax
az role assignment create `
    --role "Azure API Center Compliance Manager" `
    --assignee-object-id $principalID `
    --assignee-principal-type ServicePrincipal `
    --scope $apicID

手順 3. API センターでイベントサブスクリプションを構成する

次に、API センターで、API 定義ファイルがアップロードまたは更新されたときに関数アプリをトリガーするためのイベントサブスクリプションを作成します。次の手順では、Azure portal または Azure CLI を使ってイベントサブスクリプションを作成する方法を示します。

ポータル
Azure CLI

Azure portal で API センターに移動し、[イベント] を選びます。
[作業の開始] タブで、[Azure 関数] を選びます。
[イベントサブスクリプションの作成] ページで、次のようにします。
1. イベントサブスクリプションのわかりやすい [名前] を入力して、[イベントグリッドスキーマ] を選びます。
2. [トピックの詳細] で、任意の [システムトピック名] を入力します。
3. [イベントの種類] で、次のイベントを選びます。
  - API definition added (API 定義が追加された)
  - API definition updated (API 定義が更新された)
4. [エンドポイントの詳細] で、[Azure 関数] > [エンドポイントの構成] を選びます。
5. [Azure 関数の選択] ページで、関数アプリと構成した apicenter-linter 関数を選びます。 [選択の確認] をクリックします。
6. ［作成］ を選択します
[イベントサブスクリプション] タブを選んで、[最新の情報に更新] を選びます。イベントサブスクリプションの [プロビジョニング状態] が、[成功] であることを確認します。

API センターのリソース ID を取得します。 <apic-name> と <resource-group-name> を、実際の API センターの名前とリソースグループ名に置き換えます。

#! /bin/bash
apicID=$(az apic show --name <apic-name> --resource-group <resource-group-name> \
    --query "id" --output tsv)

# PowerShell syntax
$apicID=$(az apic show --name <apic-name> --resource-group <resource-group-name> `
    --query "id" --output tsv)

関数アプリで関数のリソース ID を取得します。この例での関数名は apicenter-analyzer です。 <function-app-name> と <resource-group-name> を、実際の関数アプリの名前とリソースグループ名に置き換えます。

#! /bin/bash
functionID=$(az functionapp function show --name <function-app-name> \
    --function-name apicenter-analyzer --resource-group <resource-group-name> \
    --query "id" --output tsv)

# PowerShell syntax
$functionID=$(az functionapp function show --name <function-app-name> `
    --function-name apicenter-analyzer --resource-group <resource-group-name> `
    --query "id" --output tsv)

az eventgrid event-subscription create コマンドを使って、イベントサブスクリプションを作成します。作成されたサブスクリプションには、API 定義の追加または更新に対するイベントが含まれます。

#! /bin/bash
az eventgrid event-subscription create --name MyEventSubscription \
    --source-resource-id "$apicID" --endpoint "$functionID" \
    --endpoint-type azurefunction --included-event-types \
    Microsoft.ApiCenter.ApiDefinitionAdded Microsoft.ApiCenter.ApiDefinitionUpdated

# PowerShell syntax
az eventgrid event-subscription create --name MyEventSubscription `
    --source-resource-id "$apicID" --endpoint "$functionID" `
    --endpoint-type azurefunction --included-event-types `
    Microsoft.ApiCenter.ApiDefinitionAdded Microsoft.ApiCenter.ApiDefinitionUpdated

コマンドの出力で、イベントサブスクリプションの詳細が示されます。 az eventgrid event-subscription show コマンドを使って詳細を取得することもできます。次に例を示します。

az eventgrid event-subscription show --name MyEventSubscription --source-resource-id "$apicID"

Note

イベントサブスクリプションが関数アプリに反映されるまでに少し時間がかかる場合があります。

API センターでイベントをトリガーする

イベントサブスクリプションをテストするため、API センターで API バージョンに関連付けられている API 定義ファイルをアップロードまたは更新してみます。たとえば、OpenAPI または AsyncAPI のドキュメントをアップロードします。イベントサブスクリプションがトリガーされた後、関数アプリによって API リンティングエンジンが呼び出されて、API 定義が分析されます。

API、API バージョン、API 定義を API センターに追加する手順について詳しくは、チュートリアル: API センターでの API の登録に関する記事をご覧ください。
Azure CLI を使って API 定義ファイルをアップロードして API を作成するには、「仕様ファイルから API を登録する」をご覧ください。

イベントサブスクリプションがトリガーされたことを確認するには:

API センターに移動し、左側のメニューで [イベント] を選びます。
[イベントサブスクリプション] タブを選んで、関数アプリのイベントサブスクリプションを選びます。
メトリックを調べて、イベントサブスクリプションがトリガーされ、リンティングが正常に呼び出されたことを確認します。

Note

メトリックが表示されるまでに数分かかる場合があります。

API 定義を分析した後、リンティングエンジンは構成されている API スタイルガイドに基づいてレポートを生成します。

API 分析レポートを表示する

API 定義の分析レポートは、Azure portal で表示できます。 API 定義が分析された後、構成されている API スタイルガイドに基づいて、エラー、警告、情報の一覧がレポートに表示されます。

ポータルでは、API センター内のすべての API 定義の分析レポートの概要を表示することもできます。

API 定義の分析レポート

API センターで API 定義の分析レポートを表示するには:

ポータルで、API 定義を追加または更新した API センターの API バージョンに移動します。
左側のメニューにある [詳細] で、[定義] を選びます。
アップロードまたは更新した API 定義を選びます。
[分析] タブを選びます。

[API Analysis Report] (API 分析レポート) が開き、構成されている API スタイルガイドに基づいて、API 定義とエラー、警告、情報が表示されます。次に示すスクリーンショットは、API 分析レポートの例です。

API 分析の概要

API センター内のすべての API 定義に対する分析レポートの概要を表示するには:

ポータルで、API Center に移動します。
左側のメニューの [ガバナンス] で、[API 分析] を選択します。概要が表示されます。

Event Grid の詳細を確認してください。

次の方法で共有

API センターで API 分析を有効にする - セルフマネージド

シナリオの概要

リンティングエンジンとイベントサブスクリプションをデプロイするオプション

制限事項

前提条件

`azd` Azure Functions アプリのデプロイとイベントサブスクリプション

このオプションのその他の前提条件

`azd` を使ってサンプルを実行します

Azure Functions アプリとイベントサブスクリプションを構成する手動の手順

このオプションのその他の前提条件

ステップ 1. Azure Functions アプリをデプロイする

ステップ 2. 関数アプリでマネージド ID を構成する

手順 3. API センターでイベントサブスクリプションを構成する

API センターでイベントをトリガーする

API 分析レポートを表示する

API 定義の分析レポート

API 分析の概要

フィードバック

その他のリソース

次の方法で共有

API センターで API 分析を有効にする - セルフマネージド

シナリオの概要

リンティング エンジンとイベント サブスクリプションをデプロイするオプション

制限事項

前提条件

azd Azure Functions アプリのデプロイとイベント サブスクリプション

このオプションのその他の前提条件

azd を使ってサンプルを実行します

Azure Functions アプリとイベント サブスクリプションを構成する手動の手順

このオプションのその他の前提条件

ステップ 1. Azure Functions アプリをデプロイする

ステップ 2. 関数アプリでマネージド ID を構成する

手順 3. API センターでイベント サブスクリプションを構成する

API センターでイベントをトリガーする

API 分析レポートを表示する

API 定義の分析レポート

API 分析の概要

関連するコンテンツ

フィードバック

その他のリソース

リンティングエンジンとイベントサブスクリプションをデプロイするオプション

`azd` Azure Functions アプリのデプロイとイベントサブスクリプション

`azd` を使ってサンプルを実行します

Azure Functions アプリとイベントサブスクリプションを構成する手動の手順

手順 3. API センターでイベントサブスクリプションを構成する