Azure REST APIの「[TSP Migration] Migrating Microsoft.DeviceUpdate DataPlane from Swagger to Typespec」は、Device Update for IoT HubのData Plane API仕様を、従来のSwagger中心の管理からTypeSpec中心の管理へ移す更新です。結論として、通常のREST API呼び出しをしているアプリ開発者は、すぐにエンドポイントやAPIバージョンを変更する必要はありません。一方で、OpenAPI定義をCIで差分チェックしているチーム、SDKを自動生成しているチーム、Azure API ManagementやPostmanなどに仕様ファイルを取り込んでいるチームは、生成されたSwaggerの差分とSDK生成結果を確認すべきです。
今回のPRでは、既存のGA APIバージョン2022-10-01を対象にしたTypeSpec移行であり、PR本文では「API surface changesはない」と説明されています。新しい仕様の正本はDeviceUpdate配下のmain.tsp、routes.tsp、models.tsp、client.tsp、tspconfig.yamlへ移り、従来のMicrosoft.DeviceUpdate/stable/2022-10-01/deviceupdate.jsonは生成物として扱われます。(GitHub)
今回のAzure REST API更新で何が変わるのか
今回の変更を一言でまとめると、Microsoft.DeviceUpdate Data PlaneのAPI仕様管理方法がSwaggerからTypeSpecへ移行するというものです。
Azure REST APIの仕様は、Azure公式のazure-rest-api-specsリポジトリが正本として扱われています。リポジトリのREADMEでも、Microsoft AzureのREST API仕様のcanonical sourceであると説明されています。(GitHub)
TypeSpecは、APIを設計・定義するための言語です。Microsoft Learnでは、TypeSpecはAPI仕様、クライアントコード、サーバー側コードなどをemittersで生成でき、OpenAPI emitterによって既存のOpenAPIベースのワークフローとも互換性を保てると説明されています。(Microsoft Learn)
今回の更新で重要なのは、「APIそのものを新しくする」よりも「API仕様の書き方と生成の流れを変える」点です。
| 確認項目 | 今回の内容 | 実務上の意味 |
|---|---|---|
| 対象API | Microsoft.DeviceUpdate Data Plane | Device Update for IoT Hubのデータ操作APIが対象 |
| 対象バージョン | GA API version 2022-10-01 | preview版への移行ではない |
| 仕様の正本 | Swagger JSONからTypeSpecファイルへ | 今後の仕様修正は.tsp側を見る必要がある |
| 生成物 | deviceupdate.jsonがTypeSpecから生成される | APIMやSDK生成では生成後のOpenAPI差分を確認する |
| SDKリリース | PR上は「No SDK release plan required」 | ただし独自生成SDKや型差分の確認は必要 |
| 破壊的変更 | REST APIレベルではbenign扱いのラベルあり | 実呼び出し影響は限定的と見られるが、生成SDK差分は確認する |
PRにはdata-plane、TypeSpec、BreakingChangeReviewRequiredなどのラベルが付与され、後にBreakingChange-Approved-Benignも付与されています。このラベル説明では、REST APIレベルでは破壊的ではなく、生成SDKへの影響もあっても軽微とされています。(GitHub)
すぐ対応が必要な人、様子見でよい人
今回のAzure REST API documentation updateは、すべての利用者に同じ影響を与えるわけではありません。自社の使い方に応じて、対応の優先度を分けて考えるのが現実的です。
| 利用者・担当者 | 対応優先度 | 確認すべきこと |
|---|---|---|
| REST APIを直接呼び出しているアプリ開発者 | 低〜中 | api-version=2022-10-01、認証、主要APIのレスポンスが変わらないか |
| Azure SDKをそのまま使う利用者 | 低 | 公式SDK更新が出た場合のみリリースノートを確認 |
| 自社でSDKを自動生成しているチーム | 高 | Python、JavaScript、Javaなどの生成差分、メソッド名、型、nullable、enumの差分 |
| OpenAPI定義をCIで比較しているチーム | 高 | Swagger再生成による形式差分を実際のAPI破壊と誤判定しないようにする |
| Azure API Managementに仕様をインポートしている担当者 | 中 | deviceupdate.jsonの再インポート時に検証ルールや必須項目が変わらないか |
| Device Updateの更新配信フローを運用している担当者 | 中 | Import Update、Delete Update、Import Devicesなどの長時間操作のポーリング挙動 |
PR上ではAPIViewによるAPI Change Checkが走り、Swagger、TypeSpec、Python、JavaScript、JavaのAPIレビューが作成されています。これは、REST API呼び出しが変わらない場合でも、SDK生成や型定義の見え方に差分が出る可能性があることを示します。(GitHub)
変更点を読むときのポイント
Swaggerが消えるのではなく、TypeSpecから生成される
初心者が誤解しやすい点は、「SwaggerからTypeSpecへ移行」と聞くと、OpenAPI/Swaggerのファイルが使えなくなるように見えることです。
実際には、TypeSpecが新しい正本になり、そこからSwagger 2.0形式のdeviceupdate.jsonが生成されます。生成されたSwaggerにはx-typespec-generatedが含まれ、@azure-tools/typespec-autorestによって出力されていることが分かります。(GitHub)
つまり、APIM、Postman、独自SDK生成ツールなどがOpenAPIファイルを必要とする場合でも、基本的には生成後のSwaggerを引き続き参照できます。ただし、手作業でdeviceupdate.jsonを修正する運用は避けるべきです。今後の修正はTypeSpec側に入れ、コンパイル結果としてSwaggerを確認する流れに寄せる必要があります。
APIバージョンは2022-10-01のまま
PR内のコミット説明では、移行対象がGAの2022-10-01へリターゲットされ、preview専用のgetLimits操作やLimitsResponse、Counters、UsageQuotaCounterなどが除外されたことが示されています。出力先もMicrosoft.DeviceUpdate/stable/2022-10-01/になっています。(GitHub)
そのため、既存クライアントが突然preview APIへ切り替わる更新ではありません。実装側で確認すべきなのは、api-versionを変えることではなく、同じAPIバージョンで生成された仕様差分が、自社のツールやテストにどう見えるかです。
Data Plane APIのため、ARM管理APIとは切り分ける
Microsoft.DeviceUpdate Data Planeは、Device Update for IoT Hubの更新、デバイス、グループ、デプロイ、診断ログなどを扱うAPIです。Azureリソースそのものを作成・更新するARMのManagement Plane APIとは確認観点が異なります。
生成Swaggerには、ホストがhttps://{endpoint}として定義され、endpointはDevice Update for IoT Hubアカウントのエンドポイントとしてclient parameter扱いになっています。また、各操作ではapi-versionが必須のquery parameterとして定義されています。(GitHub)
設定確認では、AzureリソースIDやARM APIのバージョンではなく、次の3点を優先して見ます。
| 確認項目 | 見るべき値 |
|---|---|
| endpoint | Device Updateアカウントのエンドポイント。プロトコルを重複して付けない |
| instanceId | Device Update for IoT HubアカウントのインスタンスID |
| api-version | 2022-10-01 |
特に確認したいAPI仕様上の差分
長時間操作はOperation-Locationベースで確認する
今回のPRでは、ImportUpdate、DeleteUpdate、ImportDevicesの202レスポンスについて、LocationではなくOperation-Locationヘッダーを持つため、final-state-viaをoperation-locationに設定する変更が入っています。(GitHub)
生成Swagger上でも、DeviceManagement_ImportDevicesやDeviceUpdate_ImportUpdateは長時間操作として定義され、202レスポンスにOperation-Locationヘッダーが含まれています。(GitHub)
自社実装で次のようなコードを書いている場合は、確認が必要です。
POSTでImportUpdateを実行
↓
202 Acceptedを受け取る
↓
Locationヘッダーを見に行くこの流れがLocation前提になっていると、実際の仕様とずれる可能性があります。確認すべき流れは次の通りです。
| 手順 | 確認内容 |
|---|---|
| 1 | 202レスポンスでOperation-Locationを取得できるか |
| 2 | 取得したURLまたはoperationIdでステータス確認できるか |
| 3 | ステータス確認レスポンスのRetry-Afterを考慮しているか |
| 4 | Succeeded、Failed、Running、NotStartedの処理分岐があるか |
DeviceManagement_GetOperationStatusとDeviceUpdate_GetOperationStatusの200レスポンスには、再確認までの秒数を示すRetry-Afterヘッダーが定義されています。短い間隔でポーリングしすぎる実装は避け、Retry-Afterがある場合はそれを優先するのが安全です。(GitHub)
nextLinkの扱いはページング処理で確認する
PRのコミットには、ListLogCollectionsのnextLink例を修正する内容が含まれています。(GitHub)
nextLinkは一覧取得APIで次ページをたどるための重要な値です。SDKを使っている場合は自動で処理されることが多いですが、RESTを直接叩いている場合は次のようなミスが起きやすくなります。
| 失敗しやすい実装 | 問題点 |
|---|---|
1ページ目のvalueだけ処理して終了する | 件数が多い環境でデータが欠落する |
nextLinkを相対URLとして固定処理する | 生成例や仕様差分で動かなくなる可能性がある |
topを指定すれば全件取れると思い込む | サービス側の上限やページングに依存する |
一覧系APIを運用監視やレポートに使っている場合は、nextLinkを最後までたどるテストを1つ入れておくと、仕様再生成による差分に強くなります。
ハッシュ、互換性情報、ステップ数の制約を確認する
レビューコメントでは、ハッシュや互換性プロパティに関するminItems、maxItemsの扱いが議論されています。特に、更新ファイルのハッシュ、互換性情報、インストール手順のステップは、Device Updateの実運用に直結します。(GitHub)
生成Swaggerでは、たとえばImportUpdateInputはminItems: 1、maxItems: 11、filesはminItems: 1、maxItems: 5として定義されています。また、Update.compatibilityはminItems: 1、maxItems: 10、Instructions.stepsはminItems: 1、maxItems: 10です。(GitHub)
このあたりは、APIが実際に受け付ける値と、SDKやバリデーションツールが事前に弾く値に差が出るとトラブルになります。
確認するなら、次のケースを用意します。
| テストケース | 目的 |
|---|---|
| ハッシュが空のimport manifest | 必須ハッシュのバリデーション確認 |
| compatibilityが0件の更新 | 互換性情報の必須制約確認 |
| compatibilityが上限を超える更新 | SDKまたはAPI側の上限制御確認 |
| filesが6件以上の更新 | ファイル件数制約の確認 |
| stepsが0件または11件以上の更新 | インストール手順の制約確認 |
移行・設定確認の実務手順
まずPRの状態と差分を確認する
PR画面では、2026年5月8日時点の表示としてOpen状態、レビュー待ち、requested changesに関する表示が確認できます。PRの状態は変わる可能性があるため、実際に採用する前に最新のレビュー状態、マージ状態、ラベルを確認してください。(GitHub)
確認時は、次の順番で見ると判断しやすくなります。
| 順番 | 確認対象 | 見るポイント |
| -: | ————— | ——————————————————– |
| 1 | PR本文 | API surface changesなし、対象バージョン、正本ファイル |
| 2 | Labels | BreakingChange-Approved-Benign、TypeSpec、data-plane |
| 3 | Files changed | .tsp、.yaml、生成deviceupdate.json、examples |
| 4 | APIView | Swagger、TypeSpec、各言語SDKの差分 |
| 5 | Review comments | 未解決の制約、型、例、LRO関連の指摘 |
Files changedでは、.jsonが101件、.tspが4件、.yamlが1件として表示されています。TypeSpec本体だけでなく、多数のexample JSONと生成Swaggerも差分対象になるため、単純なファイル数だけで「大規模なAPI変更」と判断しないことが大切です。(GitHub)
ローカルでTypeSpecをコンパイルして確認する
Azure REST API仕様のTypeSpec開発手順では、Node.js LTS 18以上、npm ci、npx tsp --version、npx tsp compileによる生成確認が案内されています。(GitHub)
実務では、次の流れで確認します。
git fetch upstream pull/42869/head:deviceupdate-tsp-migration
git checkout deviceupdate-tsp-migration
npm ci
cd specification/deviceupdate/data-plane/DeviceUpdate
npx tsp compile .生成後は、少なくとも次のファイルを確認します。
| ファイル | 確認内容 |
|---|---|
DeviceUpdate/main.tsp | サービス名、認証、APIバージョン、server定義 |
DeviceUpdate/routes.tsp | operationId、route、LRO、query/header/body定義 |
DeviceUpdate/models.tsp | enum、必須項目、配列上限、日時型 |
DeviceUpdate/client.tsp | SDK生成時のclientLocation、clientName、初期化パラメーター |
DeviceUpdate/tspconfig.yaml | emitter設定、生成先、SDK言語別設定 |
Microsoft.DeviceUpdate/stable/2022-10-01/deviceupdate.json | 最終的に外部ツールへ渡すOpenAPI定義 |
tspconfig.yamlでは、@azure-tools/typespec-autorestの出力先がMicrosoft.DeviceUpdate/{version-status}/{version}/deviceupdate.jsonに設定されています。Python、Java、TypeScript向けのemitter設定も含まれているため、独自にSDK生成している場合はこのファイルを必ず確認してください。(GitHub)
既存Swaggerとの差分を「実害あり」と「生成差分」に分ける
TypeSpec移行では、同じAPIを表していてもSwaggerの書き出し方が変わることがあります。PR内のコミット説明でも、292件のBreakingChange CI項目がTypeSpec再emitによって報告され、それらはparameter inliningやtype/format precisionなどのemitter normalizationで、wire impactはゼロと説明されています。(GitHub)
差分を見るときは、次の分類を使うと判断しやすくなります。
| 差分の種類 | 例 | 判断 |
|---|---|---|
| 実害が出やすい差分 | path、method、status code、required、enum値の変更 | 優先して調査 |
| SDKに影響しやすい差分 | operationId、x-ms-client-name、x-ms-parameter-location | 生成SDKのメソッド名・引数を確認 |
| バリデーションに影響しやすい差分 | minItems、maxItems、minLength、format | APIM、JSON Schema検証、テストデータを確認 |
| 生成差分の可能性が高い差分 | パラメーターのインライン化、説明文、定義順序 | 自動検出だけで障害扱いにしない |
| 認証まわりの差分 | securityDefinitionsのキー名 | 実際のOAuth flow、scopeが変わらないか確認 |
認証については、TypeSpec側でAzureAuthをaliasとして定義し、Swagger出力上のキーが変わるが、OAuth2のflow、authorization URL、scopeには影響しないというコメントが含まれています。(GitHub)
よくある誤解と注意点
「BreakingChangeReviewRequired」だけで本番影響ありと判断しない
BreakingChangeReviewRequiredというラベルを見ると、すぐに本番影響があるように感じるかもしれません。しかし今回のPRでは、後にBreakingChange-Approved-Benignラベルが付与されており、REST APIレベルでは破壊的ではなく、生成SDKにも軽微な影響にとどまるという扱いです。(GitHub)
ただし、これは「確認不要」という意味ではありません。自社のCIがSwagger差分を機械的に検出している場合、TypeSpec生成による書式差分を破壊的変更として誤検知する可能性があります。
deviceupdate.jsonを手作業で直さない
TypeSpec移行後は、deviceupdate.jsonは生成物として見るべきです。Swagger側だけを手作業で直すと、次回のnpx tsp compileで差分が戻る可能性があります。
正しい流れは次の通りです。
TypeSpecを修正
↓
npx tsp compile
↓
生成されたdeviceupdate.jsonとexamplesを確認
↓
APIViewまたは独自diffで検証preview APIの機能が残っている前提で見ない
今回のPRはGA 2022-10-01へリターゲットされています。preview専用の操作やモデルは削除対象として扱われています。(GitHub)
そのため、2023-10-01-previewなどのpreview仕様と比較して「機能が消えた」と判断するのは早計です。比較対象は、同じGA 2022-10-01の旧Swaggerにそろえる必要があります。
SDKのメソッド配置を確認する
client.tspでは、各operationに対してDeviceUpdateやDeviceManagementなどのclientLocationが指定されています。また、LogCollection.operationIdなどにlogCollectionIdというclientNameが指定されています。(GitHub)
SDKを自動生成している場合、次の点を確認します。
| 確認項目 | 例 |
|---|---|
| メソッドの所属 | DeviceUpdate側かDeviceManagement側か |
| 引数名 | operationIdがSDK上でlogCollectionIdになるか |
| client初期化 | instanceIdがコンストラクター側に出るか |
| 型名 | enumやmodel名が既存SDKと互換か |
| nullable/optional | 以前optionalだった値が必須扱いになっていないか |
最低限やるべき確認チェックリスト
今回のAzure REST API documentation updateに対して、実務で最低限見るべき項目は次の通りです。
| チェック | 対象 | 完了条件 |
|---|---|---|
| PR状態の確認 | PR #42869 | マージ状態、レビュー状態、ラベルを確認した |
| APIバージョン確認 | 2022-10-01 | 既存利用バージョンと一致している |
| OpenAPI差分確認 | deviceupdate.json | path、method、status code、requiredの差分を確認した |
| LRO確認 | ImportUpdate、DeleteUpdate、ImportDevices | Operation-LocationとRetry-Afterを使った処理を確認した |
| ページング確認 | 一覧系API | nextLinkを最後まで処理するテストがある |
| SDK生成確認 | Python、JavaScript、Javaなど | メソッド名、引数、型の差分を確認した |
| APIM・Postman確認 | 仕様インポート | 再インポート時の警告や検証エラーを確認した |
| CIルール確認 | Swagger diff | TypeSpec生成差分を誤検知しないよう分類した |
まとめ：まずは「API利用への直接影響」と「仕様生成への影響」を分けて確認する
今回のAzure REST API documentation updateは、Microsoft.DeviceUpdate Data Planeの仕様管理をSwaggerからTypeSpecへ移行する更新です。PR本文では、既存GA API version 2022-10-01のTypeSpec移行であり、新しいAPI surfaceの追加ではないと説明されています。(GitHub)
まずやるべきことは、アプリのREST呼び出しが変わるかどうかを確認することです。多くの場合、エンドポイントやapi-versionを急いで変更する必要はありません。
次に、仕様ファイルを使っている周辺システムを確認します。SDK生成、APIMインポート、Postmanコレクション生成、Swagger差分CI、契約テストを運用している場合は、生成されたdeviceupdate.jsonと旧Swaggerの差分を見てください。特に、長時間操作のOperation-Location、Retry-After、ページングのnextLink、ハッシュや互換性情報の制約は、実装ミスが起きやすいポイントです。
最後に、今後Microsoft.DeviceUpdate Data Planeの仕様を追うときは、SwaggerだけでなくTypeSpecファイルを確認する習慣を持つことが重要です。main.tspでサービス全体、routes.tspで操作、models.tspで型と制約、client.tspでSDK生成上の見え方、tspconfig.yamlで出力設定を見る。この順番で確認すれば、TypeSpec移行後のAzure REST API変更にも落ち着いて対応できます。
コメント