Share via

API センターで API ガバナンスのリンティングと分析を有効にする

  • [アーティクル]

この記事では、リンティングを有効にして、組織の API スタイル ルールに対する API 定義の準拠を、組織の API センターで分析する方法について説明します。 リンティングによって、API センターでアクセスできる分析レポートが生成されます。 API のリンティングと分析を使って、API 定義の一般的なエラーと不整合を検出します。

シナリオの概要

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

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

Azure API Center での API リンティングのしくみを示す図。

  1. API 定義に対して Spectral リンティング エンジンを実行する Azure Functions アプリをデプロイします。

  2. Azure API センターで、関数アプリをトリガーするようにイベント サブスクリプションを構成します。

  3. API センターで API 定義を追加または置換することによって、イベントがトリガーされます。

  4. イベントを受信すると、関数アプリは Spectral リンティング エンジンを呼び出します。

  5. リンティング エンジンは、定義で定義されている API が組織の API スタイル ガイドに準拠していることを確認し、レポートを生成します。

  6. 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 拡張機能の詳細については、こちらを参照してください。

    Note

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

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

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

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

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

  1. GitHub リポジトリをクローンし、Visual Studio Code で開きます。

  2. ディレクトリをリポジトリ内の APICenter-Analyzer フォルダーに変更します。

  3. resources/rulesets フォルダーに、oas.yaml ファイルがあります。 このファイルは、現在の API スタイル ガイドを反映しており、組織のニーズと要件に基づいて変更できます。

  4. 次のコマンドを使って、Azure Developer CLI と Azure CLI で認証します。

    azd auth login

az login

  5. 次のコマンドを実行して、リンティング インフラストラクチャを Azure サブスクリプションにデプロイします。

    azd up

  6. プロンプトに従って、環境名や API センター名などの必要なデプロイ情報と設定を指定します。 詳細については、「Azure Developer CLI (azd) を使ったサンプルの実行」を参照してください。

    Note

    デプロイには数分かかることがあります。

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

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

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

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

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

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

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

  1. GitHub リポジトリをクローンし、Visual Studio Code で開きます。

  2. resources/rulesets フォルダーに、oas.yaml ファイルがあります。 このファイルは、現在の API スタイル ガイドを反映しており、組織のニーズと要件に基づいて変更できます。

  3. 必要なら、関数アプリをローカル環境で実行してテストします。 詳しくは、リポジトリの README ファイルをご覧ください。

  4. 関数アプリを Azure にデプロイします。 手順については、「クイックスタート: Visual Studio Code と TypeScript を使用して Azure に関数を作成する」をご覧ください。

    Note

    関数アプリのデプロイには数分かかる場合があります。

  5. Azure portal にサインインして、関数アプリに移動します。

  6. [概要] ページで、次の詳細を確認します。

    • 関数アプリの [状態] が [実行中] であることを確認します。
    • [関数] で、apicenter-analyzer 関数の [状態] が [有効] であることを確認します。

    ポータルでの関数アプリのスクリーンショット。

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

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

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

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

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

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

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

  1. Azure portal で API センターに移動し、[イベント] を選びます。

  2. [作業の開始] タブで、[Azure 関数] を選びます。

  3. [イベント サブスクリプションの作成] ページで、次のようにします。

    1. イベント サブスクリプションのわかりやすい [名前] を入力して、[イベント グリッド スキーマ] を選びます。

    2. [トピックの詳細] で、任意の [システム トピック名] を入力します。

    3. [イベントの種類] で、次のイベントを選びます。

      • API definition added (API 定義が追加された)
      • API definition updated (API 定義が更新された)

    4. [エンドポイントの詳細] で、[Azure 関数] > [エンドポイントの構成] を選びます。

    5. [Azure 関数の選択] ページで、関数アプリと構成した apicenter-linter 関数を選びます。 [選択の確認] をクリックします。

    6. ［作成］ を選択します

      ポータルでイベント サブスクリプションを作成する際のスクリーンショット。

  4. [イベント サブスクリプション] タブを選んで、[最新の情報に更新] を選びます。 イベント サブスクリプションの [プロビジョニング状態] が、[成功] であることを確認します。

    ポータルでのイベント サブスクリプションの状態を示すスクリーンショット。

Note

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

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

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

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

  1. API センターに移動し、左側のメニューで [イベント] を選びます。

  2. [イベント サブスクリプション] タブを選んで、関数アプリのイベント サブスクリプションを選びます。

  3. メトリックを調べて、イベント サブスクリプションがトリガーされ、リンティングが正常に呼び出されたことを確認します。

    ポータルでのイベント サブスクリプション用のメトリックを示すスクリーンショット。

    Note

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

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

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

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

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

API 定義の分析レポート

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

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

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

ポータルでの API 分析レポートを示すスクリーンショット。

API 分析の概要

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

  1. ポータルで、API Center に移動します。

  2. 左側のメニューの [ガバナンス] で、[API 分析] を選択します。 概要が表示されます。

    ポータルでの API 分析の概要を示すスクリーンショット。

関連するコンテンツ

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