Azure REST API documentation update: [SDK Validation] Use azsdk-cli and onboard Rust は、Azure REST APIのエンドポイントや認証方式を変更する更新ではありません。主な変更は、azure-rest-api-specs のSDK検証・SDK生成パイプラインに、Rust SDK生成を azsdk-cli で扱う経路を追加することです。
結論から言うと、Azure REST APIを呼び出しているアプリケーション開発者は、すぐにコードを書き換える必要はほぼありません。一方で、TypeSpecでAzure REST API仕様を管理しているチーム、SDK自動生成のCIを運用しているチーム、Rust SDKの生成・レビューに関わる担当者は、azsdk-cli、Rust toolchain、tspconfig.yaml のRust emitter設定を確認すべきです。PR #42692では、Rust SDK生成への対応、生成ツールの選択ロジック、azsdk-cli出力を既存の ExecutionReport に合わせるアダプターなどが追加されています。(GitHub)
Azure REST APIの今回のdocumentation updateは何が変わるのか
今回の「Azure REST API documentation update: [SDK Validation] Use azsdk-cli and onboard Rust」は、Azure REST API仕様そのものの追加・削除というより、仕様からSDKを生成・検証する内部ワークフローの更新です。
Azure REST API仕様のリポジトリである azure-rest-api-specs は、Microsoft AzureのREST API仕様の中心的な管理場所です。仕様が完成した後は、SDKやAPIリファレンスドキュメントの生成につながるため、仕様ファイルの変更だけでなく、SDK生成パイプラインの変更もサービスチームやSDK利用者に影響します。(GitHub)
今回の変更を一言で表すと、Rust向けのTypeSpec SDK生成を、従来の spec-gen-sdk だけでなく新しい azsdk-cli 経由で扱えるようにする更新です。
| 変更項目 | 内容 | 実務上の意味 |
|---|---|---|
| Rust SDK生成の追加 | azure-sdk-for-rust がSDK言語として扱われる | Rust SDKの自動生成・検証対象が広がる |
azsdk-cli の利用 | Rust TypeSpec仕様では azsdk pkg generate、azsdk pkg build、azsdk pkg pack を使う流れを追加 | CIで azsdk-cli とRust toolchainが必要になる |
| 生成ツールの選択 | 言語と仕様タイプに応じて azsdk-cli か spec-gen-sdk を選ぶ | OpenAPIや既存言語は基本的に従来経路のまま |
| emitter確認 | typespec-metadata で対象言語のemitterが有効か確認 | tspconfig.yaml にRust生成設定がなければ notEnabled になる |
| レポート変換 | azsdk-cli のJSON出力を既存の ExecutionReport 形式に変換 | 既存のSDK Validation結果処理に接続しやすくなる |
影響を受ける人と受けない人
今回のAzure REST API documentation updateで重要なのは、「REST APIの利用者」と「REST API仕様・SDK生成の担当者」で影響範囲が大きく違う点です。
| 立場 | 対応の必要性 | 確認すべきこと |
|---|---|---|
| Azure REST APIをHTTPで直接呼び出す開発者 | 低い | エンドポイント、HTTPメソッド、認証、API versionの変更ではないため通常は対応不要 |
| 既存のAzure SDK利用者 | 低〜中 | Rust SDKの生成や配布状況を追っている場合のみ確認 |
| Azure REST API仕様をTypeSpecで管理するチーム | 高い | tspconfig.yaml でRust emitterが有効か、metadataにRust情報が出るか |
| SDK生成パイプラインを運用するチーム | 高い | azsdk-cli、Rust toolchain、AZSDK 環境変数またはPATHの設定 |
OpenAPI readme.md ベースの仕様担当者 | 低い | 原則として従来の spec-gen-sdk 経路が使われる |
| Rust SDKのレビュー担当者 | 高い | generate/build/packの各段階、成果物、API Viewの扱い |
つまり、読者が確認すべき最初の判断基準は次の2つです。
- 自分の変更対象が
tspconfig.yamlを持つTypeSpec仕様か - 対象SDK言語が
azure-sdk-for-rustか
この2つに該当する場合は、今回の更新内容をCI・レビュー手順に反映する必要があります。
Rust SDK生成では azsdk-cli が選択される
PR内の実装では、tspConfigPath があり、SDK言語が azure-sdk-for-rust で、azsdk-cli が利用可能な場合に azsdk-cli 経路を選ぶロジックが追加されています。一方、その他の言語やOpenAPI仕様では、基本的に既存の spec-gen-sdk 経路が使われます。azsdk-cli が必要なのに見つからない場合は unsupported として扱われます。(GitHub)
実務では、次のように考えると分かりやすいです。
| 仕様タイプ | SDK言語 | 使われる生成経路 |
|---|---|---|
| TypeSpec | Rust | azsdk-cli |
| TypeSpec | Go、Java、JavaScript、.NET、Pythonなど | 原則 spec-gen-sdk |
| OpenAPI | Rust以外を含む既存経路 | 原則 spec-gen-sdk |
TypeSpec + Rustだが azsdk-cli がない | Rust | unsupported として失敗扱い |
ここで注意したいのは、「Rust SDKに対応した」という表現が、すべての仕様から自動的にRust SDKが生成されるという意味ではないことです。TypeSpec側でRust向けのemitter設定が有効になっていない場合、生成処理は進まず notEnabled として扱われます。
azsdk-cli の生成フローで確認すべきポイント
azsdk-cli 経路では、単にSDKを生成するだけでなく、生成前後に複数の処理が入ります。PR内の runAzsdkGeneration では、TypeSpec metadataによるemitter確認、SDK生成、ビルド、パッケージ化、ExecutionReport 作成という流れが実装されています。(GitHub)
| 段階 | 実行内容 | 確認ポイント |
|---|---|---|
| emitter確認 | typespec-metadata で対象言語の設定を確認 | metadataの languages に rust が出るか |
| generate | azsdk pkg generate を実行 | TypeSpec仕様からRust SDKが生成されるか |
| build | azsdk pkg build を実行 | Rustパッケージとしてビルドできるか |
| pack | azsdk pkg pack を実行 | 成果物が作成されるか |
| report | ExecutionReport に変換 | 既存のSDK Validation結果として扱えるか |
CIログを見るときは、「generateが成功したか」だけで判断しないことが重要です。Rust SDKでは、生成後にビルドとパッケージ化が通って初めて、実用上の検証が進んだと考えるべきです。
たとえば、TypeSpecの構文やemitter設定に問題がなくても、生成後のRustコードが依存関係や型定義の都合でビルドに失敗することがあります。この場合、REST API仕様の意味としては正しくても、SDKとしては修正が必要です。
TypeSpecの tspconfig.yaml ではRust emitter設定を確認する
今回の更新で失敗しやすいポイントは、azsdk-cli の有無だけではありません。tspconfig.yaml 側でRust生成が有効になっているかも重要です。
PRでは、@azure-tools/typespec-metadata emitterを使ってTypeSpec metadataを取得し、SDKリポジトリ名から対象言語キーを解決する処理が追加されています。azure-sdk-for-rust は metadata内の rust キーに対応付けられています。対象言語がmetadataに見つからない場合は、emitterが有効ではないと判断されます。(GitHub)
確認時は、次の観点で見てください。
| 確認項目 | 見る場所 | 問題がある場合の症状 |
|---|---|---|
| Rust emitterが有効か | tspconfig.yaml とmetadata出力 | notEnabled になる |
| packageNameが取れるか | typespec-metadata の言語情報 | 生成後のレポートやPR名が不自然になる |
| outputDirが解決できるか | metadataの outputDir | build/pack対象のパッケージパスが見つからない |
| TypeSpec compileが通るか | CIログ | generate前のmetadata確認で失敗する |
実務上は、Rust SDK対応を入れる前に、まずTypeSpec metadataで languages.rust に相当する情報が取れる状態か確認するのが安全です。azsdk-cli を入れても、TypeSpec側がRust生成を宣言していなければ、自動生成は期待通りに進みません。
CIではRust toolchainと azsdk-cli のインストールを確認する
PRでは、SDKリポジトリ名にRustが含まれる場合にRust toolchainをインストールし、install-azsdk-cli.yml テンプレートを使う処理が追加されています。生成ステップでは azsdk-cli の実行ファイルを AZSDK 環境変数またはPATH上の azsdk から解決します。(GitHub)
CIで最低限確認したいコマンドは次の3つです。
azsdk --version
rustc --version
cargo --versionAZSDK 環境変数を使っている環境では、次の観点も確認してください。
echo "$AZSDK"
"$AZSDK" --version失敗時に見落としやすいのは、Rust toolchainは入っているが azsdk-cli が見つからないケースです。この場合、Rustのビルド以前に生成ツール選択の段階で unsupported になります。
OpenAPI仕様や既存SDK言語は基本的に従来経路のまま
今回の更新はRust SDK生成に大きく関係しますが、Azure REST API仕様全体が一律に azsdk-cli へ移行するわけではありません。
実装上は、Rust TypeSpec仕様で azsdk-cli が利用できる場合に新経路を選び、それ以外は spec-gen-sdk を使う設計です。OpenAPI仕様は既存の spec-gen-sdk 経路を使うとPR説明にも記載されています。(GitHub)
そのため、OpenAPIの readme.md だけを変更しているチームが、今回の更新だけを理由にすぐ設定変更する必要は基本的にありません。ただし、将来的にTypeSpecへ移行する予定があるサービスや、Rust SDK生成を追加する予定があるサービスは、今のうちにCIテンプレートと生成ログの見方を整理しておくと移行がスムーズです。
SDK Validationで起きやすい失敗と対処法
今回の更新では、失敗時の原因が「REST API仕様の不備」なのか「SDK生成環境の不備」なのかを切り分けることが重要です。
| 症状 | 主な原因 | 対処 |
|---|---|---|
unsupported になる | Rust TypeSpecなのに azsdk-cli が見つからない | install-azsdk-cli の実行条件、AZSDK、PATHを確認する |
notEnabled になる | tspconfig.yaml でRust emitterが有効ではない | TypeSpec metadataの languages に rust が出るよう設定を確認する |
azsdk pkg generate が失敗する | TypeSpec compile、emitter、package metadataの問題 | generateログとTypeSpec診断を確認する |
azsdk pkg build が失敗する | 生成後Rustコード、依存関係、Cargo設定の問題 | SDKリポジトリ側でビルドログを確認する |
azsdk pkg pack が失敗する | 成果物パスやパッケージ化設定の問題 | metadataの outputDir とpackage pathを確認する |
| API View成果物が出ない | Rust向けAPI View作成がまだ別扱い | API Viewの有無だけで生成失敗と判断しない |
特に注意したいのは、notEnabled です。これは「Azure REST API仕様が壊れている」というより、対象言語のSDK生成設定が有効ではないことを示す状態です。レビューでは、API仕様のレビューとSDK生成設定のレビューを分けて確認すると、原因の切り分けが早くなります。
ExecutionReport と既存ワークフローへの接続も変更点
azsdk-cli はJSON出力を返すため、PRではその出力を解析して既存の ExecutionReport 形式に変換するアダプターが追加されています。これにより、既存のSDK Validationや成果物処理の流れに、Rust SDK生成結果を載せやすくしています。(GitHub)
ただし、Rustは既存言語と完全に同じ扱いではありません。たとえば、共有SDKタイプには azure-sdk-for-rust が追加されていますが、Rust向けのbreaking changeラベルは未定義になっています。また、Rustの必須チェック設定はdata plane、management planeともに false として定義されています。(GitHub)
このため、Rust SDK生成のレビューでは次の点を意識してください。
- 既存言語と同じラベル運用が自動で適用されるとは限らない
- API View成果物の扱いが既存言語と違う可能性がある
ExecutionReportの結果だけでなく、generate/build/packそれぞれのログを見る- Rust SDKとして配布・レビューする段階では、別途SDKリポジトリ側の確認も必要になる
移行・設定確認の手順
Rust SDK生成を利用するチームは、次の順番で確認すると手戻りを減らせます。
| 手順 | 作業 | 判断基準 |
| -: | ————————– | ——————————————— |
| 1 | 対象仕様がTypeSpecかOpenAPIか確認する | tspconfig.yaml なら今回のRust対応対象になり得る |
| 2 | SDK言語がRustか確認する | azure-sdk-for-rust の場合は azsdk-cli 経路を想定する |
| 3 | CIに azsdk-cli があるか確認する | azsdk --version または $AZSDK --version が通る |
| 4 | Rust toolchainを確認する | rustc --version と cargo --version が通る |
| 5 | TypeSpec metadataを確認する | languages に rust が含まれる |
| 6 | package pathを確認する | metadataの outputDir がSDKリポジトリ内の実在パスに解決される |
| 7 | generate/build/packを確認する | 3段階すべてが成功する |
| 8 | 成果物とレポートを確認する | ExecutionReport の結果、成果物フォルダ、ログを確認する |
実際のレビューでは、次のようなチェックリストに落とし込むと便利です。
[ ] 対象仕様はTypeSpecである
[ ] SDK言語は azure-sdk-for-rust である
[ ] CIで azsdk-cli が利用できる
[ ] CIで Rust toolchain が利用できる
[ ] TypeSpec metadata に rust が出ている
[ ] packageName と outputDir が期待通りである
[ ] azsdk pkg generate が成功している
[ ] azsdk pkg build が成功している
[ ] azsdk pkg pack が成功している
[ ] API Viewやbreaking changeラベルの扱いを既存言語と混同していないレビュー時に見るべきログの優先順位
SDK Validationのログを見るときは、上から順に追うよりも、原因が出やすい地点から確認した方が効率的です。
まず見るべきなのは、生成ツールの選択ログです。ここで azsdk-cli ではなく spec-gen-sdk が選ばれている場合、SDK言語や tspConfigPath の指定が期待と違う可能性があります。
次に、emitter確認の結果を見ます。notEnabled の場合は、Rust SDK生成以前にTypeSpec設定の問題です。生成コードの修正ではなく、tspconfig.yaml とmetadata出力を確認します。
その後、azsdk pkg generate、azsdk pkg build、azsdk pkg pack の順に確認します。generateが成功してbuildが失敗している場合は、REST API仕様の構造だけでなく、Rust SDKとして生成されたコードのコンパイル可否が問題になります。packが失敗している場合は、成果物パスやパッケージ化設定を疑います。
REST API利用者が気にすべきこと
Azure REST APIを直接呼び出している開発者にとって、今回の更新はすぐに影響するものではありません。HTTPリクエストのパス、メソッド、リクエスト本文、レスポンス形式、認証方式、API versionを変更する内容ではないためです。
ただし、次のような場合は間接的な影響があります。
- Rust SDKを使ってAzureサービスを操作したい
- 既存サービスのTypeSpec化に伴い、Rust SDK生成の有無を確認したい
- SDK生成の失敗が、REST API仕様のレビューやリリース計画に影響している
- Azure SDKの自動生成PRをレビューしている
つまり、一般のAPI利用者は静観で問題ありませんが、Rust SDKを待っているチームやSDK生成PRをレビューするチームは、今回の変更を追う価値があります。
対応が必要かを判断する基準
最後に、今回のAzure REST API documentation updateへの対応要否を整理します。
| 条件 | 対応 |
|---|---|
| Azure REST APIをHTTPで直接呼び出しているだけ | 対応不要 |
OpenAPI readme.md のみを更新している | 原則対応不要。ただしCI結果は通常通り確認 |
| TypeSpec仕様を更新している | Rust SDK生成の対象か確認 |
azure-sdk-for-rust の生成を予定している | 対応必須 |
| SDK自動生成パイプラインを管理している | azsdk-cli とRust toolchainの導入状況を確認 |
| SDK Validationの結果をレビューしている | unsupported、notEnabled、build/pack失敗の切り分けを確認 |
今回の更新は、Azure REST APIの使い方を変えるものではなく、TypeSpecからRust SDKを生成・検証するための基盤整備です。次に取るべき行動は、自分の担当範囲が「REST API利用」なのか「仕様管理・SDK生成」なのかを切り分けることです。TypeSpecでRust SDK生成に関わる場合は、azsdk-cli、Rust toolchain、tspconfig.yaml のRust emitter、metadataの outputDir を順に確認してください。
コメント