2026年5月5日に公開された Azure REST API documentation update: [Microsoft Discovery] Add data-plane Discovery new GA version 2026-06-01 and 2026-02-01-preview non-breaking updates は、Microsoft Discovery のデータプレーン APIを使う開発者・運用担当者にとって、単なるドキュメント差分ではなく「GA版へ切り替える前の互換性チェックリスト」です。
結論から言うと、既存の 2026-02-01-preview をそのまま使い続けるだけなら、今回のプレビュー側修正は説明文やスキーマ順序の調整が中心で、即時の大きな改修は起きにくい内容です。一方で、2026-06-01 のGA版へ移行する場合は、KnowledgeBaseのレスポンス構造、一覧取得のページング、ツール実行時のリソース上限、ストレージマウント方式を必ず確認してください。PRでは、Microsoft.Discovery Bookshelf / Workspace 向けに 2026-06-01 のstable GAデータプレーン APIを追加し、既存の 2026-02-01-preview には非破壊的な修正を入れる内容として説明されています。(GitHub)
Azure REST API documentation updateの要点
今回のAzure REST API documentation updateで押さえるべきポイントは、次の4つです。
| 確認項目 | 内容 | 実務で見るべきポイント |
|---|---|---|
| 対象API | Microsoft Discovery の Bookshelf / Workspace データプレーン API | 管理プレーンではなく、実際のDiscovery機能を呼び出すAPIが対象 |
| 新しいAPIバージョン | 2026-06-01 stable / GA | 本番利用を見据えるなら、previewからGAへの移行可否を検証する |
| 既存previewの更新 | 2026-02-01-preview に説明文修正などの非破壊的更新 | 既存preview利用者は、コードよりも生成SDK・ドキュメント差分・テストスナップショットを確認 |
| SDK生成・AutoRest設定 | Bookshelf / Workspace のreadmeで既定タグが package-2026-06-01 に更新 | autorest readme.md を無指定で実行しているCIは、生成対象がGA版に変わる可能性がある |
Azure REST API仕様リポジトリは、Microsoft AzureのREST API仕様の基準となる場所です。今回のようなPRは、RESTリファレンスやSDK生成に影響する可能性があるため、アプリ本体だけでなく、OpenAPI / TypeSpec / AutoRestを使った生成フローも確認対象に入れるべきです。(GitHub)
まず理解すべき「データプレーンAPI」の影響範囲
Microsoft Discoveryは、AI、HPC、高度な知識管理を組み合わせ、研究開発ワークフローを支援するプラットフォームです。Bookshelfは文書をナレッジベース化し、Workspaceはプロジェクト、調査、ツール、会話などの実行基盤に関わります。(Microsoft Learn)
今回の更新は「データプレーン」です。Azureでは、リソースを作成・管理する操作をコントロールプレーン、作成済みリソースの機能を使う操作をデータプレーンと分けます。コントロールプレーンは一般にAzure Resource Manager経由で扱いますが、データプレーンは各リソースインスタンス固有のエンドポイントへ送信されます。(Microsoft Learn)
つまり、次のような呼び出しをしているコードが主な確認対象です。
GET {workspaceEndpoint}/conversations?api-version=2026-06-01&top=50
POST {bookshelfEndpoint}/knowledgeBases/{knowledgeBaseName}:startIndexing?api-version=2026-06-01Azure REST APIでは、リクエストURIのクエリ文字列にAPIバージョンなどの追加パラメーターを含めます。今回の移行でも、まず確認すべき場所は api-version の指定です。(Microsoft Learn)
Bookshelf APIで確認すべき変更点
Bookshelf側の中心は、KnowledgeBaseまわりのモデル整理です。PRでは、2026-06-01 においてKnowledgeBaseモデルが簡素化され、インデックス状態の観測性が強化されたと説明されています。具体的には、IndexingMetrics、LastIndexingRun、createdByApiVersion、失敗時の error などが追加されています。(GitHub)
KnowledgeBaseのレスポンスを固定的に読んでいるコードは要注意
2026-06-01 では、従来の version や単純な status を前提にするのではなく、直近のインデックス実行情報を lastIndexingRun として確認する設計になります。仕様上も、version と status は 2026-06-01 で削除され、createdByApiVersion と lastIndexingRun が追加されています。(GitHub)
移行時は、次のような読み替えを想定してください。
| 旧来の確認観点 | GA版で確認すべき観点 | 実務上の意味 |
|---|---|---|
KnowledgeBaseの単一の status を見る | lastIndexingRun.status を見る | 「ナレッジベース自体」ではなく「直近のインデックス実行」の状態として監視する |
version を前提に処理する | createdByApiVersion や lastIndexingRun を使う | バージョン番号で状態を判断する処理は見直す |
| インデックス失敗をログから推測する | error と lastIndexingRun.error を確認する | 失敗時の一次調査をAPIレスポンスから始めやすくなる |
| 処理件数を外部で集計する | IndexingMetrics を使う | 成功件数、失敗件数、総件数、進捗率を監視に組み込める |
IndexingMetrics には、処理済みドキュメント数、失敗数、総数、進捗率、エンリッチメント開始・終了時刻、インデックス開始・終了時刻が含まれます。監視ダッシュボードを作っている場合は、単に成功・失敗を見るだけでなく、「失敗率」「処理時間」「進捗が止まったタイミング」まで見えるように設計し直す価値があります。(GitHub)
KnowledgeBaseVersion前提のコードは洗い出す
2026-06-01 のTypeSpecでは、KnowledgeBaseVersion モデルと KnowledgeBaseVersions インターフェイスが削除対象として扱われています。/knowledgeBases/{knowledgeBaseName}/versions/... のようなバージョン配下のエンドポイントを使っている場合は、GA版で同じ前提が通用するかを必ず検証してください。(GitHub)
特に次のようなコードは検索対象です。
grep -R "KnowledgeBaseVersion\|/versions/\|getLatestVersion" .失敗しやすいのは、「APIバージョンだけ 2026-06-01 に変えれば動く」と考えてしまうケースです。既存のpreviewを継続利用することと、GA版へ移行することは別です。GA版へ切り替えるなら、レスポンスモデルとエンドポイント構造をセットで確認してください。
検索結果と長時間実行操作の扱いも変わる
2026-06-01 では、KnowledgeBaseの検索操作に SearchRequest / SearchResponse が含まれ、検索結果にはテキストと引用情報を持つ SearchResultItem が定義されています。また、長時間実行操作のステータスには operationType、indexingResult、searchResult が含まれます。(GitHub)
運用で見るべきポイントは、検索やインデックスの結果を同じ形で雑に扱わないことです。operationType を見て、インデックス操作なら indexingResult、検索操作なら searchResult を読むように分岐しましょう。
if (operation.operationType === "Indexing") {
const metrics = operation.indexingResult?.metrics;
// documentsProcessed / documentsFailed / indexingPercentageComplete を監視へ送る
}
if (operation.operationType === "Search") {
const results = operation.searchResult?.searchResults ?? [];
// text と citations をUIやログへ渡す
}Workspace APIで確認すべき変更点
Workspace側では、一覧取得、ストレージマウント、ツール実行のリソース制御、Discovery Engine更新リクエストが主な確認ポイントです。
Conversations / Investigationsの一覧取得はページング対応が必須
Conversations.list と Investigations.list は、従来のbare arrayレスポンスではなく、ページングされた結果を返す形に変更されています。skip、top、maxPageSize のクエリパラメーターも追加されています。(GitHub)
GA版のOpenAPIでは、PagedConversation と PagedInvestigation が value 配列と nextLink を持つページ型として定義されています。(GitHub)
配列を直接処理していたコードは、次のようにページ型へ対応させます。
// 旧: response が配列である前提
// const conversations = response;
// 新: GA版では value / nextLink を見る
const conversations = response.value ?? [];
const nextLink = response.nextLink;実務では、ここが最も壊れやすいポイントです。UIの一覧表示、ETL、監査ログ収集、定期同期バッチでは「最初の1ページだけ取得して終わる」不具合が起きやすいため、nextLink がある限り次ページを取得する処理を追加してください。
StorageMountProtocolでマウント方式を明示できる
ツール実行時の入出力データマウントには、新しく StorageMountProtocol が追加されました。値は NFS と BlobfuseCaching で、InputDataMount と OutputDataMount に mountProtocol を指定できます。(GitHub)
これは単なるフィールド追加ではなく、ワークロード設計に関わります。
| 選択観点 | 確認内容 |
|---|---|
| 大量の小ファイルを扱う | キャッシュ方式の影響を検証する |
| 同じデータを繰り返し読む | BlobfuseCaching の効果を検証する |
| 既存のNFS前提スクリプトがある | NFS 指定時のパス、権限、ファイル更新タイミングを確認する |
| 複数ツールで同じStorage Assetを使う | ツールごとのマウント方式を統一するか、明示的に分ける |
指定しない場合の既定動作は環境やストレージ側の設定に依存する可能性があります。性能や再現性が重要な処理では、暗黙の既定値に頼らず、検証済みの mountProtocol を明示する運用が安全です。
InfraOverridesにmaxCpu / maxRam / maxGpuが追加
InfraOverrides には、従来の cpu、ram、gpu に加えて、maxCpu、maxRam、maxGpu が追加されています。これにより、ツール実行時のリソース上限を明示しやすくなります。(GitHub)
特にGPUを使う研究開発ワークロードでは、上限指定をしないと予期しないコスト増やリソース枯渇につながることがあります。ツール定義側の要求値と、実行時の上限値を分けて考えるのがポイントです。
{
"infraOverrides": {
"cpu": "2",
"ram": "8Gi",
"gpu": "1",
"maxCpu": "4",
"maxRam": "16Gi",
"maxGpu": "1"
}
}「最低限必要なリソース」と「許容する最大リソース」を分けて管理すると、実験の再現性とコスト管理の両立がしやすくなります。
WorkingMemoryEntryTypeの大文字小文字に注意
WorkingMemoryEntryType は、thought から Thought へPascalCaseに揃えられています。TypeSpec上でも、thought は 2026-06-01 で削除され、Thought が追加されています。(GitHub)
JSONのenum値は大文字小文字を区別します。次のような比較を書いている場合は、GA版移行時に失敗します。
// 旧
if (entry.type === "thought") {
// ...
}
// 新
if (entry.type === "Thought") {
// ...
}移行期間中にpreviewとGAを並行して扱うなら、暫定的に両方を許容する変換層を入れると安全です。
const normalizedType = entry.type?.toLowerCase();
if (normalizedType === "thought") {
// preview / GA の両方を一時的に吸収
}ただし、長期的にはGA版の表記へ統一し、古い値をいつまで許容するかを決めておきましょう。
DiscoveryEngineUpdateからdiscoveryEngineStatusが外れる
DiscoveryEngineUpdate では、discoveryEngineStatus が 2026-06-01 で削除対象になっています。GA版の更新リクエストでは、systemPrompt と configuration を中心に扱う形です。(GitHub)
つまり、Discovery Engineの状態を更新リクエストで直接変更するような実装は見直しが必要です。開始・停止は専用操作、設定変更は更新リクエストという形で責務を分けてください。
2026-02-01-preview利用者は何をすべきか
2026-02-01-preview に対する今回の修正は、説明文の変更とJSONスキーマ上のフィールド順序調整が中心で、PR上ではAPI動作の変更なしと説明されています。(GitHub)
ただし、何もしなくてよいとは限りません。次のケースでは確認が必要です。
| 利用状況 | 確認ポイント |
|---|---|
| OpenAPIからSDKを自動生成している | 説明文・スキーマ順序の差分で生成物やスナップショットテストが変わらないか |
CIで autorest readme.md を無指定実行している | 既定タグが package-2026-06-01 になっていないか |
| 2025系previewタグを内部的に参照している | public repoに存在しないpreview参照を使っていないか |
| ドキュメント差分を監査している | 非破壊修正でもドキュメント更新として記録する |
Bookshelf / Workspace のAutoRest設定では、グローバル設定のタグが package-2026-06-01 になっています。previewを生成したい場合は、明示的に --tag=package-2026-02-01-preview を指定するのが安全です。(GitHub)
# GA版を生成
autorest readme.md --tag=package-2026-06-01
# preview版を明示して生成
autorest readme.md --tag=package-2026-02-01-preview影響を受ける可能性が高いチーム
今回のAzure REST API documentation updateで対応優先度が高いのは、次のようなチームです。
| チーム・担当 | 影響度 | 具体的に確認すること |
|---|---|---|
| REST APIを直接呼び出すアプリ開発者 | 高 | api-version、レスポンスモデル、ページング、enum値 |
| SDK生成・APIクライアント管理者 | 高 | AutoRestタグ、OpenAPI差分、生成モデル名、CIの固定設定 |
| RAG / ナレッジベース運用担当 | 高 | KnowledgeBaseのインデックス状態、失敗時error、検索結果の引用情報 |
| ツール実行基盤・HPC運用担当 | 中〜高 | mountProtocol、maxCpu、maxRam、maxGpu |
| 管理プレーンだけを使うインフラ担当 | 低〜中 | Discoveryリソース作成だけなら影響は限定的。ただしデータプレーン連携の有無を確認 |
| 監視・SRE担当 | 中 | LRO、Operation-Location、nextLink、インデックス進捗率 |
特に、一覧取得とKnowledgeBaseの状態監視は、テストでは見落とされやすい箇所です。単体テストでは1件だけのレスポンスをモックしがちですが、本番ではページング、失敗、再試行、長時間実行が重なります。
移行前に実施するチェック手順
GA版へ切り替える場合は、次の順序で確認すると手戻りを減らせます。
| 手順 | 作業内容 | 失敗しやすいポイント |
|---|---|---|
| 既存利用箇所を洗い出す | api-version、/versions/、KnowledgeBaseVersion、thought、discoveryEngineStatus を検索 | API Gatewayやバッチ内の固定文字列を見落とす |
| 生成設定を固定する | AutoRestやTypeSpec生成時の --tag を明示 | 無指定実行でGA版に切り替わる |
| レスポンスモデルを更新する | lastIndexingRun、value、nextLink、operationType を読む | 旧レスポンスを前提にしたJSONパースが落ちる |
| ページング処理を追加する | nextLink がある限り次ページを取得 | 1ページ目だけ同期してデータ欠落する |
| ツール実行を検証する | mountProtocol と max* リソース指定をテスト | 性能差やコスト増に気づくのが遅れる |
| 段階的に切り替える | 開発、検証、一部本番、全体の順に進める | previewとGAの混在期間に型変換を忘れる |
まずは次のような検索で、影響箇所を機械的に洗い出してください。
grep -R "2026-02-01-preview\|/versions/\|KnowledgeBaseVersion\|discoveryEngineStatus\|\"thought\"" .続いて、APIバージョンを差し替えた検証環境で、主要シナリオを確認します。
# Workspaceの会話一覧: value / nextLink を確認
curl -H "Authorization: Bearer <token>" \
"{workspaceEndpoint}/conversations?api-version=2026-06-01&top=50"
# BookshelfのKnowledgeBase取得: lastIndexingRun / createdByApiVersion を確認
curl -H "Authorization: Bearer <token>" \
"{bookshelfEndpoint}/knowledgeBases/{knowledgeBaseName}?api-version=2026-06-01"Azure REST APIの呼び出しでは、AuthorizationヘッダーにMicrosoft Entra IDで取得したBearerトークンを含めるのが基本です。今回のAPIでも、認証やエンドポイントの扱いを含めて既存クライアントの前提を確認してください。(Microsoft Learn)
「non-breaking updates」の読み違いに注意
今回のタイトルにある「non-breaking updates」は、主に既存の 2026-02-01-preview に対する修正を指して読むべきです。GA版へ移行する場合まで「何も変えずに安全」と解釈すると危険です。
実際には、2026-06-01 で次のような確認が必要になります。
| 誤解 | 正しい見方 |
|---|---|
| non-breakingだから移行作業は不要 | previewを継続する場合の影響は小さいが、GAへ切り替えるならモデル差分を確認する |
api-version だけ変えればよい | エンドポイント、レスポンス、ページング、enum値も確認する |
| 一覧APIは従来通り配列で返る | value と nextLink を持つページ型として扱う |
| KnowledgeBaseのstatusをそのまま読める | lastIndexingRun.status やoperation statusを見る |
| SDKを更新すればすべて吸収される | SDKのバージョン、対象REST API、生成モデル名を確認する |
PRページ上では、2026年5月5日の時点で新APIバージョンを導入するPRとして公開され、API stewardship board reviewなどのマージ前ステップも示されています。実装前には、Microsoft LearnのRESTリファレンス、SDKのリリースノート、自社テナントでのAPI利用可否を合わせて確認してください。(GitHub)
まず取るべき行動
今回のAzure REST API documentation updateで最初にやるべきことは、2026-06-01 へすぐ切り替えることではありません。まず、既存コードがどのAPIバージョン、どのレスポンス形状、どの生成設定に依存しているかを棚卸しすることです。
特に、次の5点を優先してください。
api-version=2026-02-01-previewの利用箇所を洗い出す- KnowledgeBaseの
version、status、KnowledgeBaseVersion前提の処理を確認する - Conversations / Investigations の一覧取得を
value/nextLink対応にする - ツール実行で
mountProtocolとmaxCpu/maxRam/maxGpuを検証する - AutoRestやSDK生成CIで
--tagを明示する
既存previewを継続する場合は、ドキュメント差分と生成物の確認で十分なケースが多いでしょう。一方、安定版APIとして 2026-06-01 を採用するなら、レスポンス構造の変更を前提に、テストデータ、監視、バッチ、SDK生成までまとめて見直すのが安全です。
コメント