次の方法で共有

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、 OpenAPI、 GraphQL など) に基づいているか、Azure Resource Manager (ARM) API (API と操作を記述する ARM テンプレートなど) を使用して定義される場合があります。 API 定義は時間の経過と同時に変化し、"ソース コード" と見なす必要があります。API 定義がソース コード管理下に格納され、導入前に適切なレビューがあることを確認します。

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

  • Azure APIOps Toolkit は、git ソース コード管理システム (GitHub や Azure Repos など) 上に構築されたワークフローを提供します。 エクストラクターを使用して 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 で OpenAPI 仕様ファイルを編集するためのプラグインは 90 を超えています 。 また、コード ジェネレーターを使って成果物を作成することもできます。 TypeSpec 言語を使用すると、クラウド サービスの API と図形を定義でき、高度に拡張可能であり、REST、OpenAPI、gRPC、およびその他のプロトコルで共通する API 図形を記述できるプリミティブを使用できます。

API の承認

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

GitHub と Azure Repos の両方で、プル要求の送信時に実行される承認パイプラインを構成できます。 次のようなツールを実行するように承認パイプラインを構成できます。

Note

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 デプロイを自動化する」を参照してください。

リファレンス

  • Last updated on