Azure REST APIのMicrosoft Discovery関連更新を見て、「自社のアプリやSDK生成に影響があるのか」「2026-06-01へ移行すべきなのか」と迷っている場合、まず押さえるべき結論はシンプルです。今回の更新は、Azure REST API全体ではなく、Microsoft DiscoveryのデータプレーンAPI、特にBookshelfとWorkspaceを直接呼び出す開発者・SDK生成担当者・API仕様をCIで取り込んでいるチームが確認すべき変更です。
2026年5月5日に公開されたPRでは、Microsoft Discovery Bookshelf / Workspace向けにデータプレーンの安定版APIバージョン2026-06-01を追加し、既存の2026-02-01-previewには説明文修正などの非破壊的な更新を加えています。既存のpreview利用者が即座に全面移行する必要があるとは限りませんが、api-versionを固定しているコード、AutoRestなどでクライアントを生成している環境、一覧APIのレスポンスを配列として処理している実装は、早めに差分確認を行うべきです。(GitHub)
今回のAzure REST API更新で何が変わったのか
今回の「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仕様に関する更新です。
主なポイントは次の3つです。
| 確認項目 | 変更内容 | 実務上の見方 |
|---|---|---|
| 新しい安定版API | 2026-06-01がBookshelf / WorkspaceのデータプレーンAPIに追加 | previewではなく安定版APIを前提に開発・検証したいチームは移行候補 |
| previewの修正 | 2026-02-01-previewに説明文修正、JSONスキーマ上のフィールド順序変更など | 通常はアプリの動作変更より、仕様生成・ドキュメント差分確認が中心 |
| SDK生成への影響 | readmeの既定タグがpackage-2026-06-01に更新 | autorest readme.mdのようにタグ未指定で生成しているCIは出力差分を確認 |
Microsoft Discoveryは、研究者やエンジニアが知識探索、実験実行、検証を含むR&Dライフサイクルを管理するための統合環境として説明されています。Bookshelfは文書をナレッジグラフ化する機能、Workspaceはプロジェクト・調査・ツール実行などを扱う領域に関係します。(Microsoft Learn)
Azure REST APIでは、要求URI、HTTPメソッド、ヘッダー、本文、応答を組み合わせてリソースを操作します。多くのAzure APIではapi-versionをクエリ文字列で指定するため、今回のようなAPIバージョン追加では、アプリ側でどのバージョンを明示しているかを確認することが重要です。(Microsoft Learn)
まず確認すべき影響範囲
今回の更新は、Azure REST APIを使うすべての利用者に影響するものではありません。対象はMicrosoft DiscoveryのデータプレーンAPIを直接または間接的に扱うケースです。
| 利用状況 | 対応優先度 | 確認すべきこと |
|---|---|---|
| Microsoft Discovery Bookshelf / WorkspaceをRESTで直接呼び出している | 高 | api-version、レスポンスDTO、ページング処理、LRO処理 |
| AutoRestやOpenAPI仕様からSDK・型定義を生成している | 高 | package-2026-06-01が生成対象になるか、CI差分が出るか |
2026-02-01-previewを本番相当で使っている | 中 | preview修正は非破壊的とされるが、生成物の差分を確認 |
| Azure SDKだけを使い、REST仕様を直接見ていない | 中 | 利用SDKがどのREST APIバージョンを対象にしているか |
| Microsoft Discovery Studioやポータル中心でAPIを直接使っていない | 低 | すぐにコード修正が必要とは限らない |
| 他のAzureサービスのREST APIだけを使っている | 低 | 今回のPR単体では原則対象外 |
なお、PRページ上ではこのPRはOpenとして表示され、new-api-versionやdata-planeなどのラベルが付与されています。また、マージ後は顧客向けに出荷済みAPIと見なされる旨や、新しいAPIバージョンのためAPI stewardship board reviewが必要である旨も示されています。実装に取り込む前に、PRのマージ状況、Microsoft Learn側のAPIバージョン表示、利用SDKのリリース状況を必ず確認してください。(GitHub)
Bookshelf APIで確認すべき変更点
KnowledgeBaseモデルはインデックス状態の見え方が変わる
Bookshelfでは、KnowledgeBase周辺のモデルが整理されています。2026-06-01では、従来のトップレベルのversionやstatusが削除対象となり、代わりにcreatedByApiVersion、lastIndexingRun、errorなどが追加されています。lastIndexingRunには、直近のインデックス実行ID、状態、エラー、メトリクスを持たせる形です。(GitHub)
実務では、次のようなコードがある場合に注意が必要です。
// 旧バージョン前提の例
if (knowledgeBase.status === "Succeeded") {
console.log(knowledgeBase.version);
}2026-06-01へ移行する場合は、直近のインデックス状態をlastIndexingRun.statusで見る設計に変えるなど、レスポンスモデルの前提を見直す必要があります。
// 2026-06-01を意識した例
const run = knowledgeBase.lastIndexingRun;
if (run?.status === "Succeeded") {
console.log({
createdByApiVersion: knowledgeBase.createdByApiVersion,
documentsProcessed: run.indexingMetrics?.documentsProcessed,
documentsFailed: run.indexingMetrics?.documentsFailed,
});
}IndexingMetricsで処理件数と進捗を監視しやすくなる
IndexingMetricsには、処理済みドキュメント数、失敗ドキュメント数、総ドキュメント数、インデックス完了率、enrichmentとindexingの開始・終了時刻が含まれます。これにより、単に「成功・失敗」を見るだけでなく、どの段階で止まったのか、どれくらいの文書が処理されたのかを監視しやすくなります。(GitHub)
運用で活用するなら、次のようなメトリクスをダッシュボード化すると実用的です。
| 監視項目 | 見るべきフィールド | 使いどころ |
|---|---|---|
| インデックス進捗 | indexingPercentageComplete | 長時間処理の進捗確認 |
| 失敗率 | documentsFailed / documentsTotal | データ品質や取り込み失敗の検知 |
| 処理対象数 | documentsTotal | 想定したファイル群が対象になっているか |
| enrichment時間 | enrichmentStartTimeUtc / enrichmentEndTimeUtc | 前処理に時間がかかるケースの切り分け |
| indexing時間 | indexingStartTimeUtc / indexingEndTimeUtc | 実インデックス処理のボトルネック確認 |
KnowledgeBaseの操作ステータスはoperationTypeで分かりやすくなる
KnowledgeBaseOperationTypeが追加され、Indexing、CancelIndexing、Search、Deleteといった操作種別を型として扱えるようになります。さらに、操作ステータスにはindexingResultやsearchResultが追加され、インデックス操作や検索操作の結果を区別して扱える形になります。(GitHub)
特に、複数の長時間実行操作を同じ監視ジョブでポーリングしている場合は、operationTypeを使って処理を分岐すると、ログやエラー通知が読みやすくなります。
switch (operation.operationType) {
case "Indexing":
console.log(operation.indexingResult?.metrics);
break;
case "Search":
console.log(operation.searchResult?.searchResults);
break;
case "Delete":
console.log("KnowledgeBase delete operation");
break;
}KnowledgeBase検索は非同期処理として扱う前提で確認する
Bookshelfのsearch操作は、/knowledgeBases/{knowledgeBaseName}:searchに対するPOSTとして定義され、202レスポンスとOperation-Locationヘッダーを返す形が示されています。つまり、検索要求を投げて即座に最終結果を受け取る前提ではなく、操作ステータスをポーリングして結果を確認する設計を意識する必要があります。(GitHub)
失敗しやすいのは、HTTPステータス202を「まだ結果がないから失敗」と誤判定する実装です。202 Acceptedを正常な受付として扱い、Operation-Locationを保存して後続確認に使うようにしましょう。
Workspace APIで確認すべき変更点
ConversationsとInvestigationsの一覧レスポンスがページ形式になる
Workspaceで最も実装影響が出やすいのは、一覧APIのレスポンス形状です。Conversations.listとInvestigations.listは、従来の裸の配列レスポンスから、CustomPageを返すページング形式に変わります。PR本文でも、skip、top、maxPageSizeクエリパラメーターを伴うページング操作へ変更されることが示されています。(GitHub)
2026-06-01のOpenAPIでは、PagedConversationやPagedInvestigationがvalue配列とnextLinkを持つオブジェクトとして定義されています。(GitHub)
旧実装で次のように配列を直接処理している場合は、移行時に失敗しやすいポイントです。
// 旧レスポンスが配列である前提の例
const conversations = await listConversations();
for (const conversation of conversations) {
console.log(conversation.name);
}ページ形式では、まずvalueを取り出し、必要に応じてnextLinkを追跡する処理に変える必要があります。
// 2026-06-01のページ形式を意識した例
let page = await listConversations({ top: 50 });
for (const conversation of page.value) {
console.log(conversation.name);
}
while (page.nextLink) {
page = await fetchNextPage(page.nextLink);
for (const conversation of page.value) {
console.log(conversation.name);
}
}大量のConversationやInvestigationを扱う環境では、ページング対応は単なる型修正ではありません。API呼び出し回数、再試行、nextLink保存、途中失敗時の再開位置まで設計しておくと、運用時のトラブルを減らせます。
skip、top、maxPageSizeは一覧取得の負荷制御に使える
ListPaginationParametersとして、skip、top、maxPageSizeが追加されています。skipはスキップ件数、topは返す最大件数、maxPageSizeは1ページあたりの最大件数を指定するためのパラメーターです。(GitHub)
実装時は、次のように使い分けると分かりやすくなります。
| パラメーター | 役割 | 使い方の例 |
|---|---|---|
top | 取得したい総件数の上限 | 管理画面で最新50件だけ表示 |
maxPageSize | 1回のレスポンスで返す件数の上限 | APIレスポンスが重くならないよう100件単位で取得 |
skip | 先頭から読み飛ばす件数 | 単純なページ送りや再取得時の位置調整 |
ただし、nextLinkが返る場合は、独自にskipを増やして再計算するより、基本的にはnextLinkを使う実装のほうが安全です。サーバー側のページング仕様が変わっても追従しやすくなります。
StorageMountProtocolでマウント方式を明示できる
Workspaceのツール実行まわりでは、StorageMountProtocolが追加され、値としてNFSとBlobfuseCachingが定義されています。また、InputDataMountとOutputDataMountにmountProtocolを指定できるようになります。(GitHub)
これは、ツールコンテナに入力データや出力先をマウントする際の挙動に関わります。たとえば、読み取り性能を重視する処理、キャッシュの有無で結果や速度が変わる処理、大量ファイルを扱うバッチ処理では、マウント方式の違いが実行時間や安定性に影響する可能性があります。
確認すべきポイントは次のとおりです。
| 確認箇所 | 判断基準 |
|---|---|
| 既存のツール実行定義 | inputDataやoutputDataでマウントを使っているか |
| ストレージ種別 | NFS前提のパス操作やファイルロックを使っていないか |
| パフォーマンス要件 | 小さなファイル多数か、大容量ファイル少数か |
| 再現性 | キャッシュ利用時に古いデータを参照するリスクがないか |
特に、ツール内でファイルの存在確認、ディレクトリ走査、ロックファイル作成を行う場合は、NFSとBlobfuseCachingのどちらを使うかで挙動確認が必要です。
InfraOverridesで最大CPU・RAM・GPUを制御できる
InfraOverridesには、従来のcpu、ram、gpu、replicaCount、imageUriに加えて、maxCpu、maxRam、maxGpuが追加されています。これはツール実行時のリソース上限を制御するための項目です。(GitHub)
実務では、次のようなケースで役立ちます。
| 利用シーン | 使い方 |
|---|---|
| コスト上限を守りたい | GPU数やCPU上限を明示して過剰利用を防ぐ |
| 共有環境で暴走を防ぎたい | 特定ツールだけ最大RAMを制限する |
| 実験ごとの差を比較したい | 同じツールを異なる上限で実行し、処理時間や精度を比較 |
| 本番運用前の検証 | 低めの上限で失敗条件を確認する |
注意点は、maxCpuやmaxRamは「その分のリソースが必ず確保される」という意味ではなく、実行時の上限指定として扱うべき点です。実際の利用可否は、環境のノードプール、クォータ、スケジューリング状況にも左右されます。
WorkingMemoryEntryTypeの値がthoughtからThoughtへ変わる
WorkingMemoryEntryTypeでは、thoughtが2026-06-01で削除対象となり、Thoughtが追加されています。小さな差に見えますが、文字列比較やenum変換を厳密に行っているコードでは影響が出ます。(GitHub)
次のような実装は移行時に確認が必要です。
// 旧バージョン前提
if (entry.type === "thought") {
renderThought(entry.content);
}2026-06-01を使う場合は、新しい値に対応しつつ、移行期間は両方を許容する実装にしておくと安全です。
if (entry.type === "Thought" || entry.type === "thought") {
renderThought(entry.content);
}ただし、最終的には利用APIバージョンに合わせて、許容値を整理してください。いつまでも旧値を残すと、データ不整合を見逃しやすくなります。
DiscoveryEngineUpdateからdiscoveryEngineStatusが外れる
DiscoveryEngineUpdateでは、discoveryEngineStatusが2026-06-01で削除対象となっています。Discovery Engineの状態を更新リクエストで直接書き換えるような実装がある場合は、systemPromptやconfigurationなど、実際に更新可能なフィールドだけを送るように見直しましょう。(GitHub)
ありがちな失敗は、既存オブジェクトをそのままPATCH本文に流用することです。読み取り用モデルと更新用モデルを分けていない場合、削除されたフィールドや読み取り専用のフィールドを送ってしまい、400系エラーや予期しない無視につながる可能性があります。
2026-02-01-preview利用者は何をすべきか
今回のPRでは、2026-02-01-previewに対して「Resources for indexing operation」から「Parameters for indexing operation」への説明文修正、KnowledgeBase操作ステータス説明の修正、JSONスキーマ上のstatusフィールド位置の並べ替えが含まれています。PRではこれらが非破壊的な修正として説明されています。(GitHub)
preview利用者がまず行うべきことは、アプリの大規模改修ではなく、生成物とテストの差分確認です。
| 確認対象 | やること |
|---|---|
| OpenAPIから生成した型 | 説明文やフィールド順序変更で差分が出るか確認 |
| スナップショットテスト | JSONスキーマの順序差分だけで失敗していないか確認 |
| APIドキュメント生成 | 表示文言の変更が利用者向けドキュメントに反映されるか確認 |
| CIのlint / validation | warningやsuppressionの差分が出ないか確認 |
非破壊的とされる変更でも、コード生成やスナップショット比較では差分として検出されることがあります。特に、API仕様ファイルを取り込んで社内SDKを自動生成しているチームは、PR反映後の生成結果を一度レビューするのがおすすめです。
SDK生成・CIで特に注意したいポイント
BookshelfとWorkspaceのreadmeでは、openapi-type: data-planeが指定され、既定のtagがpackage-2026-06-01になっています。つまり、タグを明示せずにAutoRestを実行している場合、これまでpreview仕様を前提としていた生成結果が、安定版2026-06-01仕様へ切り替わる可能性があります。(GitHub)
次のようなCI設定は確認してください。
# タグ未指定の場合、readme側の既定tagに依存する
autorest readme.mdpreview仕様で生成を続けたい場合は、明示的にタグを指定します。
autorest readme.md --tag=package-2026-02-01-preview安定版へ切り替える場合は、次の順序で進めると安全です。
| 手順 | 作業内容 | 失敗しやすい点 |
|---|---|---|
| 1 | 生成対象タグを明示する | readmeの既定変更に気づかず生成結果が変わる |
| 2 | 生成コードの差分を見る | 型名変更だけでなくレスポンス形状の変更を見落とす |
| 3 | REST統合テストを実行する | mockが旧レスポンス配列のままで通ってしまう |
| 4 | ページングとLROを重点確認する | value、nextLink、Operation-Locationの扱い漏れ |
| 5 | 本番前に小さくカナリア実行する | Discovery環境やテナント側の利用可否を確認しないまま展開する |
PR上ではAPIViewがSwagger、TypeSpec、Python、C#、JavaScript、Java向けのAPIレビューを作成していることも示されています。ただし、APIViewのレビュー作成はSDKパッケージが利用可能になったことを意味するわけではありません。実際に使うSDKのリリースノート、パッケージバージョン、対応REST APIバージョンは別途確認が必要です。(GitHub)
移行前に検索すべきコードパターン
まずはコードベース内で、旧バージョンや変更対象フィールドを洗い出しましょう。
grep -R \
-e "2026-02-01-preview" \
-e "package-2026-02-01-preview" \
-e "KnowledgeBaseVersion" \
-e "knowledgeBase.version" \
-e "knowledgeBase.status" \
-e "Conversations_List" \
-e "Investigations_List" \
-e "discoveryEngineStatus" \
-e '"thought"' \
./src ./tests見つかった箇所は、次の観点で分類します。
| 検出された文字列 | 確認内容 |
|---|---|
2026-02-01-preview | GAへ移行する対象か、preview継続か |
KnowledgeBaseVersion | 2026-06-01で不要または構造変更になる処理か |
knowledgeBase.version | createdByApiVersionやlastIndexingRunで代替できるか |
knowledgeBase.status | lastIndexingRun.statusへ変更すべきか |
Conversations_List | 配列ではなくページ形式に対応しているか |
Investigations_List | valueとnextLinkを処理しているか |
discoveryEngineStatus | 更新リクエストに含めていないか |
"thought" | Thoughtにも対応しているか |
この検索は、単なる文字列置換のためではありません。どの箇所が「APIバージョン固定」「レスポンス構造依存」「enum値依存」「更新リクエスト依存」なのかを分けることで、移行作業の優先順位が明確になります。
動作確認で見るべきテストケース
2026-06-01へ移行する場合は、通常の正常系テストだけでは不十分です。今回の変更点に合わせて、次のテストを追加してください。
| テスト観点 | 確認内容 |
|---|---|
| APIバージョン | api-version=2026-06-01で呼び出しているか |
| 認証 | Microsoft Entra IDのトークン取得・Authorizationヘッダー送信が継続して動くか |
| Bookshelf取得 | versionやstatusがなくても処理できるか |
| インデックス監視 | lastIndexingRunとIndexingMetricsを読めるか |
| Bookshelf検索 | 202 AcceptedとOperation-Locationを正常処理できるか |
| Conversations一覧 | value配列とnextLinkを処理できるか |
| Investigations一覧 | 大量データ時にページングが途切れないか |
| Storage mount | mountProtocol指定時にツール実行が成功するか |
| InfraOverrides | maxCpu、maxRam、maxGpu指定時の挙動を確認する |
| enum値 | Thoughtを旧thoughtと混同していないか |
| 更新リクエスト | discoveryEngineStatusなど削除対象フィールドを送っていないか |
REST APIを直接呼び出す場合は、HTTPステータス、ヘッダー、レスポンス本文をログに残すと切り分けが速くなります。特に長時間実行操作では、最初のリクエストID、Operation-Location、ポーリング結果、最終ステータスをセットで記録しておくと、障害調査に役立ちます。
よくある誤解と注意点
「GAが追加された」だけで自動的に本番利用できるとは限らない
2026-06-01は安定版APIバージョンとして追加されていますが、実際に利用できるかは、PRのマージ状況、対象リージョン、テナント、サービス側の公開状態、SDKの対応状況に左右されます。API仕様ファイルに存在することと、自社環境でただちに呼び出せることは分けて考えてください。
「non-breaking」でもバージョンを変えればコード修正が必要になることがある
今回の2026-02-01-preview修正は非破壊的とされています。一方で、previewから2026-06-01へ自分で移行する場合は、一覧レスポンスのページング化、KnowledgeBaseモデルの整理、enum値変更など、コード上の対応が必要になる場合があります。non-breakingという表現を「どのAPIバージョンでも無修正で移行できる」という意味に広げて解釈しないようにしましょう。
生成SDKの差分をレビューせずに更新しない
AutoRestやOpenAPI Generatorで生成したコードは、仕様の小さな変更でも型やメソッドの戻り値が変わることがあります。特に、一覧APIの戻り値がConversation[]からPagedConversation相当へ変わる場合、コンパイルは通っても実行時の処理が漏れる可能性があります。
環境変数にシークレットを入れない
Workspaceのツール実行仕様では、環境変数にシークレットを含めない旨が記載されています。API移行とは別の観点ですが、ツール実行を自動化している場合は、接続文字列、APIキー、トークンを環境変数へ直接入れていないかも同時に確認しましょう。(GitHub)
次に取るべき行動
今回のAzure REST API更新に対して、最初にやるべきことは「移行するかどうか」を決めることではありません。まず、自社のコードやCIがMicrosoft DiscoveryのBookshelf / WorkspaceデータプレーンAPIにどの程度依存しているかを棚卸しすることです。
優先順位は次の順で進めると安全です。
- PRのマージ状況とMicrosoft Learn側のAPIバージョン表示を確認する
- コード内の
api-version、AutoRestタグ、旧レスポンス前提の処理を検索する Conversations.listとInvestigations.listのページング対応を先に確認する- Bookshelfの
KnowledgeBase、lastIndexingRun、IndexingMetricsを使った監視へ移行できるか確認する - SDK生成をしている場合は、
package-2026-06-01とpackage-2026-02-01-previewの生成差分を比較する - 本番反映前に、LRO、ページング、enum値、削除対象フィールドを含む統合テストを実行する
安定版2026-06-01は、Microsoft DiscoveryのデータプレーンAPIを本格利用するうえで重要な節目です。一方で、previewからの移行は単なるapi-versionの置き換えではありません。レスポンス形状、監視項目、ページング、ツール実行のリソース制御まで確認し、変更点を小さく分けて検証することが、トラブルの少ない移行につながります。
コメント