APIOps CLIでAPI管理設定を管理する方法

適用対象: すべての API Management レベル

APIOps CLIはAzure API Management用のコード配置ツールです。 この記事では、API Managementの設定をローカルアーティファクトに抽出し、Git上でアーティファクトをレビューし、変更をプレビューし、承認されたアーティファクトをAPI Managementインスタンスに公開するために使います。 CLIはまた、APIOpsワークフローのためにGitHub ActionsやAzure Pipelinesファイルをスキャフォールドすることもできます。

これらのステップは、非本番のAPI管理インスタンスで検証可能な最小限のワークフローを提供します。 アーキテクチャおよび設計の指針については、「 APIOpsによる自動化API展開」を参照してください。

このワークフローを使って:

  • プルリクエストを通じてAPIの定義、ポリシー、その他のAPI管理設定を確認しましょう。
  • 承認された設定変更の監査可能な履歴を保持してください。
  • API管理環境間でレビューされたアーティファクトを促進。
  • 既存のインスタンスから抽出した構成から始め、またはコード内でCLI互換のアーティファクトを作成してください。

APIOps CLI は、DevOps と CI/CD を使用して API を公開する で説明されている API DevOps のアプローチを補完します。 CLI と、想定しているアーティファクト ワークフローは、本番デプロイに使用する前に、非本番環境で評価してください。

Prerequisites

  • Node.js バージョン22以降。
  • Azure CLIは、この記事のローカル認証ステップについてです。
  • Azureサブスクリプションと既存の非本番API管理インスタンスです。
  • API管理の成果物のためのGitリポジトリです。
  • API管理インスタンスへのアクセス権を持つアイデンティティ。 APIOps CLIの起動ガイダンスでは、抽出および公開ワークフローのAPI管理リソース範囲にAPI 管理サービス貢献 者と リーダー の役割が記載されています。

本番自動化では、可能な限り別個の最小権限IDを使用してください。 抽出アイデンティティはソースインスタンスへの読み取りアクセスが必要です。 パブリッシングアイデンティティは、ターゲットインスタンスを更新するために必要な権限のみを必要とします。

APIOps CLI をインストールする

@azure-tools/apiops-cli npm パッケージをインストールします。

npm install -g @azure-tools/apiops-cli

インストールされているバージョンを確認します。

apiops --version

承認したバージョンを記録し、CI/CD パイプライン向けに固定します。 アップグレード前に APIOps CLIの変更ログ を確認してください。

Azure に対して認証します

ローカル使用の場合は、Azure CLIでサインインし、非本番のAPI Managementインスタンスを含むサブスクリプションを選択してください:

az login
az account set --subscription <subscription-id>

APIOps CLIは DefaultAzureCredentialを使用しています。 Azure CLIの認証情報に加え、環境認証、ワークロード識別、マネージドアイデンティティ、Azure PowerShell、Azure Developer CLI認証情報もサポートしています。

CI/CDの場合は、クライアントシークレットの代わりにワークロードアイデンティティフェデレーションまたはマネージドアイデンティティを好みます。 認証情報、アクセストークン、サブスクリプションキー、または秘密の名前付き値をソース管理に入れてはいけません。 対応する認証オプションについては、 APIOps CLI認証ガイドをご覧ください。

アーティファクトリポジトリを準備する

API管理のアーティファクトを含むGitリポジトリのルートからAPIOpsのCLIコマンドを実行します。

GitHub Actionsのパイプラインや設定テンプレートをスキャフォールドするには、以下を実行します:

apiops init --ci github-actions --environments dev,prod --non-interactive

Azure Pipelines の場合、以下をご利用ください:

apiops init --ci azure-devops --environments dev,prod --non-interactive

このコマンドはパイプライン定義、抽出フィルターテンプレート、環境オーバーライドテンプレート、アイデンティティ設定ガイダンス、 apim-artifacts ディレクトリを作成します。 パイプラインをコミットまたは有効化する前に、生成されたすべてのファイルを確認してください。 既存のファイルがあるリポジトリで --force を使わないでください。コマンドで上書きされるファイルを確認しない限り。

すでにリポジトリやパイプラインの設計がある場合は、アーティファクトディレクトリを作成または選択し、抽出と公開コマンドを直接使うことができます。

初期のアーティファクトを作成する

リポジトリが所有するアーティファクトを特定するために、以下のいずれかの方法を選びましょう。

既存の構成を抽出する

既存のAPI管理インスタンスからベースラインを作成するには、その構成を抽出します:

apiops extract \
  --subscription-id <source-subscription-id> \
  --resource-group <source-resource-group> \
  --service-name <source-apim-name> \
  --output ./apim-artifacts

このコマンドは、 apim-artifactsの下で階層構造でJSON情報ファイル、XMLポリシーファイル、API仕様ファイルを作成します。 大規模なインスタンスの場合は、リポジトリが意図したリソースのみを管理するように 抽出フィルター を設定してください。

まずはコードファーストのアーティファクトから始めましょう

コードファーストのワークフローでは、 APIOps CLIアーティファクト形式を使用してOpenAPI仕様と必要なAPI管理情報およびポリシーファイルを追加してください。 既存のアプリケーションリポジトリのレイアウトやOpenAPIファイルだけで apiops publish準備ができているとは限りません。

アーティファクト形式に慣れていない場合は、まず非本番インスタンスから小さな参照APIを抽出してください。 得られたファイルをテンプレートとして使用し、コード ファースト ワークフローのガイダンスを確認してください。

遺物を見直せ

公開前に:

  1. 生成または作成されたファイルを確認し、リポジトリに管理したいリソースのみが含まれているか確認してください。
  2. API仕様、ポリシー、バックエンド、名前付き値、製品およびそれらの依存関係を確認しましょう。
  3. 他の環境に移動してはいけない環境固有の値は削除しましょう。 適切な場合は、レビュー済みの環境オーバーライドファイルやAzure Key Vault参照を使用してください。
  4. 資格情報や秘密の値を検索してください。 Extraction は、サポート対象のシークレット フィールドと認識されたポリシー パターンをマスクしますが、埋め込まれたシークレットをすべて検出できるとは限りません。 秘密や未解決の *** REDACTED *** 価値観を約束しないでください。
  5. アーティファクトをブランチにコミットし、プルリクエストを使って検証と承認を行います。

公開をプレビュー

非本番の対象インスタンスに対してドライランを実行してください。 ドライランでは、予定されている作成、更新、削除をそれらを適用せずに報告します:

apiops publish \
  --subscription-id <target-subscription-id> \
  --resource-group <target-resource-group> \
  --service-name <target-apim-name> \
  --source ./apim-artifacts \
  --dry-run

出力を見直し、予期せぬ変更や欠落した依存関係を解決します。 ドライランが成功しても、API の動作、ポリシー、権限、バックエンド接続をテストする代わりにはなりません。

Caution

最初のワークフローに --delete-unmatched を加えないでください。 そのオプションは、ソースアーティファクトに表示されていないターゲットインスタンス内のリソースを削除します。

レビューされた成果物を公開してください

プルリクエストが承認され、ドライランが成功したら、同じレビュー済み成果物を非本番ターゲットに発行します。

apiops publish \
  --subscription-id <target-subscription-id> \
  --resource-group <target-resource-group> \
  --service-name <target-apim-name> \
  --source ./apim-artifacts

公開後にターゲットインスタンスのAPIやポリシーを検証してください。 このワークフローを自動化する際には、承認されたコミットを公開し、組織の必要なチェックと承認でデプロイ環境を保護するようにパイプラインを設定しましょう。

次のステップ

  • 最終更新: