Azure REST API documentation updateとして公開・更新された「[DRAFT] project horizon: adding typespec for the command training job」は、Azure AI FoundryのTraining Jobs APIにCommandJob用のTypeSpec定義を追加するドラフトPRです。結論から言うと、現時点で本番移行を急ぐ変更ではありませんが、Azure AI FoundryのデータプレーンAPI、SDK生成、機械学習トレーニングジョブの自動化を扱うチームは、早めに影響範囲を確認しておくべき内容です。
特に確認すべき点は、Foundry-Features: Jobs=V1Previewヘッダーが必要になること、CommandJobの必須フィールドが明確化されていること、createOrUpdate・beginDelete・beginCancelなどの操作が追加されること、削除・キャンセルが非同期処理として扱われることです。PRはDraftかつOpenの状態で、レビュー上の指摘も残っているため、正式な仕様として実装に固定するのではなく、移行準備・設計レビュー・検証環境での確認材料として読むのが安全です。(GitHub)
Azure REST API documentation updateの要点
今回のAzure REST API documentation updateは、Azure REST APIそのものの全体仕様変更ではなく、Azure AI FoundryのデータプレーンTypeSpecにTraining Jobs APIの定義を追加するPRです。PR説明では、Azure.AI.Projects名前空間の下にTraining Jobs API surfaceを導入し、生成されるPython SDKではclient.beta.training.jobsからアクセスできる想定とされています。(GitHub)
2026年5月5日の更新では、PR内のコミットとしてadding gpucountとfeature/foundry-stagingブランチとのマージが確認できます。つまり、直近の注目点はGPU数指定に関係するgpuCountの追加・調整と、ステージング側との差分取り込みです。(GitHub)
| 確認ポイント | 内容 | 実務で見るべきこと |
|---|---|---|
| APIの位置づけ | Azure AI FoundryのデータプレーンAPI向けTypeSpec追加 | 管理プレーンARM APIではなく、ジョブ操作用APIとして扱う |
| 状態 | Draft・OpenのPR | 本番コードに固定せず、正式マージ後の差分を再確認する |
| 主な対象 | Training Jobs / CommandJob | トレーニングジョブをREST APIやSDKで自動作成するチーム |
| プレビュー条件 | Foundry-Features: Jobs=V1Preview | REST呼び出しやSDK生成時のヘッダー付与を確認する |
| 重要な追加 | gpuCount、ジョブ作成・取得・一覧・削除・キャンセル | GPU利用、非同期削除、キャンセル処理のテストを追加する |
何が変わるのか
Training Jobs APIの操作グループが追加される
PRでは、Training Jobs用の操作としてlist、get、createOrUpdate、beginDelete、beginCancelが追加されています。@tag("Training")、@route("/training")の下でJobsインターフェースが定義され、一覧取得ではjobType、tag、listViewType、propertiesによるフィルタリングが用意されています。(GitHub)
実務上は、次のように理解すると分かりやすいです。
| 操作 | 役割 | 実装時の注意 |
|---|---|---|
list | ジョブ一覧を取得 | タグ、ジョブ種別、アーカイブ状態で絞り込める |
get | 名前でジョブを取得 | ジョブ名は大文字・小文字を区別する前提で扱う |
createOrUpdate | ジョブ作成または更新 | PUT方式。更新時にタグが置き換わる点に注意 |
beginDelete | ジョブ削除 | 202で非同期、存在しない場合は204の可能性 |
beginCancel | ジョブキャンセル | 即時完了なら200、非同期なら202の可能性 |
createOrUpdateは「作成して実行する」操作として定義されており、更新時には渡したtagsが既存タグを置き換える説明があります。タグを差分更新のつもりで送ると、既存タグを消してしまう可能性があるため注意が必要です。(GitHub)
プレビュー機能としてヘッダー指定が必要になる
このTraining Jobs APIは、PR上ではプレビュー機能として扱われています。TypeSpecではJobsPreviewHeaderが定義され、FoundryFeaturesOptInKeys.jobs_v1_preview、つまりJobs=V1Previewが必須ヘッダーとして使われます。(GitHub)
REST APIを直接呼ぶ場合は、次のようなヘッダー確認が必要です。
Foundry-Features: Jobs=V1Previewまた、例示ファイルでもFoundry-FeaturesにJobs=V1Previewを指定したパラメーターが確認できます。(GitHub)
このヘッダーを忘れると、プレビュー機能に対するオプトインが不足し、期待したAPIが使えない可能性があります。APIクライアントを共通化している組織では、通常のAzure REST API呼び出しに加えて、プレビュー機能ごとのヘッダーを安全に付与できる設計にしておくと移行が楽になります。
CommandJobモデルで確認すべきフィールド
今回の中心はCommandJobです。これは、コンテナー内でコマンドを実行してトレーニング処理を行うジョブ定義です。TypeSpecではJobPropertiesをjobTypeで判別する形になっており、CommandJobではjobType: "Command"、command、environmentImageReference、computeが主要な必須要素として定義されています。(GitHub)
最低限必要になる項目
CommandJobを作成する最小構成では、少なくとも次の観点を確認します。
| 項目 | 役割 | 例 |
|---|---|---|
jobType | ジョブ種別 | Command |
command | コンテナー内で実行するコマンド | python train.py |
environmentImageReference | 使用するDockerイメージ | ACRまたはMCRのイメージURL |
computeId | 実行先コンピュート | Azure ML computeのリソースID |
PR内の最小例でも、jobType、command、environmentImageReference、computeIdを含むCommandJob作成例が示されています。(GitHub)
実装イメージは次のようになります。
{
"properties": {
"jobType": "Command",
"command": "python train.py",
"environmentImageReference": "mcr.microsoft.com/azureml/openmpi4.1.0-cuda11.8-cudnn8-ubuntu22.04:latest",
"computeId": "/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.MachineLearningServices/workspaces/<workspace>/computes/<compute-name>"
}
}ここで重要なのは、TypeSpec上のプロパティ名とJSON上の名前が一部異なることです。computeはJSONではcomputeId、codeはJSONではcodeIdとしてエンコードされます。既存の社内ラッパーやテンプレートを流用する場合は、SDKモデル名とRESTのワイヤー形式を混同しないように確認してください。(GitHub)
追加で使える主な項目
CommandJobには、トレーニングジョブの実運用に必要な設定も多く含まれています。代表的な項目は次のとおりです。
| 項目 | 用途 | 確認ポイント |
|---|---|---|
displayName / description | 表示名・説明 | ジョブ一覧で識別しやすい名前を付ける |
tags / properties | 検索・分類用メタデータ | コスト管理、実験名、環境名などを付ける |
codeId | 登録済みコード資産 | バージョン固定できているか確認する |
inputs | 入力データ | uri_folder、literalなどの型を確認する |
outputs | 出力データ | assetName、assetVersion、出力先URIを確認する |
environmentVariables | 環境変数 | 秘密情報を直接埋め込まない |
distribution | 分散学習設定 | PyTorch、MPI、TensorFlowの設定差を確認する |
resources | VM SKUやノード数など | instanceCount、instanceType、shmSizeを確認する |
limits | タイムアウトなど | 長時間ジョブの上限を明示する |
queueSettings | キュー設定 | 優先度や実行制御の設計に関係する |
userAssignedIdentityId | ユーザー割り当てマネージドID | ACR、データストア、出力先への権限を確認する |
gpuCount | GPU数 | 2026年5月5日の更新で注目すべき追加点 |
gpuCountは「ジョブに割り当てるGPU数」として定義されています。GPU数を指定できるようになると、学習ジョブの性能設計に使えますが、実際に使えるかどうかはコンピュートSKU、クォータ、リージョン、ワークスペース構成にも依存します。API仕様上の項目追加だけを見て、必ずGPUが確保できると判断しないことが大切です。(GitHub)
入力・出力モデルの変更点
入力と出力は、複雑なサブクラス階層ではなく、フラットなモデルとして定義されています。入力側はJSON上でjobInputType、出力側はjobOutputTypeを使い、型としてuri_file、uri_folder、safetensors_model、literalが定義されています。入力のpathはJSONではuriとして扱われ、リテラル入力ではvalueを使います。(GitHub)
入力・出力のモードはInputOutputModesとして統合され、ReadOnlyMount、ReadWriteMount、Download、Direct、Uploadが定義されています。出力側には、生成物を名前付きデータ資産として登録するためのassetNameやassetVersionもあります。(GitHub)
実務では、次のように使い分けます。
| 用途 | 推奨される考え方 |
|---|---|
| 大きな学習データを参照する | uri_folderとReadOnlyMountを検討する |
| 小さなパラメーターを渡す | literalとvalueを使う |
| 学習済みモデルを出力する | outputsにassetNameとassetVersionを指定する |
| モデル系出力を扱う | safetensors_modelやbaseModelIdの利用有無を確認する |
注意したいのは、入力・出力のmodeを何となく指定しないことです。マウント、ダウンロード、直接参照、アップロードは、ジョブ開始時間、I/O性能、コンテナー内のパス設計、成果物登録の流れに影響します。既存のAzure MLジョブ定義から移行する場合は、単に項目名を置き換えるのではなく、データの配置・参照方式まで確認してください。
削除とキャンセルは非同期処理として扱う
beginDeleteとbeginCancelは、単純な同期APIとして実装しない方が安全です。PRでは、削除は202 AcceptedとLocationヘッダーを返してポーリングできるほか、ジョブが存在しない場合は204を返す可能性があります。キャンセルは即時完了なら200、非同期なら202 AcceptedとLocationヘッダーを返す形です。(GitHub)
この仕様で失敗しやすいのは、202を「処理完了」と誤解することです。202はリクエストの受理を示すもので、実際の削除・キャンセル完了は返されたLocationを使って確認する必要があります。
| レスポンス | 意味 | 実装での扱い |
|---|---|---|
| 200 | キャンセルが同期的に完了 | 完了として扱う |
| 202 | 削除またはキャンセルが受理された | Locationでポーリングする |
| 204 | 削除対象が存在しない、またはボディなし | 冪等な削除として扱えるか設計する |
バッチ基盤やCI/CDからジョブを停止する場合は、beginCancelを呼んだ直後に次の処理へ進むのではなく、状態確認を入れるべきです。たとえば、キャンセル後に同名ジョブを再作成するワークフローでは、キャンセル完了前に再作成処理が走ると、名前衝突や状態不整合が起きる可能性があります。
SDK利用者への影響
PR説明では、生成されるPython SDKでclient.beta.training.jobsからアクセスできるとされています。一方で、レビューコメントではネストされたサブクライアント.beta.training.jobsの導入について確認が必要として、マージを保留するコメントもあります。(GitHub)
つまり、SDK利用者は次の点を分けて考える必要があります。
| 観点 | 対応 |
|---|---|
| REST API仕様 | PR差分で操作名、パラメーター、ヘッダーを確認する |
| Python SDK | 実際にリリースされたSDKのメソッド名を確認する |
| JavaScript SDK | APIViewで生成差分が出ているため、公開後の型定義を確認する |
| TypeSpec | モデル名・エンコード名・ディスクリミネーターの変更に注意する |
APIViewではTypeSpec、Python、JavaScriptのAPIレビューが作成されているため、SDK生成物にも影響が出る可能性があります。SDKで使う場合は、PR上の予定名だけで実装せず、正式なSDKリリースノートやAPIレビューの結果と照合してください。(GitHub)
対応すべき人・影響が小さい人
対応すべき人
このAzure REST API documentation updateを優先的に確認すべきなのは、次のようなチームです。
| 対象 | 理由 | まずやること |
|---|---|---|
| Azure AI Foundryでトレーニングジョブを自動実行しているチーム | CommandJob APIの設計に影響する | 既存のジョブ作成JSONと新モデルを比較する |
| REST APIでジョブを作成・停止する運用基盤チーム | ヘッダー、非同期処理、レスポンスコード対応が必要 | 200・202・204のハンドリングを見直す |
| SDKを生成・ラップしている開発チーム | TypeSpec変更がSDKメソッド名やモデル名に影響する | 生成後のPython/JavaScript APIを確認する |
| MLOps・CI/CD担当者 | キュー、GPU、出力資産、キャンセル処理に関係する | 検証環境でジョブ作成からキャンセルまで試す |
| セキュリティ・基盤管理者 | ACR/MCR、データストア、マネージドIDの権限が関係する | 実行IDの権限と出力先のアクセス制御を確認する |
影響が小さい人
一方で、次のようなケースでは直接の対応優先度は高くありません。
- Azure AI FoundryのTraining Jobsを使っていない
- Azure REST APIではなく、ポータル操作だけでジョブを管理している
- CommandJobではなく、別のサービス・別の管理プレーンAPIだけを使っている
- プレビュー機能を利用しない方針で運用している
ただし、将来的にAzure AI FoundryのカスタムトレーニングやMLOps自動化を進める予定があるなら、今の段階でAPI設計を把握しておく価値はあります。特に、ジョブ作成のパラメーター、出力資産登録、GPU指定、キャンセル処理は、後から設計を変えると運用影響が大きくなりやすい領域です。
移行・設定確認のチェックリスト
今回のPRを見てすぐに本番変更する必要はありませんが、将来の正式化に備えて次の観点を確認しておくと安全です。
| 確認項目 | OKの目安 | 見落とすと起きること |
|---|---|---|
| PRの状態 | Draft/Openか、マージ済みかを確認している | 未確定仕様で本番実装してしまう |
| プレビューヘッダー | Foundry-Features: Jobs=V1Previewを付与できる | APIが期待通り利用できない |
| APIバージョン | api-versionをリクエストで指定している | クライアント間で挙動が揺れる |
| 必須フィールド | command、environmentImageReference、computeIdを設定している | ジョブ作成に失敗する |
| 入力・出力 | jobInputType、jobOutputType、uri、valueを正しく使い分ける | データがマウントされない、出力が登録されない |
| タグ更新 | createOrUpdate時にタグ置換を理解している | 既存タグを誤って消す |
| 非同期処理 | 202時にLocationでポーリングする | 削除・キャンセル完了前に次処理が走る |
| GPU指定 | gpuCountとコンピュートSKU・クォータを照合する | ジョブがスケジュールできない |
| 読み取り専用項目 | services、status、systemDataを送信しない | 不要なフィールドでエラーになる可能性 |
| SDK名 | リリース後のSDKで実際のメソッド名を確認する | PR上の予定名と実装がずれる |
実装前に確認したい具体例
REST API呼び出しの設計例
REST APIでCommandJobを作成する処理を設計する場合、単にJSONを送るだけでは不十分です。最低でも、ヘッダー、APIバージョン、ジョブ名、リクエスト本文、レスポンスコードの扱いを1つのテストケースとしてまとめておく必要があります。
PUT /training/jobs/<job-name>?api-version=v1
Foundry-Features: Jobs=V1Preview
Content-Type: application/json{
"properties": {
"jobType": "Command",
"command": "python train.py --data ${{inputs.training_data}} --output ${{outputs.model}}",
"environmentImageReference": "mcr.microsoft.com/azureml/openmpi4.1.0-cuda11.8-cudnn8-ubuntu22.04:latest",
"computeId": "/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.MachineLearningServices/workspaces/<workspace>/computes/<compute-name>",
"inputs": {
"training_data": {
"jobInputType": "uri_folder",
"uri": "azureai://datastores/<datastore>/paths/data/train",
"mode": "ReadOnlyMount"
}
},
"outputs": {
"model": {
"jobOutputType": "uri_folder",
"mode": "ReadWriteMount",
"assetName": "trained-model",
"assetVersion": "1"
}
},
"gpuCount": 1
}
}この例で確認すべきポイントは、command内で${{inputs.training_data}}や${{outputs.model}}のような入出力参照を使うこと、inputsとoutputsの型名がJSON上ではjobInputTypeとjobOutputTypeになること、GPU数を指定する場合は実行先コンピュートと整合させることです。PRの最大構成例でも、入力、出力、分散設定、リソース、タイムアウト、ユーザー割り当てID、gpuCountなどが含まれています。(GitHub)
削除・キャンセル処理の実装例
削除やキャンセルの処理では、成功レスポンスの種類が複数あることを前提にします。たとえばキャンセルAPIでは、200なら即時完了、202ならポーリング待ちです。削除APIでは、202に加えて204も正常系として扱う必要があります。(GitHub)
擬似コードでは、次のような考え方になります。
ジョブキャンセルを実行
レスポンスが200:
キャンセル完了として扱う
レスポンスが202:
Locationヘッダーを取得
Retry-Afterがあれば待機
Locationをポーリングして完了確認
それ以外:
エラーとしてログ出力運用では、キャンセル要求を出しただけで「停止済み」と表示しないことが重要です。ジョブの状態確認まで含めて、UIや通知、CI/CDの後続ステップを設計してください。
失敗しやすいポイント
PRを正式仕様として扱ってしまう
このPRはDraftで、レビュー担当者による変更要求も残っています。さらに、Swagger PrettierCheckの失敗もコメントされています。つまり、現時点では「今後の仕様候補」として読むべきであり、正式な本番仕様として固定するのは危険です。(GitHub)
安全な進め方は、次の3段階です。
- PR差分をもとに影響範囲を洗い出す
- 検証環境でラッパーやJSONテンプレートを準備する
- 正式マージ後に差分を再確認して本番実装へ反映する
servicesやstatusをリクエストに入れてしまう
servicesやstatusは読み取り専用として定義されています。これらはサービス側が設定する情報であり、クライアントが作成リクエスト時に送る項目ではありません。(GitHub)
よくあるミスは、GETで取得したジョブJSONをそのままPUTの更新リクエストに流用することです。GETレスポンスにはid、type、systemData、statusなどの読み取り専用項目が含まれる可能性があります。更新時は、送信してよい項目だけを抽出する処理を入れてください。
タグを差分更新のつもりで送ってしまう
createOrUpdateの説明では、更新時に渡したタグが既存ジョブのタグを置き換えるとされています。つまり、{"env": "prod"}だけを送ると、既存のownerやexperimentNameなどのタグが消える可能性があります。(GitHub)
タグを維持したい場合は、更新前に既存ジョブを取得し、既存タグと追加・変更したいタグをマージしてから送る設計にしましょう。
GPU数だけを見てリソース設計してしまう
gpuCountは便利な項目ですが、GPU利用はAPI項目だけで完結しません。実際には、コンピュートSKU、ノード数、リージョン別クォータ、利用するDockerイメージ、分散学習設定、ドライバーやCUDAの整合性が関係します。PRの例でもGPU向けのAzure MLイメージとgpuCountが使われていますが、実環境では自社のコンピュート構成に合わせた検証が必要です。(GitHub)
いま取るべき行動
このAzure REST API documentation updateを見た開発・運用チームは、まず本番反映ではなく「準備」と「検証」に動くのが現実的です。
最初に、既存のトレーニングジョブ作成方法を棚卸ししてください。ポータル操作、SDK、REST API、CI/CD、社内ラッパーのどれでジョブを作っているかを整理します。次に、CommandJobの必須フィールド、入出力、コンピュート、GPU、非同期削除・キャンセルの扱いを、現在の実装と比較します。
最後に、正式マージやSDKリリース後に確認する項目をあらかじめリスト化します。特に、client.beta.training.jobsのようなSDKアクセスパス、Foundry-Featuresヘッダー、gpuCount、タグ置換、202レスポンス時のポーリングは、リリース後すぐに確認すべき項目です。
今回のPRはDraft段階ですが、Azure AI FoundryでトレーニングジョブをAPI化・自動化する方向性を示す重要な変更です。今のうちにジョブ定義、権限、GPUリソース、入出力資産、非同期処理の設計を見直しておくことで、正式仕様が固まったときにスムーズに移行できます。
コメント