Azure REST API Microsoft.SaaS 2026-04-01 GA更新の変更点と移行確認ポイント

Azure REST APIでMicrosoft.SaaSを扱っている場合、今回の「Azure REST API documentation update: [Microsoft.SaaS] Add GA API version 2026-04-01 (TypeSpec)」は、単なるドキュメント名の更新ではありません。結論として、SaaSリソースプロバイダー向けに2026-04-01のGA API仕様をTypeSpecベースで追加する内容であり、REST APIを直接呼び出しているチーム、SDK生成やARMテンプレート連携を管理しているチームは、api-version、リクエストボディ、非同期処理、読み取り専用・書き込み専用プロパティを確認すべきです。PR本文では2026年5月4日に、6つのTypeSpecファイル、stable/2026-04-01/saas.json、12個の検証済みサンプル、package-2026-04-01タグの追加が説明されています。一方で、確認時点ではPRがClosedであり、Azure SDKの最新仕様一覧ではSaaSが引き続き2018-03-01-betaとして掲載されているため、本番切り替え前にmainブランチ、Microsoft Learn、実際のARM応答で反映状況を確認するのが安全です。(GitHub)

Azure REST APIのMicrosoft.SaaS 2026-04-01更新で変わること

今回の中心は、Microsoft.SaaSリソースプロバイダーのARM APIをTypeSpecで定義し、GA APIバージョン2026-04-01として扱えるようにすることです。TypeSpecはクラウドサービスAPIを記述し、OpenAPI、クライアントコード、ドキュメントなどを生成するための言語です。つまり、今回の更新はREST APIリファレンスだけでなく、将来的なSDK生成やAPI仕様管理にも影響し得ます。(Azure)

確認項目	変更内容	実務で見るポイント
APIバージョン	`2026-04-01`のGA API仕様を追加	既存コードの`api-version=2018-03-01-beta`を機械的に置換しない
仕様の記述方式	TypeSpecファイルからSwagger/OpenAPIを生成	SDK生成、APIレビュー、差分確認の起点がTypeSpec側にも広がる
生成物	`stable/2026-04-01/saas.json`が追加対象	CIでOpenAPIを取り込む場合はパス変更を確認する
API面	PR本文では21プロパティ、16パスと説明	パス、操作名、レスポンスコードを既存実装と比較する
サンプル	12個のサンプルが検証対象として説明	本番データに近いpayloadで再テストする

対応が必要になりやすい人

このAzure REST API更新で特に確認が必要なのは、Azure Marketplace SaaS、Microsoft.SaaSリソース、SaaSサブスクリプション管理を自動化しているチームです。ポータル操作だけで完結している場合は影響が小さい可能性がありますが、REST API、SDK、IaC、社内管理ツールでSaaSリソースを作成・更新・削除している場合は、早めに差分を見ておくべきです。

対象者	確認すべき理由
REST APIを直接呼び出している開発者	`api-version`、エンドポイント、リクエストボディの互換性確認が必要
DevOps・SRE	PUT/PATCH/DELETEなどの非同期処理でポーリング実装が必要になる可能性がある
SDK生成・API管理担当	TypeSpec由来のSwaggerが生成物やクライアントライブラリに影響する可能性がある
Azure Marketplace SaaS連携担当	購入、更新、解約、アクセスToken取得などの操作確認が必要
IaC管理者	ARM/Bicep/Terraformなどで`Microsoft.SaaS`を扱う場合、サポート状況を別途確認する必要がある

エンドポイントはsubscription-levelとtenant-levelの両方を見る

2026-04-01仕様では、subscription-levelとtenant-levelのSaaS操作が定義されています。subscription-levelでは、サブスクリプション配下やリソースグループ配下のMicrosoft.SaaS/resourcesを扱い、tenant-levelでは/providers/Microsoft.SaaS/saasresourcesを扱う構成です。TypeSpec上でも、subscription-level操作とtenant-level操作が別ファイルで定義されています。(GitHub)

