2026年5月5日に公開・更新情報として確認したい「Azure REST API documentation update: Use a more descriptive input argument than “body” in emitted SDK.」は、REST APIのエンドポイントやリクエストJSONを変える更新ではありません。結論から言うと、影響を受けるのは主に、Azure REST APIの仕様から生成されたSDKを使い、対象のベータ操作をコードから呼び出している開発者です。
特に evaluation_taxonomies.create() や evaluation_taxonomies.update() で body= のような名前付き引数を使っている場合は、SDK更新後に引数名の変更でコード修正が必要になる可能性があります。一方、cURLやHTTPクライアントでREST APIを直接呼び出している場合、基本的にリクエスト本文の構造を変える必要はありません。GitHub PRでは、この変更はREST APIリファレンス文書やOpenAPI3ファイルには影響せず、生成されるSDKに関する変更だと説明されています。(GitHub)
Azure REST API documentation updateで何が変わったのか
今回の変更は、TypeSpecで定義されたリクエストボディのプロパティ名を、SDKに出力されたときに分かりやすい名前へ変えるものです。
これまで一部の操作では、SDKの入力引数名が単に body になっていました。body はHTTPリクエストの本文を表す一般的な言葉ですが、SDK利用者から見ると「何のbodyなのか」が分かりにくい名前です。今回のPRでは、body ではなく taxonomy や job のように、渡すオブジェクトの意味が分かる名前へ寄せています。PR #42860は2026年5月4日に feature/foundry-release ブランチへマージされ、変更ファイルはTypeSpecの .tsp ファイル2件、差分は3追加・3削除です。(GitHub)
重要なのは、これはHTTP APIの仕様変更ではなく、SDKの使い勝手とAPIサーフェスの変更だという点です。PR本文では、npx tsp compile . によってOpenAPI3ファイルは変わらないと明記されています。つまり、REST APIを直接呼ぶコードと、生成SDKを使うコードでは確認すべきポイントが異なります。(GitHub)
影響を受ける操作と対応優先度
PRで影響対象として挙げられているのは、以下のベータ操作です。evaluation_taxonomies.create() と evaluation_taxonomies.update() は既に出荷済みのため、SDK利用者にとって破壊的変更になる可能性があります。datasets.create_generation_job() は新しい操作のため、既存コードへの破壊的影響はないとされています。(GitHub)
| 対象操作 | 変更の概要 | 影響度 | 優先して確認すべき人 |
|---|---|---|---|
.evaluation_taxonomies.create() | SDK引数の body を、評価タクソノミーを表すより具体的な名前へ変更 | 高 | 既存のベータSDKで評価タクソノミーを作成している人 |
.evaluation_taxonomies.update() | SDK引数の body を、評価タクソノミーを表すより具体的な名前へ変更 | 高 | 既存のベータSDKで評価タクソノミーを更新している人 |
.datasets.create_generation_job() | ジョブ作成用の本文引数を job 方向の名前へ変更 | 低 | 新しい操作を取り込む予定のSDK利用者 |
差分を見ると、evaluation-taxonomies/routes.tsp では @body body: EvaluationTaxonomy; がより説明的な名称へ変更され、servicepatterns.tsp では @body body: TJob; が @body job: TJob; に変わっています。生成後のSDKで最終的にどの名前になるかは、言語ごとの命名規則や公開パッケージのバージョンで確認する必要があります。(GitHub)
REST API利用者とSDK利用者で影響が違う
この更新で最も混同しやすいのは、「REST APIのbodyが変わった」と受け取ってしまうことです。実際には、HTTPリクエストの本文そのものではなく、SDKメソッドに渡す引数名の話です。
| 利用形態 | 影響 | 確認ポイント |
|---|---|---|
| cURLやHTTPクライアントでREST APIを直接呼び出す | 原則として影響なし | URL、HTTPメソッド、JSON本文を不用意に変えない |
| OpenAPI3ファイルを参照している | 原則として影響なし | PRではOpenAPI3出力は変わらないと説明されている |
| Azure SDKを使って対象ベータ操作を呼ぶ | 影響あり | body= や body: の名前付き引数を使っていないか確認する |
| SDKラッパーや社内共通ライブラリを作っている | 影響あり | ラッパーの引数名、型ヒント、テスト、ドキュメントを更新する |
| TypeSpecでAzure API仕様を作成・保守している | 設計上の影響あり | @body body のような汎用名を避け、ドメイン名を使う |
TypeSpecの @body は、対象のプロパティやパラメーターがHTTPリクエストまたはレスポンスの本文であることを明示するデコレーターです。つまり @body は「HTTP上の役割」を示すものであり、プロパティ名まで body にする必要はありません。SDK利用者の視点では、body よりも taxonomy や job の方が何を渡すべきか判断しやすくなります。(Typespec)
既存コードで最初に確認すべき場所
まず、対象操作を使っているかを検索してください。リポジトリ全体で以下の文字列を探すと、影響箇所を見つけやすくなります。
evaluation_taxonomies.create
evaluation_taxonomies.update
create_generation_job
body=
body:Pythonでは、Microsoft Learnのサンプルにも evaluation_taxonomies.create(..., body=EvaluationTaxonomy(...)) のような呼び出し例が掲載されています。SDK側の引数名が変わった場合、このような名前付き引数はそのままでは動かなくなる可能性があります。(Microsoft Learn)
変更前の典型例は次のようなコードです。
taxonomy = project_client.beta.evaluation_taxonomies.create(
name=agent_name,
body=EvaluationTaxonomy(
description="Taxonomy for red teaming run",
taxonomy_input=AgentTaxonomyInput(
risk_categories=[RiskCategory.PROHIBITED_ACTIONS],
target=target,
),
),
)SDK更新後は、公開されているSDKリファレンスで実際の引数名を確認したうえで、次のようにリソースの意味に合う名前へ置き換えます。
taxonomy = project_client.beta.evaluation_taxonomies.create(
name=agent_name,
taxonomy=EvaluationTaxonomy(
description="Taxonomy for red teaming run",
taxonomy_input=AgentTaxonomyInput(
risk_categories=[RiskCategory.PROHIBITED_ACTIONS],
target=target,
),
),
)上記の taxonomy= は変更の考え方を示す例です。実際に使う名前は、導入している azure-ai-projects などのSDKバージョンに対応したAPIリファレンス、型定義、IDE補完で確認してください。特にベータAPIは正式リリース前にシグネチャが変わる可能性があるため、パッケージのバージョン固定とリリースノート確認をセットで行うのが安全です。
言語別に注意すべきポイント
SDKの引数名変更は、言語によって影響の出方が違います。単に「SDKが変わる」と見るのではなく、自分のコードが名前付き引数に依存しているかを確認することが重要です。
| 言語・利用パターン | 起きやすい影響 | 実務での確認方法 |
|---|---|---|
| Python | body= のキーワード引数が使えなくなる可能性 | 対象メソッドを呼ぶテストを実行し、型チェックやIDE補完で新しい引数名を確認する |
| C# | body: の名前付き引数を使っている場合に影響する可能性 | 名前付き引数で呼んでいる箇所を検索し、必要なら位置引数または新しい名前へ変更する |
| Java | 通常は位置引数で呼ぶため実行コードへの影響は限定的になりやすい | メソッドシグネチャ、生成ドキュメント、ラッパー層の引数名を確認する |
| TypeScript/JavaScript | オプションオブジェクトや生成形式によって影響が変わる | 生成SDKの型定義とコンパイル結果を確認する |
| 社内SDKラッパー | 外部公開している関数名やドキュメントが古くなる | ラッパーの引数名、README、サンプル、テストデータを同時に更新する |
Microsoft LearnのJava SDKリファレンスでは、現時点で createEvaluationTaxonomy(String name, EvaluationTaxonomy body) や updateEvaluationTaxonomy(String name, EvaluationTaxonomy body) のように body が引数名として表示されています。今後、対象の生成SDKが更新された場合は、このようなリファレンス上の引数名も変わる可能性があります。(Microsoft Learn)
.NETのリファレンスでも、CreateAsync(string name, EvaluationTaxonomy body, CancellationToken cancellationToken = default) のように body が使われています。C#では位置引数で呼んでいるコードは影響を受けにくい一方、body: の名前付き引数を使っている場合は注意が必要です。(Microsoft Learn)
移行時の実務チェックリスト
SDKを更新する前に、次の順番で確認すると手戻りを減らせます。
| 手順 | 作業 | 判断基準 |
| -: | ——————————- | —————————————————————————————— |
| 1 | 対象SDKのバージョンを確認する | azure-ai-projects など、Azure AI Foundry関連SDKを使っているか |
| 2 | 対象操作の利用有無を検索する | evaluation_taxonomies.create、evaluation_taxonomies.update、create_generation_job があるか |
| 3 | body の名前付き引数を検索する | Pythonの body=、C#の body:、ラッパー関数の body 引数を確認 |
| 4 | SDKリファレンスと型定義で新しい引数名を確認する | IDE補完、型チェック、公式APIリファレンスを優先する |
| 5 | サンプルコードとテストを更新する | README、手順書、CI用サンプルも忘れずに更新 |
| 6 | 単体テストと最小限の統合テストを実行する | HTTPステータスだけでなく、送信JSONが意図通りかも確認 |
| 7 | REST APIのJSON本文を不要に変更していないか確認する | OpenAPI3やREST直接呼び出しの差分が出ていないことを確認 |
特に重要なのは、SDKの引数名変更とJSONプロパティ名変更を混同しないことです。body というSDK引数を taxonomy に変えるとしても、HTTPで送るJSONの構造まで同じようにラップし直すとは限りません。リクエスト本文の形は、REST APIリファレンスまたはOpenAPI3で確認してください。
TypeSpecを保守している場合の確認ポイント
Azure REST API仕様をTypeSpecで管理しているチームは、今回の変更を単発の修正ではなく、命名ルールの見直しとして捉えるべきです。PR本文でも、TypeSpecガイドラインとしてプロパティ名に body を使わない方向へ更新することが推奨されています。(GitHub)
避けたい書き方は次のような定義です。
@doc("The evaluation taxonomy.")
@body
body: EvaluationTaxonomy;より望ましいのは、SDK利用者が何を渡すのかを理解できる名前です。
@doc("The evaluation taxonomy.")
@body
taxonomy: EvaluationTaxonomy;ジョブを作成する操作なら、次のように job のような業務上の意味を持つ名前にします。
/** The job to create. */
@body
job: TJob;この考え方にすると、生成SDKのメソッドシグネチャを見たときに、利用者が「ここには評価タクソノミーを渡す」「ここには生成ジョブを渡す」とすぐ判断できます。HTTPの都合である body をSDK利用者に見せ続けるより、ドメインオブジェクト名を前面に出す方が、サンプルコードやIDE補完でも迷いにくくなります。
よくある誤解と注意点
| 誤解 | 正しい見方 |
|---|---|
| REST APIのリクエスト本文が変わる | 今回の主眼は生成SDKの引数名。PRではREST APIリファレンス文書やOpenAPI3ファイルには影響しないと説明されている |
body というJSONプロパティを taxonomy に変える必要がある | SDK引数名とJSON本文の構造は別物。REST本文はAPIリファレンスで確認する |
| すべてのAzure REST APIが影響を受ける | PRで挙げられている対象は特定のベータ操作 |
| ベータ操作なので確認しなくてよい | ベータでも既に組み込んでいる場合、SDK更新でビルドや実行が止まる可能性がある |
| 位置引数なら必ず安全 | 言語やSDK生成方式による。テストと型チェックで確認する |
| OpenAPI3を再生成すれば差分が出る | PRでは npx tsp compile . でOpenAPI3ファイルは変わらないとされている |
PRのチェックでは、APIViewがAPIレベルの変更を検出し、Azure.AI.ProjectsのTypeSpecに対するAPIレビューが作成されています。これは、HTTP APIの変更というより、SDKとして公開されるAPI面に差分が出ることを示すシグナルとして見るのが適切です。(GitHub)
対応すべき人と次のアクション
今回のAzure REST API documentation updateで最優先に対応すべきなのは、Azure AI FoundryやAzure.AI.Projects系のSDKで、対象ベータ操作をすでに使っている開発者です。特に body= を明示しているPythonコード、body: を使っているC#コード、社内ラッパーで body という引数名を公開しているコードは、SDK更新前に洗い出してください。
REST APIを直接呼び出している場合は、慌ててJSON本文を変える必要はありません。まずは利用形態を切り分け、SDK利用箇所だけを対象に確認するのが効率的です。
最後に、TypeSpecを保守する側は、@body body のような汎用名を避け、taxonomy、job、request、configuration など、渡すデータの意味が分かる名前を使う方針にそろえるとよいでしょう。今回の変更は小さな命名修正に見えますが、生成SDKの可読性、サンプルコードの分かりやすさ、移行時のミス防止に直結します。
コメント