Azure REST API documentation updateのうち、fleet 2026-06-02-preview: Get update namespace final state via original uriで最初に押さえるべき結論は、Fleet Managed NamespaceのUpdate操作そのものの入力項目が大きく増えたわけではなく、長時間実行操作（LRO）の完了後に「最終状態をどこから取得するか」が変わったという点です。具体的には、x-ms-long-running-operation-optionsのfinal-state-viaがlocationからoriginal-uriに変更されています。REST APIを直接呼ぶ管理者よりも、SDK生成、Go SDK、独自のポーリング処理、IaCテンプレートでプレビューAPIを使っている開発者・運用担当者が影響を確認すべき更新です。(GitHub)
Azure REST API documentation updateの概要
今回の更新は、Azure REST API仕様リポジトリであるAzure/azure-rest-api-specsのPull Request #43387として確認できます。PR名はfleet 2026-06-02-preview: Get update namespace final state via original uriで、対象はAzure Kubernetes Fleet Managerに関連するMicrosoft.ContainerService/fleets/managedNamespacesのUpdate操作です。GitHub上では2026年5月20日にマージされたPRとして表示されており、日本時間では2026年5月21日更新として把握しておきたい内容です。(GitHub)
変更対象は、主に次の3ファイルです。PRの差分では、TypeSpec定義のfleetnamespace.tspにLROの最終状態取得方法を明示する拡張が追加され、OpenAPI JSON側では2026-05-01-previewと2026-06-02-previewのfleets.jsonでfinal-state-viaがlocationからoriginal-uriへ変更されています。(GitHub)
| 項目 | 変更前 | 変更後 | 実務上の意味 |
|---|---|---|---|
| 対象API | Fleet Managed Namespaces – Update | 同じ | Update操作の対象リソースは変わらない |
| APIバージョン | 2026-05-01-preview、2026-06-02-preview | 同じ | プレビューAPI利用者は差分確認が必要 |
| LRO最終状態取得 | final-state-via: location | final-state-via: original-uri | 完了後の最終GET先がLocationヘッダー側ではなく元のリソースURI側になる |
| 主な影響 | SDK生成、ポーリング結果、テスト | 同左 | RESTリクエスト本文よりもクライアント実装への影響が大きい |
何が変わったのか
変更の中心は、Fleet Managed Namespaceを更新するPATCH操作に対するLRO設定です。既存のREST APIドキュメントでは、Fleet Managed NamespaceのUpdate操作は次のようなPATCHエンドポイントとして説明されています。レスポンスは200 OKまたは202 Acceptedを取り、202 Acceptedの場合はLocationとRetry-Afterヘッダーが返る可能性があります。(Microsoft Learn)
PATCH https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ContainerService/fleets/{fleetName}/managedNamespaces/{managedNamespaceName}?api-version=2026-06-02-previewこのエンドポイントやリクエスト本文の基本構造が大きく変わるわけではありません。重要なのは、非同期更新が完了した後にSDKやクライアントが「最終的なFleet Managed Namespaceリソース」を取得する方法です。
AutoRestの拡張仕様では、final-state-via: locationは初回レスポンスにLocationヘッダーがある場合にそのURLへ最終GETを行う動作、final-state-via: original-uriは処理完了後に元のリソースURIへ最終GETを行う動作として説明されています。つまり今回の更新により、Update後の最終状態確認は「操作ステータス用URL」ではなく「更新対象リソース自身のURI」を基準にする意図が明確になりました。(GitHub)
final-state-via: original-uriを実務でどう理解するか
LROは、リソース作成・更新・削除のように即時完了しない操作で使われるパターンです。クライアントは最初のリクエストで202 Acceptedを受け取り、指定された間隔で状態をポーリングし、処理がSucceeded、Failed、Canceledなどの終端状態になるまで待ちます。AutoRestの説明でも、x-ms-long-running-operation: trueが付いた操作では、生成コードが監視用リンクを使ってポーリングすることが示されています。(GitHub)
ここで混同しやすいのが、「ポーリング先」と「最終的な結果取得先」は必ずしも同じではないという点です。Locationヘッダーは操作状態の確認や結果取得に使われることがありますが、更新後のリソース本体を正しく取得したい場合は、元のリソースURIをGETしたほうが自然なケースがあります。
今回のoriginal-uriへの変更は、Fleet Managed NamespaceのUpdate完了後に、更新対象そのものの最終状態を取得する設計へ寄せる変更と見るのが実務的です。たとえば、タグ、プロビジョニング状態、managedNamespaceProperties、status.lastOperationErrorなどを確認する場合、操作ステータスURLのレスポンスではなく、対象リソースのGET結果を前提にしたほうが後続処理を書きやすくなります。
| 観点 | location | original-uri |
|---|---|---|
| 最終GETの基準 | 初回レスポンスのLocationヘッダー | PATCHを実行した元のリソースURI |
| 向いている用途 | 操作結果URLをサービス側が明示する場合 | 更新後のリソース本体を取得したい場合 |
| 実装上の注意 | Locationを最終結果と誤認しやすい | 元リソースのGET権限やAPIバージョンを確認する |
| 今回の変更後 | 使われなくなる方向 | Fleet Managed Namespace Updateの最終状態取得に使われる |
影響を受ける対象者
今回のAzure REST API documentation updateは、AzureポータルでFleetを操作しているだけの利用者よりも、REST API、SDK、IaC、CI/CDでFleet Managed Namespaceを扱っているチームへの影響が大きい更新です。
| 利用形態 | 影響度 | 確認すべきこと |
|---|---|---|
| Azureポータル中心の運用 | 低 | 通常は直接対応不要。ただし裏側で利用する拡張機能やCLIの更新は確認する |
Azure CLIのfleet拡張機能 | 中 | az upgradeとaz extension update --name fleetで最新化できる状態か確認する |
| REST APIを直接呼ぶスクリプト | 中 | Locationを最終リソースとして扱っていないか確認する |
| 自作のLROポーリング実装 | 高 | ポーリング完了後に元のリソースURIをGETする設計にできているか確認する |
| Azure SDK利用アプリ | 中〜高 | SDKパッケージ更新時にUpdate結果の型、メソッド名、戻り値の扱いをテストする |
| Go SDK生成・利用 | 高 | PR上でBreakingChange-Go-Sdkラベルが付いているため、生成結果と呼び出しコードの確認が必要 |
| Bicep、ARM、Terraform AzAPI | 中 | 利用中のapiVersion、プレビューAPIの更新計画、CI検証を確認する |
PR上ではAPIレベルの変更が検出され、TypeSpecとGoのAPIViewが作成されています。また、BreakingChange-Go-Sdkラベルも付与されています。これは「すべてのGo利用者に必ず破壊的変更が発生する」と断定できる情報ではありませんが、少なくともSDK生成結果では注意が必要な差分として扱われたことを意味します。(GitHub)
管理者が確認すべきポイント
利用中のAPIバージョンを棚卸しする
まず確認すべきなのは、組織内でMicrosoft.ContainerService/fleets系のプレビューAPIをどこから呼んでいるかです。Azure Kubernetes Fleet ManagerのプレビューARM REST APIは、-previewで終わるAPIバージョンが対象で、Microsoft LearnではプレビューAPIの寿命がおおむね約1年であること、ARM/Bicep/TerraformテンプレートやプレビューSDKを最新互換バージョンへ定期的に更新することが推奨されています。(Microsoft Learn)
アクティビティログから特定APIバージョンの利用を確認する場合は、公式ドキュメントの考え方に沿って、対象APIバージョンを指定して調査します。(Microsoft Learn)
API_VERSION="2026-06-02-preview"
az monitor activity-log list \
--offset 30d \
--max-events 10000 \
--namespace microsoft.containerservice.fleets \
--query "[?eventName.value == 'EndRequest' && contains(not_null(httpRequest.uri,''), '${API_VERSION}')]"この確認で、CI/CD、IaC、管理スクリプト、SDKアプリのどれがFleet APIを呼んでいるかを洗い出します。特に、運用チームが把握していないGitHub Actions、Azure DevOps Pipeline、Terraform Cloud、社内バッチから呼び出しているケースは見落としやすいポイントです。
Azure CLIと拡張機能を更新する
Fleet ManagerのプレビューAPIライフサイクルに関するMicrosoft Learnでは、Azure CLIとfleet拡張機能について、az upgradeとaz extension update --name fleetによる更新が案内されています。CLI経由でFleet Managed Namespaceを更新している場合、古い拡張機能のまま検証すると、REST API仕様の変更を正しく反映できない可能性があります。(Microsoft Learn)
az upgrade
az extension update --name fleet本番環境でいきなり実行するのではなく、検証用サブスクリプションまたは検証用Fleetで、更新前後のaz fleet namespace updateや関連コマンドの結果を比較してください。
カスタムロールの読み取り権限を確認する
final-state-via: original-uriでは、LRO完了後に元のリソースURIへGETする流れが想定されます。最小権限のカスタムロールを使っている環境では、更新権限だけでなく、対象リソースの読み取り権限が含まれているかを確認してください。
たとえば、更新操作自体は成功しているのに、SDKのPollUntilDoneや.result()で失敗する場合、処理本体ではなく「完了後の最終GET」で権限エラーが出ている可能性があります。ログではPATCHの成功だけでなく、その後に発生するGETリクエストも確認することが重要です。
開発者が確認すべき実装ポイント
Locationを最終結果として固定的に扱わない
REST APIを直接呼んでいる場合、202 Acceptedで返ったLocationを「更新後リソースのURL」として保存している実装は見直しが必要です。Locationは操作ステータス確認に関係するURLであり、今回の仕様変更後は、最終状態の取得先として元のリソースURIを使う前提で設計したほうが安全です。
望ましい処理の流れは次のようになります。
| 手順 | 処理 | 注意点 |
|---|---|---|
| 1 | Fleet Managed NamespaceへPATCHを送信 | api-versionを明示する |
| 2 | 200 OKならレスポンスを処理 | 即時完了として扱う |
| 3 | 202 AcceptedならLROとして扱う | Retry-Afterがあれば尊重する |
| 4 | 操作が終端状態になるまでポーリング | タイムアウトと失敗状態を必ず実装する |
| 5 | 成功後、元のリソースURIをGET | 更新後の最終状態を取得する |
| 6 | 期待するタグ、状態、プロパティを検証 | 操作成功と設定反映を分けて確認する |
擬似コードで書くと、次のような考え方です。
patchUri = "/subscriptions/.../providers/Microsoft.ContainerService/fleets/{fleetName}/managedNamespaces/{managedNamespaceName}?api-version=2026-06-02-preview"
response = PATCH patchUri body
if response.status == 200:
return response.body
if response.status == 202:
pollUntilTerminalState(response.headers)
finalResource = GET patchUri
return finalResource
raise error実装でありがちな失敗は、Locationヘッダーのレスポンスをそのまま業務ロジックへ渡してしまうことです。後続処理がpropertiesやtagsを期待している場合、操作ステータスのJSONとリソース本体のJSONが一致せず、フィールド不足や型不一致が発生します。
SDK更新時は「成功するか」だけでなく「戻り値」を見る
SDKを使っている場合、単にビルドが通るか、Updateが成功するかだけでは確認が足りません。今回の変更はLRO完了後の最終状態取得に関係するため、begin_update、BeginUpdate、PollUntilDone、.result()などの戻り値が、期待するFleet Managed Namespaceリソースになっているかを確認する必要があります。
確認すべき観点は次の通りです。
| 確認項目 | 具体例 |
|---|---|
| メソッド名 | update、begin_update、BeginUpdateの呼び出しが変わっていないか |
| 戻り値の型 | Fleet Managed Namespace本体として扱えるか |
| 非同期完了後の値 | tags、eTag、properties.statusなどが取得できるか |
| エラー処理 | ポーリング中の失敗と最終GETの失敗を区別できるか |
| テスト | 202応答のケースをモックではなく実APIまたは統合テストで確認しているか |
特にGo SDKでは、PR上でBreakingChange-Go-Sdkが検出されています。Goの自動生成SDKを直接利用している場合、パッケージ更新時にコンパイルエラーだけでなく、レスポンス構造体、Pollerの戻り値、サンプルコードの差分まで確認してください。(GitHub)
IaCではプレビューAPIの固定に注意する
Bicep、ARMテンプレート、Terraform AzAPIでFleet関連リソースを管理している場合、apiVersionまたはtypeにプレビューAPIバージョンが固定されていないか確認してください。Microsoft Learnでは、Bicepではリソース型末尾の@2024-05-02-previewのような指定、ARMテンプレートではapiVersion、Terraformではtypeに含まれるAPIバージョンを確認する例が示されています。(Microsoft Learn)
Bicepの例です。
resource fleet 'Microsoft.ContainerService/fleets@2026-06-02-preview' = {
name: fleetName
location: location
}Terraform AzAPIの例です。
resource "azapi_resource" "fleet_namespace" {
type = "Microsoft.ContainerService/fleets/managedNamespaces@2026-06-02-preview"
name = var.namespace_name
parent_id = azapi_resource.fleet.id
}IaCで注意すべきなのは、「APIバージョンを上げれば常に安全」というわけではないことです。プレビューAPIでは、スキーマ、LROの挙動、SDK生成結果が変わることがあります。更新時は、Planの差分、Apply後の実リソース状態、ロールバック手順までセットで検証してください。
展開前に確認したいチェックリスト
本番環境へ反映する前に、次のチェックを済ませておくとトラブルを減らせます。
| チェック項目 | 確認内容 | 優先度 |
|---|---|---|
| API利用箇所の棚卸し | アクティビティログ、CI/CD、IaC、SDKアプリを確認 | 高 |
| APIバージョン | 2026-05-01-previewまたは2026-06-02-previewを使っているか | 高 |
| LRO処理 | Locationを最終リソースとして扱っていないか | 高 |
| 最終GET | PATCH元のリソースURIをGETして期待値を検証できるか | 高 |
| 権限 | 更新権限に加えて読み取り権限があるか | 中 |
| SDK | 特にGo SDKの生成結果と呼び出しコードを確認 | 高 |
| CLI | Azure CLIとfleet拡張機能を更新 | 中 |
| IaC | Bicep、ARM、Terraform AzAPIのAPIバージョンを確認 | 中 |
| テスト | 200即時完了と202非同期完了の両方を検証 | 高 |
| ロールバック | APIバージョン変更前に戻す条件と手順を決める | 中 |
よくある誤解と失敗しやすいポイント
「リクエスト本文が変わった」と誤解する
今回の主な変更は、Fleet Managed Namespace Updateの入力項目追加ではありません。少なくともPR差分上の中心は、LROのfinal-state-viaをoriginal-uriへ変更することです。リクエスト本文のtagsや更新対象の基本URIだけを見ていると、変更点を見落とします。
202 Acceptedを成功完了として扱う
202 Acceptedは「更新要求が受け付けられた」ことを示す状態であり、更新後のリソース状態が反映済みであることを意味しません。Fleet Managed NamespaceのUpdateドキュメントでも、202 AcceptedではLocationとRetry-Afterヘッダーが示されるレスポンスとして扱われています。(Microsoft Learn)
運用スクリプトでは、PATCHの直後に次の処理へ進まず、LRO完了を待ってから元のリソースURIをGETし、期待する状態になっているか確認してください。
プレビューAPIを長期間固定する
Fleet ManagerのプレビューAPIは、定期的な更新を前提に使う必要があります。Microsoft Learnでは、プレビューAPIやそれに基づくツールを最新互換バージョンへ更新すること、最低でも6〜9か月ごとに更新を行うことが推奨されています。(Microsoft Learn)
本番運用でプレビューAPIを使う場合は、APIバージョンを固定して安定させるだけでなく、更新タイミングを運用計画に組み込むことが重要です。固定し続けると、ある時点で非推奨化やSDK更新時の差分がまとめて発生し、移行負荷が大きくなります。
管理者・開発者が次に取るべき行動
今回のAzure REST API documentation updateは、Fleet Managed NamespaceのUpdate操作におけるLRO最終状態取得の仕様を明確にする更新です。通常の管理画面操作だけなら大きな変更対応は不要なケースが多い一方で、REST APIやSDK、Go SDK、自作ポーリング、IaCで2026-05-01-previewまたは2026-06-02-previewを扱うチームは確認が必要です。
まず、アクティビティログとリポジトリ検索でFleet APIの利用箇所を洗い出してください。次に、Locationヘッダーを最終結果として扱っている実装がないかを確認します。そのうえで、SDK更新、CLI拡張機能の更新、IaCのAPIバージョン確認、LRO完了後の元リソースGETを含む統合テストを実施します。
特にGo SDKや自動生成クライアントを使っている場合は、今回のPRで破壊的変更が検出されている点を軽視しないほうが安全です。ビルド、戻り値、ポーリング完了後の最終リソース取得まで確認し、プレビューAPIを使う運用では6〜9か月単位のAPIバージョン見直しを定例化しましょう。
コメント