Azure API Management の裏に Web API があると、Web API の CI/CD と一緒に API Management の APIs も更新したいですよね。
公式ドキュメント ではめんどくさそうな実現方法が書かれていますが、APIs だけ更新したいなら Azure CLI で実現するのがシンプルでよいと思っています。
今回は ASP.NET Core 6 の Web API でやりますが Open API のファイルを出力できるならどれでも一緒です。GitHub Actions でのざっくりな流れは以下です。
- Web API をビルド時に Open API (Swagger) の定義ファイルを出力する
- Web API をデプロイする
- Open API (Swagger) の定義ファイルをもとに API Management の APIs を更新する
az apim api import を使うときに知っておきたいこと
Azure API Management の APIs の更新は Azure CLI でやります。
使うコマンドのドキュメントは以下です。ドキュメント通りにコマンドを実行すればよいだけに見えて説明が薄く闇深いので、気になる点を書いていきます。
az apim api import (az apim api) | Microsoft Learn
az apim api import の使い方と闇
APIM の APIs を更新したい場合は、先述のドキュメントで書かれている必須のパラメーター4つの他に、最低限必要なものがあります。
※ ちなみにこれは2022年10月現在の状況なのでバグだったら直るかもしれません。
- --api-id : 名称通り APIs のユニークな ID です。指定しないと毎回ランダムな値がセットされてしまいます 。つまり別の APIs ができることになる。そして既存の APIs の"path" が重複していると怒られる。同じ APIs を更新する際は事実上必須です。
- --display-name: セットしないと更新時に "MY API" に書き換えられるため事実上必須と言ってよいでしょう (これはバグな気がする) 。
- --service-url: セットしないと更新時に空になるので事実上必須です (これはバグな気がする) 。
それぞれのパラメーターが Azure Portal の APIM のリソース (APIs → 対象の API をクリック → Settings タブ) でどれにあたるかを補足しておくとこんな感じです。
| パラメーター | Azure Portal での値 |
|---|---|
--display-name |
Display name (①) |
--api-id |
Name (②) |
--service-url |
Web service URL (③) |
--path |
API URL suffix (④) |
--service-name |
API Management のリソース名 |
他のオプショナルなパラメーターは必要に応じてつける感じです。
ローカルでコマンドを実行するサンプル
前置きが長くて集中力が低めの私ですが、先述の内容を加味してコマンドのフォーマットは以下です。
az apim api import --resource-group <RESOURCE GROUP> --service-name <APIM SERVICE NAME> --display-name <DISPLAY NAME> --api-id <NAME> --service-url <SERVICE URL> --path <API URL SUFFIX> --specification-format OpenApiJson --specification-path <FILE PATH>
実行の例はこんな感じ。
前提知識: GitHub Actions 実行前に知ってきたい基礎
もう GitHub Actions で動かしたいお気持ちですが、最低限 ? 知っておかなあかん前提知識を2つあげます。
1つ目: CI 時に ASP.NET Core 6 で OpenAPI の定義ファイルを出力
これを書くと長くなるので前々回のブログにまとめました。
2つ目: GitHub Actions での Azure へのログインは OIDC
昨年 OIDC がサポートされてからは、基本的に OIDC でのログインがベストプラクティスです。ということでここも一緒に書くと長くなりそうだったので前回のブログに書きました。
GitHub Actions での実行
事前に以下の2つがやってある前提で話を進めます。
- "前提知識" の "2つ目: GitHub Actions で Azure へのログイン" で示した OIDC の設定。
- デプロイ先の API Management と Web App のリソースの作成が作成。
YAML のサンプル
コアな部分は先述で書いているので説明は省きますが、シンプルに組み合わせた基本的なコードです。
※ 14 - 25行目の env 定義は私の環境のものなので各々で試すときは変更が必要です。
この YAML での注意点
シンプルなサンプルなので、プロダクションで利用するにあたり考慮してない点をいくつか書いておきます。
- 本質からちょっと脱線する Web API は build 時に zip した方が速くね？とか Service URL は動的にとってきた方がいんじゃねとかそういう最適化も行ってないです。Web App のデプロイ時に Blue/Green デプロイするとか、要所で Environment 使って承認をさせるとかはもちろん触れてません。
- APIM の APIs を作成するときの subscription とかの考慮もしてないです。
