次の方法で共有

DevOps と CI/CD を使って API を発行する

  • [アーティクル]

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

企業における API の戦略的価値を考慮すると、DevOps の継続的インテグレーション (CI) とデプロイ (CD) 手法の採用は API 開発において重要な側面になっています。 この記事では、API の管理に DevOps の原則を採用するために必要な意思決定について説明します。

API DevOps は次の 3 つの部分で構成されています。

API DevOps のフローを示す図。

ここでは、API DevOps パイプラインの各部分について説明します。

[API の定義]

API 開発者は、API に適用する仕様、設定 (ログ、診断、バックエンドの設定など)、ポリシーを指定することで API 定義を作成します。 API 定義には、Azure API Management サービス上に API をプロビジョニングするために必要な情報を指定します。 仕様は、標準ベースの API 仕様 (WSDL、Open API、GraphQL など) に基づいたものにするか、Azure Resource Manager (ARM) API (たとえば、API と操作を記述した ARM テンプレート) を使って定義することができます。 API 定義は時間の経過と共に変わるため、"ソース コード" と考える必要があります。 必ず API 定義をソース コード管理下に置き、採用前に適切なレビューを行ってください。

API 定義の作成を支援するツールはいくつかあります。

  • Azure APIOps Toolkit は、git ソース コード管理システム (GitHub や Azure Repos など) 上に構築されたワークフローを提供します。 extractor を使って API 定義を作成し、それを "パブリッシャー" がターゲット API Management サービスに適用します。 APIOps は、現時点では REST と GraphQL の各 API をサポートしています。
  • dotnet-apim ツールを使うと、適切な形式の YAML 定義を、後でデプロイできる ARM テンプレートに変換することができます。 このツールは REST API に重点を置いています。
  • Terraform は、Azure 内のリソースを構成するための Azure Resource Manager の代替手段です。 ARM テンプレートの作成と同じ方法で、API を実装する Terraform 構成を (ポリシーと共に) 作成できます。

また、Visual Studio Code などのエディター用の IDE ベース ツールを使って、API の定義に必要な成果物を生成できます。 たとえば、Visual Studio Code Marketplace には、30 個を超える OpenAPI 仕様ファイルを編集するプラグインが掲載されています。 また、コード ジェネレーターを使って成果物を作成することもできます。 CADL 言語を使うと、大まかな構成要素を簡単に作成し、Open API のような標準の API 定義形式にコンパイルすることができます。

API の承認

API 定義が完成したら、開発者は API 定義を提出し、レビューと承認を受けます。 git ベースのソース コード管理システム (GitHub や Azure Repos など) を使っている場合は、pull request を使って提出することができます。 pull request は、API 定義に提案された変更内容を他のユーザーに通知するものです。 承認ゲートが確認されると、承認者は pull request をメイン リポジトリにマージして API 定義を運用環境にデプロイできることを示します。 pull request プロセスによって、開発者は承認プロセス中に見つかった問題を修正できます。

GitHub と Azure Repos のどちらでも、pull request が提出されたときに実行される承認パイプラインを構成できます。 次のようなツールを実行するように承認パイプラインを構成できます。

注意

Azure API は、ご自分の API ガイドラインの出発点として使用できる厳格なガイドライン セットに準拠する必要があります。 ガイドラインを適用するための Spectral 構成があります。

自動化ツールを実行した後は、人間の目で API 定義を確認します。 ツールですべての問題を検出できるわけではありません。 人間のレビュー担当者は、API 定義がセキュリティ、プライバシー、一貫性のガイドラインへの準拠など、API に関する組織の条件を満たしていることを確認します。

API の発行

API 定義はリリース パイプラインを通じて API Management サービスに発行されます。 API 定義の発行に使うツールは、API 定義の作成に使ったツールによって変わります。

  • Azure APIOps Toolkit を使う場合、このツールキットにはターゲット サービスに API 定義を書き込むパブリッシャーが含まれています。
  • dotnet-apim を使う場合、API 定義は ARM テンプレートで表現されます。 Azure Pipelines と GitHub Actions の場合、ARM テンプレートをデプロイするタスクを使用できます。
  • Terraform を使う場合は、CLI ツールを使ってサービス上に API 定義をデプロイします。 Azure Pipelines と GitHub Actions 用のタスクを使用できます。

他のソース コード管理、CI/CD システムを使用できますか?

はい。 説明したプロセスは、どのようなソース コード管理システムでも機能します (ただし、APIOps には git ベースのソース コード管理システムが必要です)。 同様に、チェックインによってトリガーされ、Azure と通信するコマンドライン ツールを実行できるのであれば、任意の CI/CD プラットフォームでも使用できます。

ベスト プラクティス

API の発行に使う DevOps パイプラインを設定するための業界標準はありません。また、ここで紹介したどのツールもすべての状況で機能するわけではありません。 ただし、ほとんどの状況では、以下のツールとサービスを組み合わせて使うことでカバーできることがわかっています。

  • Azure Repos を使うと API 定義を git リポジトリに格納できます。
  • Azure Pipelines は、自動化された API 承認と API 発行プロセスを実行します。
  • Azure APIOps Toolkit には、API を発行するためのツールとワークフローが用意されています。

お客様のデプロイで最大の成功を収めています。また、次の方法を推奨しています。

  • GitHub または Azure Repos をソース コード管理システムとして設定します。 この選択によって、パイプライン ランナーの選択も決まります。 GitHub の場合は Azure Pipelines または GitHub Actions を使用できますが、Azure Repos の場合は Azure Pipelines を使う必要があります。
  • 各 API 開発者用に Azure API Management サービスを設定し、API サービスと一緒に API 定義を開発できるようにします。 サービスを作成するときには、従量課金または開発者 SKU を使います。
  • ポリシー フラグメントを使って、開発者が各 API にのために作成する必要がある新しいポリシーを減らします。
  • 名前付きの値とバックエンドを使用して、ポリシーが汎用的であり、任意の API Management インスタンスに適用できることを確認します。
  • Azure APIOps Toolkit を使って、開発者サービスから有効な API 定義を抽出します。
  • 各 pull request に対して実行する API 承認プロセスを設定します。 API 承認プロセスには、破壊的変更の検出、リンティング、自動化 API テストを含める必要があります。
  • Azure APIOps Toolkit パブリッシャーを使って、運用 API Management サービスに API を発行します。

APIOps を使った CI/CD デプロイ パイプラインを構成して実行する方法の詳細については、Azure アーキテクチャ センターの「APIOps を使って API デプロイを自動化する」を参照してください。

リファレンス

  • Azure DevOps Services には、Azure Repos と Azure Pipelines が含まれています。
  • Azure APIOps Toolkit には、API Management DevOps のためのワークフローが用意されています。
  • Spectral には、OpenAPI 仕様用のリンターが用意されています。
  • openapi-diff には、OpenAPI v3 定義用の破壊的変更検出機能が用意されています。
  • Newman には Postman コレクション用の自動テスト ランナーが用意されています。