Azure REST APIの「Azure REST API documentation update: Applyt renaming for the GA 2.1.0」は、RESTエンドポイントそのものを大きく変える更新というより、Azure AI Foundry / Azure.AI.Projects関連のTypeSpec定義とSDK生成時の名前をGA 2.1.0向けに整理する変更として確認するのが実務的です。特に影響を受けやすいのは、Azure REST APIを直接HTTPで呼ぶ利用者よりも、生成SDK、TypeSpec、Azure AI Projects系のクライアントライブラリ、サンプルコードを管理している開発チームです。
2026年5月5日時点で更新が入ったPRでは、specification/ai-foundry/data-plane/Foundry 配下の .tsp ファイルが変更され、C#向け設定とOpenAI拡張、Projects Agents関連のクライアント名が追加・整理されています。PR自体はAzure REST API仕様の標準リポジトリである azure-rest-api-specs 上の変更で、このリポジトリはMicrosoft AzureのREST API仕様の主要な管理元と説明されています。(GitHub)
Azure REST API documentation update: Applyt renaming for the GA 2.1.0で確認すべき結論
今回の変更で最初に確認すべきポイントは、次の3つです。
| 確認ポイント | 実務上の意味 | 優先度 |
|---|---|---|
REST APIのURL・HTTPメソッド・api-versionが変わるのか | 既存のHTTPリクエストや自動化スクリプトが壊れるかを判断する | 高 |
| SDK上のクラス名・プロパティ名・列挙名が変わるのか | アプリケーションコード、サンプル、型参照、テストの修正が必要になる | 高 |
| 変更が正式リリース済みか、PR段階か | すぐ移行するか、リリース確定後に対応するかを判断する | 高 |
今回のPR差分を見る限り、中心は @@clientName や @@access によるSDK生成名・公開範囲の調整です。TypeSpec Azureのドキュメントでは、@clientName はクライアントSDK要素の生成名を上書きするためのデコレーターで、クライアント、メソッド、パラメーター、モデル、列挙、モデルプロパティなどに影響します。(Azure)
一方で、Azure REST APIの一般的な呼び出しでは、要求URI、HTTPメソッド、ヘッダー、要求本文、応答本文といった要素を組み合わせます。Azure REST APIでは多くの場合 api-version が重要なクエリパラメーターになりますが、今回のPR差分からは、RESTの要求URIやHTTPメソッド自体が変更されたとは読み取れません。(Microsoft Learn)
今回の更新はAzure REST API全体ではなくAzure AI Foundry系の仕様変更として見る
「Azure REST API documentation update」と聞くと、Azure REST API全体の仕様変更に見えます。しかし、対象ファイルを見ると、変更は主に以下のパスに集中しています。
| 変更ファイル | 対象領域 | 読み取れる影響 |
|---|---|---|
specification/ai-foundry/data-plane/Foundry/client.csharp.tsp | Azure.AI.ProjectsのC#向けSDK生成設定 | C# SDKの公開名・公開範囲の調整 |
specification/ai-foundry/data-plane/Foundry/src/sdk-extensions-openai/client.tsp | OpenAI拡張・ツール関連の生成設定 | ツール、関数呼び出し、MCP、OpenAPI Toolなどの名前整理 |
specification/ai-foundry/data-plane/Foundry/src/sdk-projects-agents/client.tsp | Projects Agents関連の生成設定 | Agent endpointやTelemetry関連の名前整理 |
PRには data-plane と TypeSpec のラベルが付いており、差分は3つの .tsp ファイル、合計で46行追加・1行削除です。つまり、管理プレーン全体のARM API変更ではなく、Azure AI Foundryのデータプレーン仕様、特にSDK生成時の名前付けに関する更新として扱うのが適切です。(GitHub)
変更点の中心は「SDKで見える名前」の整理
今回の更新で目立つのは、REST APIのワイヤー形式よりも、生成SDKで開発者が目にする名前の変更です。たとえば、OpenAI拡張関連では、DetailEnum を ImageDetailLevel、defer_loading を ShouldDeferLoading、read_only を IsReadOnly のように、用途が分かりやすい名前へ寄せる指定が追加されています。(GitHub)
C#向けの主な変更
C#向け設定では、評価・データ生成・Evaluator生成ジョブ周辺の名前と公開範囲が調整されています。
| 変更内容 | 影響しやすいコード |
|---|---|
Target を EvaluationTarget として扱う指定 | 評価対象モデルや型名を直接参照しているC#コード |
EvalResult.passed を IsPassed として扱う指定 | 評価結果の成功可否を参照するコード |
DataGenerationJobType を DataGenerationJobKind として扱う指定 | データ生成ジョブ種別を参照するコード |
DataGenerationJobs / EvaluatorGenerationJobs の一部操作を internal にする指定 | 生成SDKの低レベル操作を直接呼んでいるコード |
特に注意したいのは、@@access(..., Access.internal) の追加です。TypeSpec Azureのドキュメントでは、@access は操作、モデル、列挙、モデルプロパティなどのアクセス情報を上書きするデコレーターで、Access.public または Access.internal を指定します。これにより、生成SDKで公開されるAPI表面が変わる可能性があります。(Azure)
OpenAI拡張・ツール関連の主な変更
OpenAI拡張側では、ツールや関数呼び出しに関する名前がより説明的な名称へ整理されています。
| 変更前または元の要素 | 変更後の生成名 | 確認すべき箇所 |
|---|---|---|
CreatedBy | AgentItemSource | Agentや項目の作成元を扱う処理 |
OpenAI.DetailEnum | ImageDetailLevel | 画像詳細度の指定 |
ComputerScreenshotImage.image_url | ImageUri | 画像URLを扱うプロパティ |
AutoCodeInterpreterToolParam.type | Kind | コードインタープリターツールの種類 |
AzureAISearchTool.azure_ai_search | AzureAISearch | Azure AI Search連携 |
AzureFunctionBinding.type | Kind | Azure Functions連携 |
BingGroundingSearchConfiguration.set_lang | Language | Bing grounding検索の言語設定 |
CustomToolParam.defer_loading | ShouldDeferLoading | カスタムツールの遅延読み込み |
FunctionToolParam.strict | IsStrict | 関数ツールの厳格モード |
MCPToolFilter.read_only | IsReadOnly | MCPツールの読み取り専用判定 |
OpenApiFunctionDefinition.spec | Specification | OpenAPI関数定義 |
OpenApiTool.openapi | OpenApi | OpenAPI Tool設定 |
StructuredOutputDefinition.strict | IsStrict | 構造化出力の厳格モード |
WebSearchApproximateLocation.type | Kind | Web検索のおおよその位置情報 |
この種の変更は、REST APIのJSONフィールド名を直接変えるとは限りません。しかし、SDKで型安全に利用している場合は、コンパイルエラーや補完候補の変化として表面化します。
Projects Agents関連の主な変更
Projects Agents側では、Agent endpointとTelemetry関連の名前が整理されています。
| 変更前または元の要素 | 変更後の生成名 | 想定される影響 |
|---|---|---|
AgentEndpointConfig | AgentEndpointConfiguration | Agent endpoint設定型の参照 |
TelemetryEndpointAuth | TelemetryEndpointAuthentication | Telemetry認証設定 |
TelemetryEndpoint.auth | Authentication | 認証プロパティ名 |
TelemetryEndpoint.data | ExportedDataTypes | エクスポート対象データ種別 |
TelemetryEndpointAuthType | TelemetryEndpointAuthenticationKind | 認証方式の列挙名 |
TelemetryDataKind | ExportedDataTypes | Telemetryデータ種別 |
既存コードでこれらの型名・プロパティ名を直接参照している場合、SDK更新時にビルドエラーが出る可能性があります。逆に、Azure Portalだけを利用している運用担当者や、HTTPリクエストを最小限のJSONで送っているだけの利用者は、影響が限定的な可能性があります。
影響を受ける可能性が高いチーム
今回のAzure REST API documentation updateで確認を急ぐべきなのは、次のようなチームです。
| 対象者 | 影響の出方 | 対応方針 |
|---|---|---|
| Azure AI Projects / Foundry系SDKを使う開発者 | 型名・プロパティ名の変更でビルドエラーが出る | SDK更新前後の差分を確認する |
| C# SDK利用者 | client.csharp.tsp の変更が直接影響しやすい | C#コード内の旧名称検索を行う |
| Pythonなど他言語SDKの利用者 | 共有 client.tsp のリネームが波及する可能性がある | APIViewや生成結果を確認する |
| TypeSpecからSDKを生成しているチーム | 生成物の名前が変わる | 生成コードのスナップショット比較を行う |
| 社内ドキュメント・サンプル管理者 | サンプルコードのプロパティ名が古くなる | ドキュメントとSDKバージョンをそろえる |
| REST APIを直接呼ぶ自動化チーム | 影響は限定的と見られるが、APIバージョンは要確認 | HTTPリクエストの回帰テストを実行する |
PRコメントでは、APIViewがTypeSpecとPythonパッケージに対してAPIレベルの変更を検出したことが示されています。これは、少なくとも生成されるAPI表面に差分があることを示す重要なサインです。(GitHub)
すぐに移行すべきか、様子を見るべきか
現時点で重要なのは、この変更を「正式リリース済みの確定仕様」として扱いすぎないことです。PRは Open 状態で、feature/foundry-release ブランチへのマージを目的としたものとして表示されています。また、PR上では SDK Validation Status のチェック失敗も示されており、現時点では非ブロッキングながら対応が推奨されています。(GitHub)
そのため、実務では次のように判断すると安全です。
| 状況 | 推奨対応 |
|---|---|
| 本番環境で現行SDKを利用中 | すぐ置き換えず、正式リリース・SDK更新後に検証環境で確認 |
| GA 2.1.0向けの新規実装を準備中 | 新名称を前提にサンプル・設計書を作る |
| TypeSpecや生成SDKを自社CIで追従している | 該当PRまたはマージ後コミットで生成差分を確認 |
| SDK更新でビルドエラーが出た | まずリネーム由来か、公開範囲変更由来かを切り分ける |
| REST APIをcurlやHTTPクライアントで直接利用 | エンドポイント、HTTPメソッド、api-version、JSONフィールドの差分を個別確認 |
ポイントは、「REST API利用者全員が即修正」ではなく、SDKの型名・プロパティ名を直接使っている箇所から優先的に点検することです。
移行前に確認するチェックリスト
SDKや仕様を更新する前に、次の順で確認すると手戻りを減らせます。
利用形態を切り分ける
まず、自社システムがAzure REST APIをどの方法で利用しているかを分けてください。
| 利用形態 | 今回の影響 |
|---|---|
| HTTPリクエストを直接送る | 影響は比較的小さい可能性が高い |
| Azure SDKを使う | 生成名変更の影響を受けやすい |
| TypeSpecからSDKを生成する | 生成物の差分確認が必須 |
| サンプルコードを社内配布している | 名前変更によりサンプルが古くなる可能性 |
| CIでAPI仕様リポジトリを追跡している | PRマージ前後の差分管理が必要 |
コード内の旧名称を検索する
SDK更新前に、影響しそうな名称をリポジトリ全体で検索します。
rg "ResponsesFunctionCallOutputStatusEnum|DataGenerationJobType|AgentEndpointConfig|TelemetryEndpointAuth|TelemetryDataKind|DetailEnum|defer_loading|read_only|azure_ai_search|set_lang|openapi|spec" .C#中心のプロジェクトなら、次のような新名称への置き換え候補も確認します。
rg "EvaluationTarget|IsPassed|DataGenerationJobKind|ImageDetailLevel|ShouldDeferLoading|IsStrict|IsReadOnly|AgentEndpointConfiguration|TelemetryEndpointAuthentication" .ただし、言語ごとに命名規則は変わります。C#では IsStrict、Pythonではスネークケース、JavaScript/TypeScriptではキャメルケースになる可能性があります。単純置換ではなく、利用中のSDKで実際に生成されたAPI名を確認してください。
REST APIの通信内容が変わっていないか確認する
今回の差分はSDK名の整理が中心に見えますが、移行時はHTTPレベルの回帰テストも必要です。
確認すべき項目は次の通りです。
| 確認項目 | 見るべきポイント |
|---|---|
| URL | パスが変わっていないか |
| HTTPメソッド | GET / POST / PATCH / DELETEなどが変わっていないか |
api-version | 利用しているAPIバージョンがGA 2.1.0と整合しているか |
| リクエスト本文 | JSONプロパティ名が変わっていないか |
| レスポンス本文 | 既存のパーサーが期待するフィールドが残っているか |
| 認証 | Microsoft Entra IDのトークン取得・Authorizationヘッダーが従来通りか |
Azure REST APIの基本構成では、要求URI、HTTPメソッド、ヘッダー、要求本文、応答本文を確認することが重要です。SDKの名前が変わっても、HTTPワイヤー上のJSONが同じなら、直接REST呼び出しのコードは修正不要な場合があります。(Microsoft Learn)
失敗しやすいポイント
「SDK名の変更」と「REST APIのJSON名の変更」を混同する
@@clientName は生成SDK上の名前を変えるための指定です。たとえばSDK上で ImageUri と表示されても、実際のJSONフィールドやREST仕様上のプロパティが同じとは限りません。移行時は、SDKの公開名とHTTPのワイヤー形式を分けて確認してください。(Azure)
PR段階の内容を本番仕様として扱う
今回のPRはOpen状態で、レビューやチェックの状況がまだ動く可能性があります。社内ドキュメントに反映する場合は、「GA 2.1.0向けPRで確認された変更」として扱い、正式SDKリリース後に最終確認するのが安全です。(GitHub)
低レベルの生成メソッドを直接使っている
DataGenerationJobs.get や EvaluatorGenerationJobs.create のような操作に Access.internal が指定されると、これまで見えていた生成メソッドが公開APIとして使えなくなる可能性があります。SDKの低レベルメソッドを直接叩いている場合は、より上位の公開メソッドへ移行できるか確認してください。
サンプルコードだけ古いまま残る
SDKのリネーム対応では、本体コードよりもサンプル、README、社内Wiki、研修資料が古くなりがちです。特に strict、defer_loading、read_only のようなプロパティは、概念としては同じでもSDK上の表記が変わる可能性があります。サンプルが古いと、新規メンバーが最初のビルドでつまずきます。
具体的な移行手順
まず検証環境でSDK更新を試す
本番ブランチではなく、検証用ブランチでSDKや生成コードを更新します。更新後は、ビルドエラーを単に直すのではなく、どの変更が今回のリネームに由来するかを分類してください。
| エラーの種類 | 典型例 | 対応 |
|---|---|---|
| 型名が見つからない | 旧クラス名・旧enum名を参照 | 新しい生成名に変更 |
| プロパティが見つからない | strict や read_only 系の参照 | SDK上の新プロパティ名を確認 |
| メソッドが見つからない | internal化された操作を呼び出し | 公開APIまたは上位メソッドに移行 |
| テストの期待値がずれる | 表示名やシリアライズ名を混同 | SDK名とJSON名を分けて検証 |
影響範囲ごとにテストを分ける
すべてを一括でテストすると、原因の切り分けが難しくなります。今回の差分に合わせて、以下のようにテストを分けると確認しやすくなります。
| テスト対象 | 重点確認 |
|---|---|
| Evaluation関連 | EvaluationTarget、IsPassed の参照 |
| Data Generation Jobs | 種別名、ジョブ作成・取得・キャンセルの呼び出し方法 |
| Evaluator Generation Jobs | 生成ジョブの公開メソッドの有無 |
| OpenAI拡張ツール | Function tool、Custom tool、MCP、OpenAPI toolの設定 |
| Azure AI Search連携 | AzureAISearch の生成名と設定コード |
| Bing grounding | 言語設定のプロパティ名 |
| Telemetry endpoint | 認証方式、エクスポート対象データ種別 |
変更履歴を社内ドキュメントに残す
リネーム対応は、修正した直後は分かっていても、数か月後に「なぜこの名前に変えたのか」が分からなくなりがちです。社内の変更履歴には、最低限以下を残してください。
| 記録項目 | 記録例 |
|---|---|
| 変更理由 | GA 2.1.0向けのSDK生成名整理 |
| 対象 | Azure AI Foundry / Azure.AI.Projects関連 |
| 変更元 | AgentEndpointConfig |
| 変更後 | AgentEndpointConfiguration |
| 確認したSDKまたは仕様 | 利用中のSDKバージョン、または参照したPR |
| 残課題 | 正式リリース後に再確認 |
REST API利用者が今すぐやるべきこと
今回のAzure REST API documentation updateは、名前の整理が中心です。ただし、SDK利用者にとっては「見た目だけの変更」ではありません。型名、プロパティ名、公開メソッドが変わると、ビルド、テスト、サンプル、社内ドキュメントに影響します。
今すぐ行うべきことは、次の3つです。
1つ目は、Azure REST APIを直接呼んでいるのか、SDK経由で使っているのかを切り分けることです。直接REST呼び出しであれば、URL、HTTPメソッド、api-version、JSONフィールドを中心に確認します。
2つ目は、Azure AI Projects、Foundry、OpenAI拡張、Agents、Telemetry関連のコードで旧名称を検索することです。特にC# SDKや生成SDKを使っている場合は、今回のリネームがビルドエラーとして出やすくなります。
3つ目は、PR段階の変更と正式SDKリリースを分けて扱うことです。PR上ではAPIレベル変更やSDK検証ステータスに関する情報も出ているため、検証環境で先に確認し、本番反映は正式なリリース情報と生成結果を見て判断するのが安全です。(GitHub)
Azure REST APIの更新を追うときは、「RESTの通信仕様が変わったのか」「SDKの表面名だけが変わったのか」を分けて見ることが重要です。今回の「Applyt renaming for the GA 2.1.0」は、まずSDK生成名と公開範囲の変更として扱い、コード検索、生成差分、回帰テストの順に確認しましょう。
コメント