2026年5月5日更新として確認すべきポイントは、Azure REST API全体の使い方が変わったことではなく、Microsoft.SaaS リソースプロバイダー向けに GA API version 2026-04-01 の TypeSpec 定義と生成済み Swagger が追加されたことです。Azure Marketplace の SaaS サブスクリプションを REST API、独自ツール、SDK、IaC から扱っているチームは、api-version、リクエスト/レスポンスのスキーマ、長時間実行操作、アクセストークンの取り扱いを確認する必要があります。PR上ではレビューや破壊的変更確認に関するラベルも付いているため、本番適用前にはマージ状況と公式ドキュメントへの反映もあわせて確認しましょう。(GitHub)
Azure REST API documentation updateの要点
今回の更新は、Azure REST APIの中でも Microsoft.SaaS に関する仕様追加です。PRでは「Microsoft.SaaS resource provider GA API version 2026-04-01」の TypeSpec 定義を追加すると説明されており、TypeSpecソース、tspconfig.yaml、生成済みの stable/2026-04-01/saas.json、各操作のサンプルJSONが含まれています。(GitHub)
| 確認項目 | 今回の内容 | 実務での意味 |
|---|---|---|
| 対象リソースプロバイダー | Microsoft.SaaS | Azure Marketplace SaaSの契約、作成、更新、解約、アクセストークン取得などに関係 |
| API version | 2026-04-01 | 既存の古い api-version から移行する候補になる |
| 仕様形式 | TypeSpecと生成済みSwagger | 今後のSDK生成やREST API仕様確認ではTypeSpec側の変更も重要になる |
| 主な操作範囲 | サブスクリプションレベル、テナントレベル | 管理対象のパスや権限設計を分けて確認する必要がある |
| 注意点 | PR上ではレビュー関連ラベルあり | すぐ本番反映と決めず、マージ後の公式反映を確認する |
TypeSpecはAPI設計を記述するための言語で、API仕様やクライアントコードなどを生成する仕組みと組み合わせて使われます。Azure REST APIの仕様では、TypeSpecからOpenAPI/Swagger形式の仕様が生成されるため、生成後のJSONだけでなく、元となるTypeSpec定義の意図も確認すると変更点を把握しやすくなります。(Microsoft Learn)
何が変わったのか
Microsoft.SaaSのGA API version 2026-04-01が追加された
PRでは、Microsoft.SaaS リソースプロバイダーのGA APIとして 2026-04-01 が定義されています。main.tsp では Microsoft.SaaS Resource Provider - GA API としてバージョン 2026-04-01 が設定され、Azure Resource Manager向けの共通型も利用されています。(GitHub)
生成済みSwaggerでは、host が management.azure.com、schemes が https、api-version が 2026-04-01 として扱われます。Azure REST APIでは、一般にHTTPSでAzure Resource Managerへリクエストを送り、Microsoft Entra IDのベアラートークンで認証します。(GitHub)
GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.SaaS/resources/{resourceName}?api-version=2026-04-01
Authorization: Bearer {access_token}このようなREST呼び出しを自前で組み立てている場合、単に api-version を置き換えるだけでは不十分です。レスポンス項目、読み取り専用項目、書き込み専用項目、長時間実行操作の扱いまでテストする必要があります。
サブスクリプションレベルとテナントレベルの操作が整理された
今回の仕様では、サブスクリプション配下のSaaSリソース操作と、テナントレベルのSaaSリソース操作が分かれています。サブスクリプションレベルでは、取得、作成/更新、更新、削除、リソースグループ単位の一覧、アクセストークン取得、解約などの操作が定義されています。(GitHub)
一方、テナントレベルでは、/providers/Microsoft.SaaS/saasresources 系のパスで、作成、取得、更新、削除、一覧、アクセストークン取得、事前検証に相当する操作が定義されています。テナントレベルのリソース名には 3〜50 文字の英数字とハイフンというパターンも指定されています。(GitHub)
| 操作カテゴリ | 代表的な操作 | 確認すべきポイント |
|---|---|---|
| サブスクリプションレベル | 作成、取得、更新、削除、一覧、解約、アクセストークン取得 | 既存の管理ツールや自動化スクリプトがこのパスを使っていないか確認する |
| テナントレベル | 作成、取得、更新、削除、一覧、アクセストークン取得 | テナントスコープの権限、パス、リソース名制約を確認する |
| 事前検証 | preflight | 作成前チェックや購入前チェックのフローに組み込めるか確認する |
| 移動関連 | moveResources、validateMoveResources | リソース移動を自動化している場合は検証対象に含める |
実務では、「SaaS契約を作るAPI」だけを見るのではなく、契約前の検証、契約後の更新、解約、リソース移動、アクセストークン取得まで一連の業務フローで確認することが重要です。
モデルから削除・整理された項目がある
TypeSpecのコメントでは、GAモデルに向けていくつかの項目が削除または整理されています。たとえば SubscriptionTerm は削除され、termStartDate と termEndDate が SaasResourceProperties 上のフラットな項目として扱われます。また、支払いチャネル関連のメタデータ、CSP関連の複数モデル、beneficiaryEmail なども削除対象として記載されています。(GitHub)
特に注意したいのは、古いレスポンスを前提にしているアプリです。たとえば、管理画面で market や beneficiaryEmail を表示していた、あるいはCSP関連フィールドの存在を前提に分岐処理を書いていた場合、2026-04-01 では同じロジックが成立しない可能性があります。
| 変更・整理された観点 | 確認すべき影響 |
|---|---|
SubscriptionTerm の削除 | termStartDate、termEndDate を直接参照する実装へ見直す |
| 支払いチャネル関連メタデータの削除 | レスポンス上の支払い情報を前提にした表示・判定を見直す |
| CSP関連モデルの削除 | CSP向けの独自分岐や入力パラメータを棚卸しする |
market の削除 | 市場情報をレスポンスから直接取得する前提を避ける |
beneficiaryEmail の削除 | 受益者メールを表示・保存している処理を確認する |
additionalInfo などの書き込み専用項目 | GETレスポンスに返る前提で実装しない |
productCode はGAでの主要な購入識別子として説明されており、サーバー側で契約条件の解決に使われる想定です。既存実装が古いプラン名やオファー名だけで購入対象を判定している場合は、productCode を中心にした設計へ見直す余地があります。(GitHub)
アクセストークンをログに出さない設計が必要
listAccessToken 系の操作では、AccessTokenResult に token や offerUriWithToken が含まれ、これらは秘密情報として扱われます。実装時は、HTTPレスポンス全体をデバッグログに出す、エラー時にレスポンスボディをそのまま監視ツールへ送る、といった実装を避けるべきです。(GitHub)
安全な実装にするには、次のようなルールを明文化します。
| 対象 | 推奨する扱い |
|---|---|
token | ログ、画面、分析基盤に出力しない |
offerUriWithToken | URL全体を保存せず、必要な処理が終わったら破棄する |
| エラーログ | レスポンス本文を丸ごと出さず、HTTPステータス、操作名、相関IDを中心に記録する |
| 監視ツール | シークレットマスキングルールに token と offerUriWithToken を追加する |
誰が対応すべきか
対応が必要なのは、Azure REST API全般の利用者ではなく、Microsoft.SaaS を使ってSaaSリソースやMarketplace連携を扱っているチームです。特に、REST APIを直接呼んでいる、SDK生成物を利用している、IaCや独自スクリプトで api-version を固定している場合は優先的に確認しましょう。(GitHub)
| 利用状況 | 対応優先度 | 具体的に見る場所 |
|---|---|---|
| REST APIを直接呼び出している | 高 | URL、api-version、リクエストボディ、レスポンス解析 |
| 自社の管理画面からSaaS契約を操作している | 高 | 作成、更新、解約、一覧、アクセストークン取得の全フロー |
| SDKを使っている | 中〜高 | SDKが 2026-04-01 に対応したタイミング、破壊的変更の有無 |
| ARMテンプレートや独自IaCで扱っている | 中 | リソースタイプ、APIバージョン、入力パラメータ |
| 監視・棚卸し用途でGETだけ使っている | 中 | ステータス値、削除されたフィールド、読み取り専用項目 |
Microsoft.SaaS を使っていない | 低 | 直ちに設定変更する必要は低い |
反対に、仮想マシン、ストレージ、ネットワークなど別のAzureリソースだけを管理している場合、今回の更新だけでREST API全体の実装を変更する必要はありません。ただし、Azure REST API仕様がTypeSpec中心に整理されていく流れを把握しておくと、将来のAPI移行やSDK更新時に判断しやすくなります。
影響範囲を確認する方法
まず、コードやテンプレート内に Microsoft.SaaS と古い api-version が含まれていないか確認します。PRのreadmeでは新しいタグとして package-2026-04-01、既存のプレビュータグとして package-2018-03-01-beta が記載されています。古いプレビューAPIを使っている場合は、差分確認の優先度が高くなります。(GitHub)
grep -R "Microsoft.SaaS" .
grep -R "2018-03-01-beta" .
grep -R "api-version=" .PowerShellを使う場合は、次のようにリポジトリ全体から該当文字列を探せます。
Get-ChildItem -Recurse -File |
Select-String -Pattern "Microsoft.SaaS","2018-03-01-beta","api-version="見つかった箇所は、次の観点で分類します。
| 分類 | 例 | 対応 |
|---|---|---|
| RESTクライアント | management.azure.com/.../Microsoft.SaaS/... | 新APIバージョンで契約テストを行う |
| 設定ファイル | api-version=2018-03-01-beta | 置き換え可否を検証環境で確認する |
| レスポンス変換 | market、beneficiaryEmail などの参照 | 削除・変更された項目を前提にしていないか確認する |
| ログ出力 | レスポンス全体の記録 | アクセストークンやURL付きトークンをマスクする |
| SDKラッパー | 独自クラスやDTO | SDK更新時の型変更に備える |
ここで重要なのは、api-version を一括置換しないことです。Azure REST APIではAPIバージョンごとにスキーマや動作が変わることがあります。まず検証環境で代表的な作成、取得、更新、削除、解約、アクセストークン取得の流れを動かし、問題がないことを確認してから段階的に切り替えます。
移行時に確認すべき実務ポイント
リクエストボディの項目を見直す
SaasResourceProperties には、作成・更新時に渡せる項目、読み取り専用の項目、書き込み時だけ意味を持つ項目が分かれています。たとえば provisioningState、status、publisherName、planName、offerName、termStartDate、termEndDate、isFreeTrial、purchaserEmail などは読み取り専用として定義されています。(GitHub)
一方で、riskPropertyBagHeader、additionalInfo、intent などは作成・更新時に関係する項目です。additionalInfo はAssets APIへ渡されるが保存やGETでの返却はされない旨が説明されています。つまり、「PUTで送ったからGETで同じ値が返る」と考えるとテストが失敗します。(GitHub)
確認例
{
"properties": {
"productCode": "sample-product-code",
"quantity": 1,
"autoRenew": true,
"additionalInfo": {
"source": "internal-portal"
}
}
}このような作成リクエストを使う場合、検証では次の点を確認します。
| 確認項目 | 見るべき結果 |
|---|---|
productCode | 購入対象の識別に使われ、想定したSaaS商品に紐づくか |
quantity | 契約数やシート数として期待どおり処理されるか |
autoRenew | 更新設定が業務要件と合っているか |
additionalInfo | GETレスポンスに返る前提の実装になっていないか |
| 読み取り専用項目 | リクエストに含めてエラーや無視が起きないか |
長時間実行操作のポーリングを確認する
生成済みSwaggerでは、作成、更新、削除、解約など一部の操作が長時間実行操作として定義されています。Azure Resource ManagerのREST APIでは、202 Accepted、Azure-AsyncOperation、Location、Retry-After などのヘッダーを使って処理状況を追跡するパターンがあります。(GitHub)
失敗しやすいのは、PUTやDELETEのレスポンスを受け取った時点で処理完了とみなしてしまう実装です。SaaS契約の作成・解約はバックエンド側の処理に時間がかかることがあるため、最終状態を確認せずに次の処理へ進むと、画面表示や後続APIで不整合が起きます。
| NG実装 | 改善策 |
|---|---|
202 Accepted を成功完了として扱う | ポーリングして最終状態を確認する |
Retry-After を無視して短周期で再試行する | 指定された待機時間を尊重する |
Location だけ、または Azure-AsyncOperation だけに固定する | API仕様に従って両方のパターンに対応する |
| タイムアウト時に契約状態を確認しない | GETで現在状態を再確認する |
ステータス値を固定しすぎない
SaasResourceStatus には NotStarted、PendingFulfillmentStart、Subscribed、Unsubscribed、Suspended などの値が定義されています。また、サブスクリプション状態の理由や削除元、PATCH時の意図を表す列挙値も定義されています。(GitHub)
ステータスを扱う実装では、既知の値だけを前提にした厳しすぎるバリデーションを避けます。将来のAPI更新で値が増える可能性を考え、未知のステータスは「不明」や「要確認」として表示し、処理を即時停止しない設計にしておくと保守性が高まります。
function toDisplayStatus(status: string): string {
switch (status) {
case "Subscribed":
return "契約中";
case "Unsubscribed":
return "解約済み";
case "Suspended":
return "停止中";
case "PendingFulfillmentStart":
return "処理開始待ち";
case "NotStarted":
return "未開始";
default:
return `不明な状態: ${status}`;
}
}SDK利用者が確認すべきこと
PRでは、Go、Python、JavaScript、JavaなどのSDK向けAPIレビューが検出されています。また tspconfig.yaml では、Javaの azure-resourcemanager-saas、JavaScriptの @azure/arm-saas、Goの armsaas、Pythonの azure.mgmt.saas などに関する生成設定が確認できます。(GitHub)
SDKを使っている場合は、REST API仕様が追加された直後に自動的に手元のSDKが対応するとは限りません。次の順序で確認すると安全です。
| 手順 | 確認内容 |
|---|---|
| SDKの対応状況を確認 | 利用中のSDKが 2026-04-01 に対応しているか |
| changelogを確認 | 型名、メソッド名、必須項目、戻り値の変更がないか |
| 生成型を確認 | 読み取り専用・書き込み専用の扱いが変わっていないか |
| サンプルを実行 | 作成、更新、削除、アクセストークン取得を検証環境で試す |
| 例外処理を確認 | LRO、権限エラー、入力エラー、未知のステータス値に対応できるか |
SDK経由であっても、ログにシークレットを出さない、長時間実行操作の完了を待つ、古い項目に依存しない、という基本はREST API直接利用時と同じです。
本番適用前のチェックリスト
Microsoft.SaaS の 2026-04-01 を採用する前に、次の項目を確認しておくと移行時のトラブルを減らせます。
- GitHub PRがマージされ、公式ドキュメントやSDKに反映されているか
- 現在使っている
api-versionと2026-04-01の差分を確認したか Microsoft.SaaSを呼び出すURL、スクリプト、IaC、SDKラッパーを棚卸ししたかmarket、beneficiaryEmail、支払いチャネル関連、CSP関連など古い項目に依存していないかproductCodeを中心に購入対象を扱う設計になっているか- GETで返らない書き込み専用項目を、レスポンス検証で必須扱いしていないか
tokenとofferUriWithTokenをログや監視ツールに出していないか- 作成、更新、削除、解約などの長時間実行操作でポーリングを実装しているか
- 未知のステータス値や列挙値が来てもアプリが落ちないか
- 検証環境でSaaS契約の作成から解約までの一連のフローをテストしたか
特に、PR上では BreakingChangeReviewRequired や NotReadyForARMReview などのラベル、クロスバージョンの破壊的変更チェックに関する表示が確認できます。仕様を先取りして実装準備を進めることは有効ですが、本番切り替えはマージ状況、レビュー完了、SDKリリース状況を確認してから判断するのが安全です。(GitHub)
まとめ：まずはMicrosoft.SaaSの利用箇所を棚卸しする
今回のAzure REST API documentation updateは、Microsoft.SaaS のGA API version 2026-04-01 に向けたTypeSpec定義と生成済みSwaggerの追加が中心です。影響を受けるのは、Azure Marketplace SaaSをREST API、SDK、IaC、独自管理画面から扱っているチームです。
次に取るべき行動は明確です。まずリポジトリや設定ファイルから Microsoft.SaaS と既存の api-version を検索し、該当箇所を一覧化します。そのうえで、削除・整理されたモデル項目、アクセストークンの秘匿、長時間実行操作のポーリング、SDK対応状況を検証環境で確認します。Microsoft.SaaS を使っていない場合は直ちに変更する必要は低いものの、Azure REST API仕様がTypeSpecベースで管理・生成される流れは、今後のAzure API移行を考えるうえで押さえておくべきポイントです。
コメント