種別	主なパス	代表的な操作
subscription-level	`/subscriptions/{subscriptionId}/providers/Microsoft.SaaS/resources`	サブスクリプション単位の一覧取得
subscription-level	`/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.SaaS/resources/{resourceName}`	取得、作成・更新、更新、削除
subscription-level	`/checkEligibility`、`/checkNameAvailability`	購入可否や名前の利用可否確認
subscription-level	`/listAccessToken`、`/unsubscribe`	ISVアクセストークン取得、解約
tenant-level	`/providers/Microsoft.SaaS/saasresources`	tenant-levelの作成・一覧取得
tenant-level	`/providers/Microsoft.SaaS/saasresources/{resourceId}`	取得、更新、削除
tenant-level	`/providers/Microsoft.SaaS/operationResults/{operationId}`	非同期操作の状態確認

注意したいのは、古い2018-03-01-beta仕様には/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.SaaS/applicationsなどのパスも含まれていた点です。2026-04-01への移行では、単にapi-versionを差し替えるだけでなく、呼び出しているパスが新仕様の対象に残っているかを確認してください。(GitHub)

プロパティ変更は「読み取り専用」と「書き込み専用」を分けて確認する

今回の仕様で実装上の落とし穴になりやすいのは、プロパティの可視性です。PR本文ではAPI surfaceとして、12個のReadOnly、6個のReadWrite、3個のWriteOnlyプロパティが説明されています。生成された仕様でも、subscriptionId、status、publisherName、termStartDate、purchaserEmailなどはサーバー側で割り当て・解決される値として扱われ、riskPropertyBagHeader、additionalInfo、intentは作成・更新時の入力向けとして定義されています。(GitHub)

分類	主なプロパティ	実装時の注意点
ReadOnly	`subscriptionId`、`status`、`statusReason`、`publisherName`、`planName`、`offerName`、`termStartDate`、`termEndDate`、`isFreeTrial`、`purchaserEmail`	PUT/PATCHのbodyに入れても期待どおり更新されない前提で設計する
ReadWrite	`description`、`quantity`、`autoRenew`、`storeFront`、`privateOfferId`、`productCode`	更新対象として扱えるが、サーバー側の検証結果を必ず確認する
WriteOnly	`riskPropertyBagHeader`、`additionalInfo`、`intent`	GETレスポンスに返る前提でログ・画面・後続処理を組まない

特にproductCodeはGA仕様で購入識別子として扱われ、カタログや契約条件の解決に関わる重要な値です。また、TypeSpecコメントではmarketやcspProperties、beneficiaryEmailなどがGA APIから除外された旨が示されています。古いpayloadをそのまま流用している場合は、不要になった項目を送っていないか確認してください。(GitHub)

移行前に確認すべき手順

既存のapi-versionと呼び出しパスを棚卸しする

まず、アプリケーション、Azure Functions、Logic Apps、CI/CDスクリプト、社内管理ツールでMicrosoft.SaaSを呼び出している箇所を洗い出します。検索対象は、次のような文字列です。

Microsoft.SaaS
api-version=2018-03-01-beta
/providers/Microsoft.SaaS/applications
/providers/Microsoft.SaaS/resources
/providers/Microsoft.SaaS/saasresources
listAccessToken
unsubscribe
checkEligibility

この段階では置換しないでください。古いAPIで使っているパス、body、レスポンス参照項目を一覧化し、新しい2026-04-01仕様に対応する操作があるかを確認します。

payloadの差分を確認する

次に、作成・更新時のJSON bodyを見直します。古い仕様ではofferId、publisherId、skuId、termId、paymentChannelType、paymentChannelMetadataなどを使っていた実装があるかもしれません。2026-04-01仕様ではproductCode、quantity、autoRenew、privateOfferIdなどを中心に整理されているため、古い作成パラメーターを送る実装は移行時にエラーや無視の原因になります。(GitHub)

202応答の処理を必ず確認する

SaaSリソースの作成、更新、削除、解約、移動などは、同期的に完了するとは限りません。2026-04-01仕様でも、202 Accepted、location、Retry-Afterを使うレスポンスが定義されています。自動化スクリプトでは、202を成功終了として扱って次工程へ進めるのではなく、指定された場所で状態確認を行う設計にしてください。(GitHub)

