Azure REST API documentation updateとして「Remove 2026-11-01-preview api version」が確認された場合、まず見るべきポイントは2026-11-01-previewを使った実装・テンプレート・SDK生成設定が自社環境に残っていないかです。今回の変更は、Azure REST APIの仕様リポジトリ上でMicrosoft.DeviceRegistry関連の2026-11-01-preview APIバージョンを削除する内容です。ただし、現時点で確認できるPRはOpen状態で、ARMレビューやバージョンレビューのラベルも付いているため、「本番APIが即停止した」と短絡的に判断するのではなく、ドキュメント・仕様・自動生成コードへの影響を先に点検するのが現実的です。(GitHub)
Azure REST APIの「Remove 2026-11-01-preview api version」で何が変わるのか
今回のAzure REST API documentation updateは、azure-rest-api-specsリポジトリのPR「Remove 2026-11-01-preview api version #42859」として確認できます。対象はAzure Device Registry、リソースプロバイダーとしてはMicrosoft.DeviceRegistryです。PRでは1コミットで155ファイルが変更され、追加はなく、24,485行の削除が示されています。(GitHub)
削除対象には、次のようなパスが含まれます。
| 確認対象 | 変更内容の見方 |
|---|---|
specification/deviceregistry/resource-manager/Microsoft.DeviceRegistry/preview/2026-11-01-preview | 2026-11-01-previewのOpenAPI仕様本体とサンプルが削除対象 |
specification/deviceregistry/DeviceRegistry.Management/examples/2026-11-01-preview | SDK生成・検証で参照される管理系サンプルが削除対象 |
specification/deviceregistry/resource-manager/readme.md | AutoRestなどの生成設定で使うAPIバージョンタグの見直し対象 |
specification/deviceregistry/DeviceRegistry.Management/main.tsp | TypeSpec由来の定義・生成経路に影響する可能性 |
特に重要なのは、単にサンプルが消えるだけではなく、readme.mdやmain.tspも変更対象に含まれている点です。Azure REST APIの仕様ファイルは、REST APIドキュメント、SDK生成、ARMテンプレートやBicepのリファレンス生成に関係することがあります。そのため、ドキュメントだけを読んでいる利用者よりも、API仕様からSDKやIaC定義を自動生成しているチームほど注意が必要です。(GitHub)
対象サービスはAzure Device Registry
今回の変更で中心になるのは、Azure Device Registryです。Microsoft LearnのDevice Registry REST説明では、Device Registryはクラウドとエッジ上のデバイスやアセットを単一のレジストリとして扱い、クラウド側ではAzureリソースとして管理し、エッジ側ではKubernetesのカスタムリソースと同期する仕組みとして説明されています。(Microsoft Learn)
つまり、影響確認が必要なのは「Azure REST APIを直接叩いている開発者」だけではありません。次のような担当者も確認対象になります。
| 担当者・チーム | 確認すべき理由 |
|---|---|
| Azure REST APIを直接呼び出す開発者 | URLのapi-version=2026-11-01-preview指定が残っていると、将来的にドキュメントや仕様参照とずれる可能性がある |
| Bicep / ARMテンプレート利用者 | Microsoft.DeviceRegistry/...@2026-11-01-previewを使っているテンプレートがあるか確認が必要 |
| Terraform AzAPI利用者 | type = "Microsoft.DeviceRegistry/...@2026-11-01-preview"のような指定が残っていないか確認する |
| SDK生成・内製ツール担当者 | AutoRest、TypeSpec、OpenAPI仕様を使った自動生成が失敗する可能性がある |
| IoT / エッジ管理基盤の運用担当者 | Device Registryのアセット、デバイス、スキーマ関連操作に依存がないか確認する |
Microsoft LearnのARM/Bicepリファレンスでは、たとえばMicrosoft.DeviceRegistry/namespaces/devicesの2026-11-01-previewページに、Bicep、ARMテンプレート、Terraform AzAPI向けの記述例が掲載されています。こうした参照をもとにテンプレートを作った環境では、該当バージョンの利用有無を優先的に確認しましょう。(Microsoft Learn)
影響を受けやすいAPI・リソースの範囲
PRのファイル一覧を見ると、assets、assetEndpointProfiles、namespaces、namespaces/devices、namespaces/assets、schemaRegistries、schemas、schemaVersionsなど、Device Registryの主要な管理リソースに関するサンプルが削除対象に含まれています。(GitHub)
実務では、次の3種類の依存を探すと効率的です。
REST APIのURLにapi-version=2026-11-01-previewがある
アプリケーションコード、PowerShellスクリプト、CI/CDのデプロイスクリプト、検証用curlコマンドを検索します。
grep -R "2026-11-01-preview" .
grep -R "Microsoft.DeviceRegistry" .たとえば、次のような呼び出しが残っている場合は要確認です。
GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.DeviceRegistry/namespaces/{namespaceName}/devices/{deviceName}?api-version=2026-11-01-previewこの場合、単純に文字列だけを置き換えるのではなく、移行先APIバージョンでリクエスト本文、レスポンス、必須プロパティ、列挙値が変わっていないかを確認してください。
BicepやARMテンプレートにAPIバージョン指定がある
Bicepでは、次のような指定が確認対象です。
resource device 'Microsoft.DeviceRegistry/namespaces/devices@2026-11-01-preview' = {
name: 'device01'
}ARMテンプレートでは、次のようなapiVersionを検索します。
{
"type": "Microsoft.DeviceRegistry/namespaces/devices",
"apiVersion": "2026-11-01-preview"
}Microsoft Learnの該当リファレンスにも、apiVersionとして2026-11-01-previewを使う例が掲載されています。ドキュメント更新後にこのバージョンが選択肢から外れる場合、テンプレート作成時の参照元が変わる可能性があります。(Microsoft Learn)
SDK生成や型定義にpackage-preview-2026-11がある
Azure REST API仕様のreadme.mdでは、package-preview-2026-11タグがMicrosoft.DeviceRegistry/preview/2026-11-01-preview/deviceregistry.jsonを参照する構成になっています。(GitHub)
AutoRestや独自の生成パイプラインで次のような指定をしている場合は、削除後に生成が失敗する可能性があります。
autorest readme.md --tag=package-preview-2026-11このケースでは、移行候補として安定版の2026-04-01や2025-10-01、または別のプレビュー版を検討します。ただし、バージョン間で対応リソースやプロパティが異なる可能性があるため、生成結果のコンパイル確認だけでなく、実際のAPI呼び出しテストまで行うべきです。
すぐに確認すべき変更点チェックリスト
今回の変更は、PR上ではOpen状態であり、NotReadyForARMReviewやVersioningReviewRequiredなどのラベルも確認できます。さらに、GitHub Actionsのコメントでは、Azureのバージョニングポリシーに関するレビューが必要であること、Swagger BreakingChangeチェックが失敗していることも示されています。(GitHub)
そのため、現段階での対応は「本番反映済みとして慌てて置き換える」よりも、以下の順で進めるのが安全です。
| 優先度 | 確認項目 | 判断基準 |
|---|---|---|
| 高 | コード内の2026-11-01-preview検索 | 本番・検証・サンプルのどこに残っているかを分類する |
| 高 | IaC定義のAPIバージョン確認 | Bicep、ARM、Terraform AzAPIで該当バージョンを使っていないか確認する |
| 高 | SDK生成パイプラインの確認 | package-preview-2026-11や該当OpenAPIファイルを参照していないか確認する |
| 中 | Microsoft Learnのバージョン選択肢確認 | 最新、安定版、プレビュー版のどれを使うべきか整理する |
| 中 | レスポンス差分の確認 | 移行候補バージョンで必須項目や型が変わらないか確認する |
| 低 | サンプルコードの棚卸し | 社内Wiki、検証メモ、PoCコードに古い指定が残らないよう更新する |
ポイントは、本番コードとサンプルコードを同じ扱いにしないことです。サンプルに残っているだけなら急ぎ度は低いですが、CI/CDや本番デプロイテンプレートに残っている場合は、早めに移行候補を決める必要があります。
移行先APIバージョンをどう選ぶべきか
Azure REST APIでは、日付形式のAPIバージョンが使われます。previewが付くバージョンは新機能検証向けであり、安定版より変更リスクが高いと考えて運用するのが基本です。
Azure SDKのREST API仕様インベントリでは、Device Registryの安定版として2026-04-01、2025-10-01、2024-11-01が確認でき、プレビュー版として2026-11-01-preview、2026-03-01-preview、2025-11-01-preview、2025-07-01-previewなどが並んでいます。(Azure)
移行先を選ぶときは、次の基準で判断します。
| 選択肢 | 向いているケース | 注意点 |
|---|---|---|
| 安定版の最新APIバージョン | 本番運用、長期運用、変更リスクを下げたい場合 | preview限定の機能が使えない可能性がある |
| 直近の別プレビュー版 | 検証環境、preview機能が必要なPoC | 将来の変更・削除に備えた追跡が必要 |
| 現行バージョン維持 | PRが未マージで、短期的な検証のみ続ける場合 | ドキュメントや生成仕様から外れた後に対応が遅れる可能性がある |
実務では、まず2026-04-01のような安定版で要件を満たせるか確認し、どうしてもプレビュー機能が必要な場合だけ別のpreviewバージョンを選ぶのが無難です。特に本番のIaCテンプレートでは、プレビューAPIを固定して使い続けると、将来の仕様変更に追随するコストが高くなります。
設定確認の具体的な進め方
リポジトリ全体を検索する
まず、アプリケーション、インフラコード、CI/CD定義、社内ドキュメントをまとめて検索します。
grep -R "2026-11-01-preview" .
grep -R "package-preview-2026-11" .
grep -R "Microsoft.DeviceRegistry" .GitHubを使っている場合は、リポジトリ検索で次の語句を入れると見つけやすくなります。
"2026-11-01-preview"
"Microsoft.DeviceRegistry"
"package-preview-2026-11"検索結果は、次のように分類してください。
| 分類 | 例 | 対応 |
|---|---|---|
| 本番コード | API呼び出し、SDK利用、デプロイスクリプト | 移行候補を決めて検証環境で差分確認 |
| IaC | Bicep、ARM、Terraform AzAPI | APIバージョン変更後にデプロイ差分を確認 |
| 生成設定 | AutoRest、TypeSpec、OpenAPI参照 | 生成コマンドと出力SDKを再検証 |
| サンプル・メモ | 社内Wiki、PoC、検証用curl | 誤利用を防ぐため注記または更新 |
移行候補バージョンで差分を見る
APIバージョンを変えるときは、単にapi-versionの文字列を変更するだけでは不十分です。次の項目を確認します。
| 確認項目 | 見るべきポイント |
|---|---|
| リソースタイプ | 対象のMicrosoft.DeviceRegistry/...が移行先バージョンにも存在するか |
| 必須プロパティ | location、extendedLocation、properties内の必須項目が変わっていないか |
| 認証・証明書関連 | X.509、ユーザー名/パスワード、シークレット名の指定が変わっていないか |
| レスポンス構造 | 既存コードが参照しているフィールドが残っているか |
| 非同期操作 | 作成・削除・更新操作の完了待ちロジックに影響がないか |
Device Registryでは、デバイス、アセット、スキーマ、スキーマバージョン、エンドポイント、証明書関連の設定を扱うため、プロパティ差分の見落としが運用トラブルにつながりやすい領域です。
検証環境でデプロイとロールバックを試す
移行前に、最低限次のテストを行います。
| テスト | 目的 |
|---|---|
| テンプレートのwhat-if / plan | APIバージョン変更で意図しない再作成が起きないか確認 |
| 新規作成テスト | 移行先バージョンでリソースが作れるか確認 |
| 既存リソース更新テスト | 既存リソースに対するPATCH/PUTが通るか確認 |
| GET/Listテスト | 運用監視や棚卸し処理が壊れないか確認 |
| 削除・復旧テスト | 検証環境でライフサイクル操作に問題がないか確認 |
とくにIaCでは、APIバージョンを変更しただけで差分が出る場合があります。差分が出たときは、「実体のリソース変更」なのか「スキーマ解釈の違い」なのかを切り分けてください。
よくある失敗パターン
ドキュメント削除をサービス停止と誤解する
今回のPRは、仕様リポジトリ上ではOpen状態で確認されています。さらに、レビューやバージョニングに関するブロッキング項目が示されているため、現時点で「2026-11-01-previewの実APIがすでに使えない」と断定するのは避けるべきです。(GitHub)
ただし、ドキュメントや仕様から外れるAPIバージョンを使い続けると、将来的な調査・障害対応・SDK生成が難しくなります。動いているかどうかだけで判断せず、管理可能なバージョンへ寄せることが重要です。
preview版を本番の長期運用に固定する
preview版は、新機能の検証では有用です。一方で、本番システムの長期運用では、仕様変更や削除の影響を受けやすくなります。
本番でpreview版を使う必要がある場合は、最低限次のルールを設けましょう。
| ルール | 理由 |
|---|---|
| 利用理由を設計書に残す | なぜ安定版ではなくpreview版が必要なのかを後から判断できる |
| 代替バージョンを定期確認する | 安定版に取り込まれた時点で移行しやすくする |
| APIバージョンをコードレビュー対象にする | 何気ないコピー&ペーストでpreview版が増えるのを防ぐ |
| 障害時の切り戻し手順を用意する | 仕様変更時に復旧判断を早くする |
SDKやツールの自動生成だけ確認して終わる
SDKが生成できても、実際のAPI呼び出しが同じように動くとは限りません。型定義の生成、コンパイル、単体テスト、実APIに対する結合テストは別物です。
特にDevice Registryのようにクラウドとエッジの同期を含むサービスでは、作成・更新・削除後の状態反映まで確認する必要があります。GETが成功するだけでなく、エッジ側や運用監視で期待どおり見えるかも確認しましょう。
今回の更新で取るべき対応
今回のAzure REST API documentation updateは、2026-11-01-previewという将来日付のプレビューAPIバージョンをAzure Device Registryの仕様から削除する内容です。PRでは多数のサンプル、OpenAPI仕様、生成設定が削除対象になっており、SDK生成やIaC参照に影響する可能性があります。(GitHub)
まずは、自社環境で次の3点を確認してください。
- コード、IaC、CI/CD、社内ドキュメントに
2026-11-01-previewが残っていないか検索する Microsoft.DeviceRegistryを使う処理がある場合、安定版APIバージョンで代替できるか確認する- preview版を使い続ける必要がある場合、理由・移行候補・検証手順を明文化する
Azure REST APIのapi-version変更は、見た目には小さな文字列変更に見えます。しかし実際には、テンプレート生成、SDK、運用手順、監視、障害対応に波及します。今回のようなドキュメント更新を見つけたら、まず依存箇所を洗い出し、安定版へ寄せられる部分から移行計画を立てるのが最も安全です。
コメント