Azure REST API documentation update: Add Foundry jobs and MLflow surfaces は、Azure AI Foundryまわりの学習ジョブ管理とMLflow互換APIを、REST API仕様として扱いやすくするための更新です。最初に確認すべきポイントは、学習ジョブ作成、ジョブ試行、成果物、メトリクス、出力、MLflow tracking／registry系APIが仕様面で追加・整理されていることです。
特に注意したいのは、初期サマリーでは /jobs ルートが示されていますが、後続の差分では公開パスやTypeSpecフォルダーが training_jobs に揃えられている点です。既存コードやSDK生成設定で /jobs を前提にしている場合は、最新のOpenAPI／TypeSpecを確認してから対応してください。PR上ではFoundry jobsのTypeSpec、ルート、例、生成OpenAPIスナップショット、MLflow互換ルート群の追加が説明されています。(GitHub)
Azure REST API documentation updateの要点
今回のAzure REST API documentation updateは、単にエンドポイントが増えるだけの変更ではありません。Azure AI Foundryのモデル学習ジョブをREST APIで作成し、その後のライフサイクル、試行履歴、成果物、メトリクス、出力まで追跡しやすくする変更です。
加えて、MLflow互換のルートグループが /mlflow/api/2.0/mlflow 配下に追加され、experiments、runs、metrics、artifacts、registered models、model versions といったMLOpsでよく使う操作をFoundry側のAPI仕様に載せる方向になっています。(GitHub)
| 確認項目 | 変更内容 | 実務で見るべきポイント |
|---|---|---|
| Foundry jobs | 学習ジョブ用のTypeSpec、ルート、例、OpenAPI出力を追加 | REST直打ち、SDK生成、CIのOpenAPI差分チェックに影響 |
| ジョブ作成 | 学習ジョブをPOSTで作成し、Operation-Idで冪等性を扱う | リトライ時に同じジョブが重複作成されない設計が必要 |
| ジョブ子リソース | attempts、artifacts、metrics、outputsを扱うルートを追加 | 実行後の監視、成果物取得、評価メトリクス確認に影響 |
| LRO | cancel／deleteなどで非同期ポーリング用のヘッダーや操作ルートを扱う | 完了前に後続処理を進めないようポーリング実装を確認 |
| MLflow互換surface | tracking／registry系のルートを追加 | 既存のMLflowクライアント、MLOpsパイプライン連携を検証 |
| SDK投影 | beta client側の操作名やグルーピングに影響する可能性 | 生成SDKのメソッド名、namespace、operation groupを確認 |
変更点：Foundry jobsで学習ジョブの作成から確認まで扱える
Foundry jobsの追加で重要なのは、ジョブ作成だけでなく、ジョブの状態確認、キャンセル、削除、試行履歴、成果物、メトリクス、出力までREST API仕様に含まれることです。
最新のTypeSpecでは、学習ジョブの一覧取得に GET /training_jobs、作成に POST /training_jobs が定義されています。作成時には Operation-Id ヘッダーを指定でき、これは同じ作成要求を安全にリトライするための冪等性キーとして説明されています。(GitHub)
学習ジョブ作成で見るべき項目
学習ジョブ作成時のリクエストでは、少なくとも次の観点を確認します。
| 項目 | 確認内容 | 失敗しやすい例 |
|---|---|---|
name | ジョブ名。大文字小文字を区別する前提で扱う | 環境ごとに命名規則が揃っておらず、再実行時に衝突する |
job_type | 現時点ではcommand jobが中心 | 既存の別種ジョブと同じ扱いにしてスキーマ不整合が起きる |
compute_id | 利用するcompute resource ID | 開発環境と本番環境で参照先を固定値にしてしまう |
training | 宣言的な学習レシピ | training指定時に不要なcommandを同時に送る |
command | trainingを使わない場合の起動コマンド | レシピ型ジョブとコマンド型ジョブを混在させる |
Operation-Id | リトライ用の冪等性キー | リトライごとに新しいIDを発行して重複ジョブが作られる |
TypeSpec上のモデルでは、JobCreateが name と properties を持ち、command jobでは compute_id、inputs、outputs、environment_variables、resources、gpu_count、distribution などの構成項目が示されています。trainingを指定する場合は、サービス側がレシピを実行用コマンドや環境へ変換する前提の説明も含まれています。(GitHub)
ルートは/jobsではなく/training_jobsを必ず確認する
この更新で最も見落としやすいのはルート名です。
PRの初期サマリーでは /jobs や POST /jobs が説明されていますが、後続コミットではwire pathとresource segmentを training_jobs に更新したこと、さらにreview feedbackを受けてTypeSpecフォルダーやpreview flagも training_jobs に揃えたことが記録されています。最新のTypeSpecルートでも POST /training_jobs が使われています。(GitHub)
既存実装を見直すときは、次のように確認すると安全です。
# 既存コードに古いルート前提が残っていないか確認
grep -R '"/jobs\|/jobs' ./src ./tests ./infra
# 新しいルート前提のテストがあるか確認
grep -R 'training_jobs' ./src ./tests単純な文字列置換だけで済ませるのは危険です。ジョブ作成、ポーリング、attempts、artifacts、metrics、outputsの各ルートがどのように組み立てられているかを、生成OpenAPIまたは最新TypeSpecで照合してください。
ジョブのライフサイクル操作で変わること
Foundry jobsでは、作成後の操作も重要です。キャンセルや削除は即時完了とは限らず、非同期処理として扱われる場合があります。
TypeSpecでは、削除は 202 Accepted と Location／Operation-Location ヘッダーで完了確認するケース、またはジョブが存在しない場合に 204 を返すケースが説明されています。キャンセルも即時に 200 で終わる場合と、202 Acceptedでポーリングが必要になる場合があります。(GitHub)
| 操作 | 確認すべき実装 | 注意点 |
|---|---|---|
| 作成 | Operation-Idを発行し、業務IDと紐づけて保存 | 同じ論理ジョブの再送では同じOperation-Idを使う |
| キャンセル | 200と202の両方を処理 | 202の場合は完了前提でUIや後続処理を進めない |
| 削除 | 202と204を処理 | 存在しないジョブをエラー扱いにするか業務要件で判断 |
| ポーリング | operation result／statusルートを確認 | LocationとOperation-Locationの役割を混同しない |
| 監視 | job_name、operation_id、attempt_idをログに残す | 障害時にどの試行の問題か追跡できなくなる |
APIクライアント側では、HTTPステータスコードだけで完了判断しない設計が必要です。特にMLOpsパイプラインでは、ジョブ作成後すぐに成果物ダウンロードやメトリクス取得へ進むと、まだ対象データが存在しない可能性があります。
attempts、artifacts、metrics、outputsの追加で確認できる範囲が広がる
学習ジョブでは、1つのジョブに対して複数の試行が発生することがあります。今回の更新では、attempts配下で試行単位の情報を取得し、さらに成果物、メトリクス、出力を確認するルートが追加されています。
最新TypeSpecでは、/training_jobs/{job_name}/attempts、/training_jobs/{job_name}/attempts/{attempt_id}/artifacts、metrics、outputsなどのルートが定義されています。また、attempt_idには特定の試行IDだけでなく、最新試行を示す latest も使える形になっています。(GitHub)
latestだけに頼ると原因調査が難しくなる
開発初期は latest を使うと便利です。しかし、本番運用では試行IDを明示してログに残す設計が重要です。
たとえば、同じ学習ジョブを3回再試行した場合、latestで取得したメトリクスだけを見ると、1回目と2回目で発生した精度低下やデータ欠損の痕跡を見落とすことがあります。CI/CDやMLOps基盤では、少なくとも次の値を保存しておくとトラブルシューティングが楽になります。
| 保存する値 | 目的 |
|---|---|
job_name | 対象ジョブを特定する |
operation_id | 作成・削除・キャンセルなどの非同期操作を追跡する |
attempt_id | どの試行で発生した事象かを切り分ける |
metric_name | 精度、loss、評価指標などを追跡する |
| artifact path | ダウンロード対象や成果物の場所を再現する |
| output name | モデル、データセット、評価結果などの出力を追跡する |
MLflow surfaces追加の意味
MLflow surfacesの追加は、既存のMLflowベースの運用をAzure AI Foundry側のAPI仕様と接続しやすくする変更です。
MLflow REST APIは、experimentsやrunsの作成・取得、parameters、metrics、artifactsの記録などを扱うAPIです。公式MLflowドキュメントでも、APIは /api/2.0/mlflow/... 配下のルートで使われることが説明されています。(MLflow AI Platform)
今回のTypeSpecでは、Foundry側に /mlflow/api/2.0/mlflow/experiments、runs、metrics/get-history、artifacts/list、registered-models、model-versions といったMLflow互換ルートが追加されています。runsでは log-batch、log-metric、log-parameter、set-tag、log-modelなども定義されています。(GitHub)
MLflow互換だからといって無確認で移行しない
MLflow互換ルートがあると、既存のMLflowクライアントやMLOpsツールをそのまま使えるように見えます。ただし、実務では次の点を必ず検証してください。
| 検証項目 | 理由 |
|---|---|
| 認証方式 | ローカルMLflow serverとは認証・認可の前提が異なる |
| tracking URI | クライアントが期待する /api/2.0/mlflow との対応を確認する |
| artifact URI | 成果物の保存先、ダウンロードURI、権限が環境ごとに異なる可能性がある |
| registry操作 | PATCH、DELETE、POSTがプロキシやWAFで許可されているか確認する |
| エラー形式 | MLflowクライアントが期待するエラー応答と一致するか確認する |
| request body | JSON payloadの形が利用ツールの送信内容と合うか確認する |
Azure Machine LearningでもMLflowは実験追跡やモデル管理で使われており、Microsoft LearnではMLflowを使ったモデル管理や追跡に関する説明が提供されています。ただし、MLprojectファイルのサポート終了予定など、MLflow周辺の推奨構成は時期によって変わるため、利用中のドキュメントバージョンを確認して判断する必要があります。(Microsoft Learn)
影響を受けるチーム
今回のAzure REST API documentation updateは、Azure AI Foundryを直接操作する開発者だけでなく、SDK生成、MLOps、監視、APIゲートウェイ運用にも影響します。
| 対象 | 影響 | すぐ確認すること |
|---|---|---|
| REST APIを直接呼ぶ開発者 | ルート、ヘッダー、リクエストbody、ポーリング処理が変わる | /jobs前提が残っていないか、Operation-Idを保存しているか |
| SDK利用者 | beta client、operation group、メソッド名が変わる可能性 | SDKの生成元OpenAPI、メソッド名、戻り値型を確認 |
| SDK生成・保守担当 | TypeSpec／OpenAPI差分がクライアントAPIに影響 | APIViewやBreakingChangeチェックの結果を確認 |
| MLOps担当 | MLflow tracking／registry連携の経路が増える | experiments、runs、metrics、artifactsの最小フローを試す |
| SRE／運用担当 | 非同期操作、試行履歴、成果物取得の監視が必要 | operation ID、attempt ID、メトリクス取得のログ設計を見直す |
| API gateway担当 | 新しいパスとHTTPメソッドを許可する必要 | /training_jobsと/mlflow/api/2.0/mlflow/*の許可設定を確認 |
| セキュリティ担当 | 成果物ダウンロードやregistry操作の権限管理が必要 | RBAC、監査ログ、トークン取り扱いを確認 |
PR上ではAPIViewがAPIレベルの変更を検出し、TypeSpecのAPI reviewが作成されたことも記録されています。SDKや公開APIの互換性を気にするチームは、この種のレビュー結果を必ず確認すべきです。(GitHub)
移行・設定確認のチェックリスト
既存システムへ取り込む場合は、次の順序で確認すると手戻りを減らせます。
仕様確認
| チェック | 判断基準 |
|---|---|
| 最新のTypeSpec／OpenAPIを参照しているか | PR初期サマリーではなく、最新の生成物を基準にする |
ルートが/training_jobsになっているか | 古い/jobs前提のコードが残っていない |
api-versionの扱いを確認したか | 利用中のプレビュー／安定版の範囲を明確にする |
| 生成SDKのoperation groupを確認したか | models側の便利メソッド、trainingJobs側の低レベル操作を混同しない |
| OpenAPI差分をCIで検出しているか | 意図しないpath、schema、response変更を見逃さない |
実装確認
| チェック | 判断基準 |
|---|---|
Operation-Idを保存しているか | リトライ時に同じ論理要求として扱える |
| POST再送時に新しいIDを作っていないか | 重複ジョブを避けられる |
202 Accepted後にポーリングしているか | 非同期完了前に成果物取得へ進まない |
latestと明示的なattempt_idを使い分けているか | 障害解析時に試行単位で追跡できる |
| artifact downloadの権限を確認したか | 成果物URLやバイト列の取り扱いで漏えいを防げる |
| metrics取得の粒度を決めているか | last values、history、aggregates、samplesを目的別に使える |
MLflow確認
| チェック | 判断基準 |
|---|---|
| experimentsのcreate／searchが通るか | trackingの基本操作が動く |
| runsのcreate／log-batch／searchが通るか | 学習実行の記録ができる |
| metricsのget-historyが通るか | 時系列メトリクスを確認できる |
| artifactsのlistが通るか | 成果物の参照ができる |
| registered-modelsのcreate／get／searchが通るか | model registry運用に使える |
| model-versionsのcreate／transition／get-download-uriが通るか | バージョン管理と配布の流れを確認できる |
実装例：学習ジョブ作成時のリトライ設計
次は、Operation-Idを使って学習ジョブ作成を安全にリトライするための考え方を示す例です。実際のendpoint、api-version、body schemaは利用中の最新OpenAPIに合わせて調整してください。
OPERATION_ID="$(uuidgen)"
curl -X POST "https://{foundry-endpoint}/training_jobs?api-version={api-version}" \
-H "Authorization: Bearer ${AZURE_ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-H "Operation-Id: ${OPERATION_ID}" \
-d '{
"name": "sft-sample-20260505",
"properties": {
"job_type": "command",
"compute_id": "{compute-resource-id}",
"training": {
"algorithm": "sft",
"model": "{base-model-reference}",
"dataset": {
"train": "{training-dataset-reference}"
}
},
"gpu_count": 1,
"tags": {
"purpose": "validation"
}
}
}'この例で重要なのは、OPERATION_IDをHTTP送信の直前に使い捨てで作るのではなく、業務側のジョブレコードと一緒に保存することです。ネットワークエラーやタイムアウトで再送する場合、同じ論理ジョブには同じ Operation-Id を使います。
逆に、新しい学習条件、新しいデータセット、新しいモデルで別ジョブとして実行する場合は、新しい Operation-Id を発行します。ここを混同すると、「再送したつもりが別ジョブを作った」「新規実行のつもりが前回要求として扱われた」といった事故につながります。
APIゲートウェイやプロキシで確認すべき設定
REST API本体の実装だけでなく、API gateway、WAF、社内プロキシ、監査ログ基盤も確認が必要です。MLflow互換surfaceでは、一般的なREST操作よりも多様なHTTPメソッドとパスが使われます。
| 設定箇所 | 確認内容 |
|---|---|
| パス許可 | /training_jobs*、/mlflow/api/2.0/mlflow/*がブロックされないか |
| HTTPメソッド | GET、POST、PATCH、DELETEが必要な範囲で許可されているか |
| ヘッダー | Operation-Id、Location、Operation-Locationを削除していないか |
| bodyサイズ | MLflowのbatch logやartifact関連操作で制限にかからないか |
| タイムアウト | ジョブ作成後の同期待ちではなく、ポーリング前提になっているか |
| ログマスク | 認証トークン、artifact URL、モデル名、データセットIDを適切に保護しているか |
特に PATCH と DELETE は、セキュリティ設定で禁止されている環境があります。registered modelsやmodel versionsの操作を使う場合は、事前に疎通テストを行ってください。
SDK利用者が確認すべきポイント
SDKだけを使っている場合でも、今回の更新を無視してよいわけではありません。TypeSpecやOpenAPIの変更は、生成SDKのメソッド名、引数、戻り値、operation groupに影響する可能性があります。
PRのサマリーでは、学習ジョブ作成の便利操作をbetaのmodels client側に create_training_job／createTrainingJob として移す意図が説明されています。一方で、ジョブのライフサイクル操作や子リソースはbeta jobs側に置く方針も示されています。(GitHub)
SDKを使う場合は、次の3点を確認してください。
| 確認項目 | 具体的な見方 |
|---|---|
| メソッド名 | create_training_job、createTrainingJob、trainingJobs.createなど、言語ごとの命名を確認 |
| 戻り値 | 作成直後にジョブ本体が返るのか、operation resultをポーリングするのか確認 |
| 例外処理 | cancel／deleteの200、202、204をSDKがどう表現するか確認 |
「SDKを更新したらコンパイルが通った」だけでは不十分です。ジョブ作成、キャンセル、メトリクス取得、artifact取得までの最小E2Eテストを用意してください。
検証時に使える最小テストシナリオ
本番導入前には、次の順番で検証すると問題を切り分けやすくなります。
| 順番 | テスト | 成功条件 |
|---|---|---|
| 1 | GET /training_jobs | 一覧取得ができる、認証とapi-versionが正しい |
| 2 | POST /training_jobs | Operation-Id付きでジョブを作成できる |
| 3 | 同じOperation-Idで再送 | 重複作成されず、期待どおりの冪等動作になる |
| 4 | operation status/resultの確認 | 非同期操作の完了を追跡できる |
| 5 | attempts一覧取得 | 実行試行を取得できる |
| 6 | metrics取得 | 最新値、履歴、集計、サンプルの少なくとも1つを取得できる |
| 7 | artifacts一覧・content info取得 | 成果物の存在とダウンロード情報を確認できる |
| 8 | outputs取得 | 学習結果や出力参照を確認できる |
| 9 | MLflow experiment作成・検索 | MLflow tracking互換の基本動作を確認できる |
| 10 | MLflow run作成・metric記録 | 既存MLOpsツールとの接続可能性を確認できる |
PRでは、git diff --check、TypeSpecのOpenAPI3出力コンパイル、client.tspのコンパイルが検証項目として示されており、既存警告を除いて通過したことが記録されています。自社側で仕様を取り込む場合も、生成物の確認、差分レビュー、E2Eテストをセットで行うのが安全です。(GitHub)
失敗しやすいポイント
| 失敗パターン | 起きる問題 | 対策 |
|---|---|---|
PRサマリーの/jobsだけを見て実装する | 最新仕様とルートがずれる | 最新OpenAPI／TypeSpecで/training_jobsを確認 |
リトライ時にOperation-Idを再生成する | 重複ジョブが作られる可能性がある | 同じ論理要求には同じIDを使う |
202 Acceptedを完了扱いする | 成果物やメトリクスがまだ取得できない | operation status/resultをポーリングする |
latest attemptだけで監視する | 過去試行の問題を追跡できない | attempt_idをログに保存する |
| MLflow互換を完全互換と決めつける | クライアントやツールの期待と差が出る | experiments、runs、metrics、registryを個別に疎通確認 |
proxyでPATCHやDELETEが落ちる | model registry操作が失敗する | MLflow registry系メソッドを事前に許可 |
| SDK生成後のメソッド名を確認しない | 既存コードの呼び出しが壊れる | language別の生成結果とAPIViewを確認 |
| artifact URLやトークンをログ出力する | 機密情報漏えいにつながる | ログマスクと監査設定を見直す |
まず対応すべきこと
今回のAzure REST API documentation updateを見たら、最初に行うべきことは5つです。
まず、最新のTypeSpecまたは生成OpenAPIでルートを確認します。特に /jobs ではなく /training_jobs になっているかを見ます。次に、POST /training_jobs の作成処理で Operation-Id を保存し、リトライ時に再利用できるようにします。
その後、cancel／delete／create後の非同期ポーリング、attempts単位のmetrics／artifacts／outputs取得、MLflow互換ルートの最小疎通テストを実施します。SDKを使っている場合は、生成SDKのメソッド名と戻り値、beta clientのグルーピングも確認してください。
この更新は、Azure AI Foundryの学習ジョブをMLOps基盤に組み込みやすくする一方で、ルート名、冪等性、非同期処理、MLflow互換性の確認を怠ると、運用時の重複実行や追跡不能な失敗につながります。まずは開発環境で、ジョブ作成からメトリクス取得、artifact確認、MLflow run記録までの一連の流れを1本のテストとして固めることが、最も実用的な対応です。
コメント