API ガバナンス

  • 5 分

API ガバナンスは、組織のすべての API に対して標準、ポリシー、プロセスを広範囲に定義して適用するプラクティスとして定義されます。 API Center を使うと、次のことによってそれを実現できます。

  • API のタイトル、説明、バージョン、定義、デプロイなどの API メタデータの追跡。 さらに、独自のカスタム API メタデータ (ライブ サイト情報、ソース管理リポジトリなど) を指定して、組織にとって重要なメタデータを追跡できます (前のモジュールで示しました)。
  • すべての API が組織の API 設計哲学に準拠するように設計されていることの保証
  • API コンシューマーへのシームレスなロールアウトと通信のための、破壊的変更が含まれる API バージョンのタイムリーな検出の保証

このユニットでは、API Center によって大規模な API ガバナンスの構成がどのように実現されるかを見ていきます。

前提条件

API Center を使って API を管理するには、次のことを行う必要があります。

  1. Azure CLI をインストールします。
  2. Azure Developer CLI (azd) をインストールします。
  3. サブスクリプションに Event Grid リソース プロバイダーを登録します。 Event Grid リソース プロバイダーを登録する必要がある場合は、「Azure Event Grid を使用して、パートナーによって発行されたイベントをサブスクライブする」をご覧ください。

API 設計の適合性

API プラットフォーム チームは、API プロデューサー向けの一連のガイドラインの定義を担当することがよくあります。 API Center を使うと、Spectral オープンソース リンティング エンジンでルールを定義して、API ガイドラインを体系化できます。 API Center には提供されている Spectral ルールが既定で付属していますが、独自に作成したり、オープンソース ルールセットの大規模なコミュニティを活用したりできます。 API 定義がアップロードされるたびに、API Center は提供されているルールセットを使って Spectral リンターを実行し、API 定義が規則に準拠していることをチェックします。 API センターで表示できる API コンプライアンスのレポートが生成されます。

組織向けに API 設計の適合性を構成するには:

  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 portal の API 分析コンプライアンス レポートを示すスクリーンショット。

API ガバナンスをシフトレフトする

最も成功するガバナンス イニシアティブには、常に開発者自身が含まれます。 従来のシフトレフト原則を適用すると、API プラットフォーム チームは、開発サイクルの早い段階で、API を公開するために満たす必要がある要件を、API プロデューサーに正確に認識させることができます。 これにより、開発サイクルの後半で準拠していない API を修復する必要が減り、貴重な開発時間を節約できます。

API プロデューサーは、Visual Studio Code 用の API Center 拡張機能を使って、Visual Studio Code で API がビルドされている間に直接、API 設計の適合性チェックを実行できます。 さらに、API 作成者は破壊的変更検出機能を使用して、変更が API 利用者にとっての破壊的変更となる可能性があるケースを検出できます。

Visual Studio Code での API 設計の適合性

API Center 拡張機能は、OpenAPI とカスタム ルールセットをサポートする JSON/YAML リンターである Spectral と統合されています。 開発者は、この拡張機能を使って、提供または推奨される API スタイル ガイドに厳密に従い、異なる複数のチームによって開発されているすべての API の一貫性を確保できます。

Note

この機能を使うには、API Center と Spectral 拡張機能をインストールする必要があります。

アクティブにするには次のようにします。

  1. Ctrl + Shift + P のキーボード ショートカットを使ってコマンド パレットを開きます。 「Azure API Center: Set active API Style Guide」と入力して、Enter キーを押します。
  2. 提供されている既定の規則のいずれかを選択するか、組織にスタイル ガイドが既に用意されている場合は、[ローカル ファイルの選択] または [リモート URL の入力] を使用して、Visual Studio Code でアクティブなルール セットを指定します。 Enter キーを押します。 VS Code で API スタイル ガイドを設定するオプションを示すスクリーンショット

アクティブな API スタイル ガイドが設定された後は、OpenAPI または AsyncAPI ベースの仕様ファイルを開くと、Visual Studio Code でローカル リンティング操作がトリガーされます。 結果は、エディターのインラインと、[問題] ウィンドウ ([表示] >[問題] または Ctrl + Shift + M) の両方に表示されます。VS Code でのリンティング チェックの結果を示すスクリーンショット

Visual Studio Code での破壊的変更の検出

コンシューマーの運用ワークフローを中断する API バージョンを出荷すると、信頼性がなくなり、信頼が失われます。 API Center 拡張機能で Optic を使うと、開発者は、任意の 2 つの API バージョンを簡単に比較し、API に発生した破壊的変更をデプロイ前に検出できます。

Note

この機能を使うには、Optic をインストールする必要があります。 次のコマンドを使ってインストールします。

*npm install -g @useoptic/optic*

このとき、次のようになります。

  1. Ctrl + Shift + P のキーボード ショートカットを使ってコマンド パレットを開きます。 「Azure API Center: Detect Breaking Change (破壊的変更の検出)」と入力し、Enter キーを押します。
  2. 比較する最初の API 仕様ドキュメントを選択します。 有効なオプションには、API センターで見つかる API 仕様、ローカル ファイル、または Visual Studio Code のアクティブなエディターが含まれます。
  3. 比較する 2 つ目の API 仕様ドキュメントを選択します。 有効なオプションには、API センターで見つかる API 仕様、ローカル ファイル、または Visual Studio Code のアクティブなエディターが含まれます。

Visual Studio Code で、2 つの API 仕様間の差分ビューが開きます。 破壊的変更は、エディターのインラインと、[問題] ウィンドウ ([表示] >[問題] または Ctrl + Shift + M) の両方に表示されます。VS Code での破壊的変更の検出を示すスクリーンショット