よくある失敗は、PUTやPATCHの直後にGETして古い状態を読み、「更新に失敗した」と誤判定するケースです。Retry-Afterが返る場合はその値を尊重し、タイムアウト、リトライ回数、失敗時の通知先まで決めておくと運用トラブルを減らせます。

az restで小さく検証する

専用のAzure CLIコマンドがない操作を検証する場合、az restを使うとREST APIを直接呼び出せます。Microsoft Learnでも、既存のAzure CLIコマンドが使用できない場合にaz restを使う位置づけが説明されています。(Microsoft Learn)

az rest --method get \
  --url "https://management.azure.com/subscriptions/<subscriptionId>/providers/Microsoft.SaaS/resources?api-version=2026-04-01"

リソースグループ配下の一覧取得を確認する場合は、次のように呼び出します。

az rest --method get \
  --url "https://management.azure.com/subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.SaaS/resources?api-version=2026-04-01"

更新処理を試す場合は、いきなり本番リソースでPATCHしないでください。検証環境で、quantityやautoRenewなど影響を限定しやすい項目から試し、レスポンスのstatus、statusReason、termStartDate、termEndDateを確認します。

az rest --method patch \
  --url "https://management.azure.com/subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.SaaS/resources/<resourceName>?api-version=2026-04-01" \
  --body '{
    "location": "global",
    "properties": {
      "quantity": 25,
      "autoRenew": true
    }
  }'

本番適用前のチェックリスト

チェック項目	判定基準
仕様反映	GitHub main、Microsoft Learn、実際のARM応答で`2026-04-01`が利用可能か
パス互換性	既存の`applications`や旧SaaSパスを新仕様で使っていないか
body互換性	古い`offerId`、`skuId`、`paymentChannelMetadata`などに依存していないか
可視性	ReadOnlyを更新対象にしていないか、WriteOnlyをレスポンスで参照していないか
LRO	202、`location`、`Retry-After`を処理できるか
認証・権限	呼び出し主体に対象サブスクリプション・リソースグループへの適切な権限があるか
ログ	`listAccessToken`の戻り値やトークンを平文ログに残していないか
ロールバック	`api-version`を戻すだけでなく、payloadとレスポンス処理も戻せる設計か

すぐに切り替えるべきか

今回の更新はGA API versionの追加を示す重要な変更ですが、すぐに全環境で切り替えるのはおすすめしません。理由は、2026年5月7日時点で確認できるPRがClosedであり、Azure SDKの最新仕様一覧ではSaaSが2018-03-01-betaとして掲載されているためです。ドキュメント更新、仕様リポジトリ、サービス側の受付状況、SDK対応には時間差が出ることがあります。(GitHub)

実務では、次の順番で進めるのが安全です。

既存のMicrosoft.SaaS REST API利用箇所を洗い出す
2018-03-01-betaと2026-04-01のpathsとdefinitionsを比較する
検証環境でGET系APIから試す
作成・更新・削除はLRO処理を含めてテストする
SDKやIaCの対応状況を確認してから本番へ段階適用する

まとめ

Azure REST APIのMicrosoft.SaaS向け2026-04-01 GA API version追加は、SaaSリソース操作をより新しいARM API仕様に整理する変更です。確認すべきポイントは、api-versionの置換そのものではなく、subscription-levelとtenant-levelのパス、作成・更新payload、ReadOnly/WriteOnlyプロパティ、202応答のポーリング処理です。

まずは既存コードのMicrosoft.SaaS利用箇所を棚卸しし、GET系APIで2026-04-01が利用できるかを検証してください。そのうえで、PATCHやDELETEなど状態変更を伴う操作は、非同期処理とロールバック手順を用意してから段階的に移行するのが現実的です。

この記事を書いた人

佐藤健司

実務の現場で詰まりがちなポイントを地図にするITブログ「IT trip」を運営。Windows／Office（Teams・Excel）からSQL、サーバ運用、ガジェットまで、再現性のある手順と“なぜそうなるか”を丁寧に解説します。読んだらすぐ試せること、そして迷った人の次の一歩が見えることを大切にしています。