MENU

Azure REST API documentation update: Discovery/2026 02 01 preview dpの変更点と対応ポイント

Azure

Azure REST API documentation update: Discovery/2026 02 01 preview dpは、Azure DiscoveryのData Plane APIに2026-02-01-preview仕様を追加・整理する更新です。結論から言うと、Azure DiscoveryをREST APIで直接呼び出している開発者、OpenAPI/TypeSpecからSDKを生成しているチーム、dataAssetIdsやstorageId、discovery://dataassets系のURIを使っている実装は、リクエスト項目・ポーリング処理・ストレージ参照の見直しが必要です。

一方で、Azure Discoveryを使っていない環境や、管理プレーンのAzure REST APIだけを利用している環境では、すぐにコード変更が必要になる可能性は高くありません。まずは自分たちの実装がMicrosoft.Discovery.WorkspaceまたはMicrosoft.Discovery.BookshelfのData Plane APIに依存しているかを確認しましょう。

目次

Azure REST API documentation update: Discovery/2026 02 01 preview dpの要点

今回の更新は、Azure REST API仕様リポジトリのPull Request #39746として、2026年5月5日にAzure:mainへマージされたものです。PRにはdata-plane、TypeSpec、new-api-versionなどのラベルが付いており、Discovery/2026 02 01 preview dpという名前の通り、Discovery関連Data Plane APIのプレビュー仕様を扱う更新と見てよい内容です。(GitHub)

確認すべきポイントは次の3つです。

確認項目今回のポイント実務での対応
APIバージョン2026-02-01-previewがWorkspace/BookshelfのData Plane仕様として定義RESTクライアント、SDK生成設定、テストデータのapi-versionを確認
ストレージ参照dataAssetIdsや旧URIから、Storage Asset中心の参照へ移行リクエスト/レスポンスのフィールド名、URI形式、永続化データを点検
長期実行操作削除、インデックス作成、ツール実行などでLROの扱いが重要202、Operation-Location、ポーリング処理、リトライ処理をテスト

Microsoft.Discovery.WorkspaceとMicrosoft.Discovery.Bookshelfの両方で、2026-02-01-previewがData Plane APIバージョンとして定義されています。(GitHub)

何が変わったのか

今回のPRでは、Discovery配下にWorkspaceとBookshelfの仕様・サンプル・AutoRest設定が追加または更新されています。変更ファイルの内訳には.json、.md、.tsp、.yamlが含まれ、生成済みSwagger、TypeSpec、サンプルJSON、AutoRest用readmeが対象になっています。(GitHub)

特に重要なのは、単なるドキュメント文言の修正ではなく、APIクライアントが実際に参照するスキーマや操作定義が変わっている点です。PR内ではSwagger、TypeSpec、Java、C#向けのAPIViewも作成されており、SDK利用者にも影響する可能性があります。ただし、APIViewが作成されたことと、各言語のSDKパッケージがすでに利用可能であることは同義ではありません。SDK利用者は、実際に使っているパッケージのリリース状況も別途確認してください。(GitHub)

影響を受ける可能性が高い利用者

次のいずれかに当てはまる場合は、今回のAzure REST API documentation updateを確認する価値があります。

  • Azure DiscoveryのWorkspace APIを直接RESTで呼び出している
  • Azure DiscoveryのBookshelf APIでナレッジベースやバージョン管理を扱っている
  • OpenAPI/SwaggerやTypeSpecから社内SDKを生成している
  • dataAssetIds、storageId、discovery://dataassets、discovery://storagesのような旧データ参照を使っている
  • 202 Acceptedを返す長期実行操作を、即時完了の処理として扱っている
  • APIのレスポンスを固定スキーマとしてDBやログに保存している

逆に、Azure DiscoveryのData Plane APIを使っていない場合や、Azure Resource Managerの管理APIだけを利用している場合は、今回の変更による直接影響は限定的です。

Discovery.Workspaceで確認すべき変更点

Microsoft.Discovery.Workspaceでは、Conversation、Investigation、Task、Tool実行まわりの仕様が整理されています。ファイルツリー上でも、Conversations、Investigations、Tasks、Toolsに関するサンプルが2026-02-01-preview配下に追加されています。(GitHub)

InvestigationはDiscovery Engine操作とLROに注意

Investigationでは、従来のデータアセット連携系モデルや操作が2026-02-01-previewで削除扱いになっています。具体的には、Investigationに紐づくData Asset一覧、リンク、リンク解除のモデルや操作が削除対象として定義されています。代わりに、Discovery Engineの取得、更新、開始、停止、Working Memoryの取得といった操作が重要になります。(GitHub)

削除操作も注意が必要です。Investigationの削除は長期実行操作として扱われ、ポーリング前提の処理になります。従来のように「DELETEを送ったらすぐ完了」と実装している場合、画面表示や後続処理で不整合が出る可能性があります。

実務では、削除後に次の処理へ進む前に、操作ステータスを確認する設計にしておくべきです。

DELETE送信
↓
202 Acceptedを受け取る
↓
Operation-Locationまたは操作ステータス取得APIで状態確認
↓
Succeeded/Failed/Canceledなどの結果に応じて後続処理を分岐

TaskはstorageAssetIdsへの移行を確認する

Task関連では、タスク結果やタスク本体にStorage Asset参照が追加され、旧来のData Asset参照やCitationが削除対象になっています。TaskResultではstorageAssetIdsが追加され、dataAssetIdsやcitationsは2026-02-01-previewで削除扱いです。Task本体にもstorageAssetIdsが追加され、dataAssetIdsは削除対象になっています。(GitHub)

この変更は、単なる名前変更として扱うと失敗しやすい部分です。dataAssetIdsをstorageAssetIdsに置き換えるだけでなく、保存しているIDの種類、参照先リソース、後続のダウンロード/表示処理まで確認する必要があります。

旧実装でありがちな項目見直しポイント
taskResult.dataAssetIdsを表示・保存しているtaskResult.storageAssetIdsを扱う設計に変更
citationsをレスポンス前提にしているレスポンスに存在しない場合のUI・ログ・検索連携を確認
タスク作成時にData Asset IDを渡しているStorage Asset IDを渡す仕様に合わせる
タスク一覧のフィルタを固定文字列で組み立てているstatus、priorityなどの条件式が新仕様で通るか再テスト

Tool実行はstorageUri、環境変数、ログ取得がポイント

Tool実行では、データURIの扱いが大きな確認ポイントです。旧定義ではdiscovery://storagesやdiscovery://dataassetsを扱うDataUriがありましたが、2026-02-01-previewではdiscovery://storageassetsを扱うStorageUriが追加されています。入力マウント、出力マウント、実行結果の出力URIでも、旧uriではなくstorageUriが追加されています。(GitHub)

また、Tool実行リクエストではstorageIdが削除対象になり、environmentVariablesが追加されています。ただし、環境変数にはシークレットを含めないことが明記され、最大50件という制限もあります。(GitHub)

ありがちな失敗は、API仕様上の環境変数を「シークレット注入の仕組み」と誤解することです。アクセストークン、APIキー、接続文字列などをここに入れると、ログやデバッグ情報、実行環境の扱いによって漏えいリスクが高まります。秘密情報は、Azure側のID管理や安全なシークレット管理の仕組みと組み合わせて扱うべきです。

Tool実行では、実行開始、状態取得、キャンセル、実行一覧、コンピュート使用量の確認も定義されています。ログ取得ではlogCountが追加され、0〜2500の範囲が指定されています。大量ログを毎回取得すると画面表示やAPI呼び出しコストが増えるため、運用画面では初期表示を少なめにし、必要に応じて追加取得する設計が現実的です。(GitHub)

Discovery.Bookshelfで確認すべき変更点

Microsoft.Discovery.Bookshelfでは、KnowledgeBaseとKnowledgeBaseVersionまわりの仕様が中心です。ナレッジベースの一覧、バージョンの作成・取得・削除、最新バージョン取得、インデックス作成開始/キャンセル、操作ステータス取得などが2026-02-01-preview配下で定義されています。(GitHub)

dataAssetIdsからstorageAssetReferencesへ

BookshelfのKnowledgeBaseでは、storageAssetReferencesが2026-02-01-previewで追加されています。これはStorage AssetのARMリソースIDと、必要に応じてUser Assigned Managed Identityを持てる参照モデルです。一方、dataAssetIdsは同バージョンで削除対象になっています。(GitHub)

移行時は、次の観点で確認してください。

確認対象チェック内容
リクエストボディdataAssetIdsを送っていないか
保存済み設定ナレッジベース作成時のデータソースIDをStorage Asset参照へ変換できるか
マネージドIDStorage AssetへアクセスするUser Assigned Managed Identityが必要か
権限指定したIDが対象Storage Assetへアクセスできるか
テストデータ旧Data Asset IDを使ったサンプルが残っていないか

特に、storageAssetReferencesは単なる文字列配列ではなく、idと任意のuserAssignedIdentityを持つ参照です。既存コードが「ID文字列の配列」を前提にしている場合、型定義、バリデーション、画面入力、設定ファイルをまとめて見直す必要があります。

インデックス作成と削除はLRO前提で扱う

BookshelfのKnowledgeBaseVersionでは、インデックス作成開始、インデックス作成キャンセル、削除、最新バージョン削除が長期実行操作として定義されています。削除系では旧来の即時削除型の操作が削除され、202や操作ステータスを前提にした処理へ変わっています。(GitHub)

実装で確認すべきなのは、HTTPステータスコードだけではありません。次のような処理を見直してください。

実装箇所失敗しやすいパターン修正の考え方
削除後の画面更新DELETE成功直後に一覧から完全削除する操作完了まで「削除中」として表示
バッチ処理202を成功完了として次のジョブを開始操作ステータスが完了するまで待機
リトライ処理同じリクエストを無条件に再送Repeatabilityヘッダーや冪等性を考慮
監視失敗時のerrorを読まずにタイムアウト扱い操作ステータスのFailedとエラー内容を記録

RESTクライアントで確認すべき設定

生成済みSwaggerでは、WorkspaceとBookshelfのどちらも{endpoint}を使うパラメータ化ホストになっており、Workspaceはhttps://{workspaceName}.discovery.azure.com、Bookshelfはhttps://{bookshelfName}.discovery.azure.comのようなエンドポイント例が示されています。また、認証はOAuth2でhttps://discovery.azure.com/.defaultスコープを使う定義になっています。 (GitHub)

RESTクライアントでは、最低限次の設定を確認してください。

endpoint:
  https://{workspaceName}.discovery.azure.com
  または
  https://{bookshelfName}.discovery.azure.com

api-version:
  2026-02-01-preview

auth scope:
  https://discovery.azure.com/.default

特に、クライアント側でapi-versionをデフォルト値として固定している場合、コード上は新しいエンドポイントを呼んでいるつもりでも、古いAPIバージョンのまま動作することがあります。URL組み立て処理、SDK初期化処理、テスト用モック、Postmanコレクションをまとめて確認しましょう。

SDK生成・AutoRest利用者が確認すべきこと

AutoRest用readmeでは、Workspace/Bookshelfともにopenapi-type: data-plane、tag: package-2026-02-01-previewが指定されています。入力ファイルはそれぞれpreview/2026-02-01-preview/discovery-workspace.json、preview/2026-02-01-preview/discovery-bookshelf.jsonです。(GitHub)

社内SDKや独自クライアントを生成している場合は、次の手順で確認すると抜け漏れを減らせます。

# 旧フィールドや旧URIを検索
grep -R "dataAssetIds\|storageId\|discovery://dataassets\|discovery://storages" ./src ./tests

# LROを即時完了扱いしていないか検索
grep -R "Operation-Location\|202\|poll" ./src ./tests

# APIバージョン固定を検索
grep -R "api-version\|2026-02-01-preview" ./src ./tests

SDK生成後は、コンパイルが通るかだけでなく、以下をテストしてください。

テスト項目確認する内容
スキーマ互換性旧フィールドが残っていないか
ポーリング202返却後に完了まで追跡できるか
エラー処理LRO失敗時のerrorをログに残せるか
サンプル実行生成済みexamplesと実装のリクエスト形状が一致するか
認証OAuthスコープとエンドポイントが正しいか

移行時の優先順位

すべてを一度に直そうとすると、API仕様変更と業務ロジック変更が混ざって混乱します。次の順で進めると安全です。

まず旧データ参照を洗い出す

最優先は、dataAssetIds、storageId、旧uri、旧discovery://URIの検索です。これらは今回の変更で最も破綻しやすい部分です。単にコードを検索するだけでなく、設定ファイル、テストデータ、保存済みジョブ定義、ログ再実行用のJSONも確認してください。

次にLRO処理を確認する

削除やインデックス作成のような操作は、ステータスコードだけで完了判定しない設計にします。202 Acceptedを「処理完了」として扱っている箇所があれば、ステータス取得、タイムアウト、キャンセル、失敗時のロールバック方針を追加してください。

最後にSDKとUIを合わせる

APIスキーマを直しても、UIが旧項目名のままだと運用で混乱します。たとえば「Data Asset ID」という表示を残したままStorage Asset IDを入力させると、問い合わせ対応や障害調査で誤解が起きます。画面文言、CSV出力、監査ログの項目名も合わせて見直しましょう。

注意点: preview仕様を本番前提で固定しない

2026-02-01-previewは名前の通りプレビューAPIです。今回のPRはマージ済みで、90件のチェックも通過していますが、同じPRの後続文脈では、DiscoveryのGA版や非破壊更新に関する別PRも言及されています。つまり、将来の仕様変更やGA版への整理が入る可能性を考えて設計すべきです。(GitHub)

本番実装では、次のような対策を入れておくと変更に強くなります。

対策効果
APIバージョンを設定値にするGA版や次のpreviewへ切り替えやすい
レスポンスの未知フィールドを許容するプレビューAPIの追加変更に耐えやすい
LRO処理を共通化する削除・実行・インデックス作成で再利用できる
ストレージ参照をドメインモデル化するdataAssetからstorageAssetへの移行を局所化できる
SDKとREST直叩きを混在させない挙動差や認証差分を減らせる

今すぐやるべき確認リスト

今回のAzure REST API documentation updateを受けて、まずは次の順で確認してください。

優先度確認内容対象者
高Microsoft.Discovery.WorkspaceまたはMicrosoft.Discovery.Bookshelfを使っているか開発者、アーキテクト
高dataAssetIds、storageId、旧discovery://URIが残っていないかAPI実装者
高削除・実行・インデックス作成でLROを正しく待機しているかバックエンド開発者
中AutoRest/SDK生成タグがpackage-2026-02-01-previewになっているかSDK管理者
中OAuthスコープとエンドポイント設定が新仕様と一致しているかインフラ、認証担当
中UIやログの項目名がStorage Asset前提になっているかフロントエンド、運用担当
低後続PRやGA版の仕様差分を継続確認する体制があるか技術リード

今回の変更で最も重要なのは、「DiscoveryのData Plane APIが2026-02-01-previewとして整理された」ことそのものよりも、旧Data Asset中心の実装、即時完了前提の削除処理、固定されたSDK生成設定がそのままでは合わなくなる可能性がある点です。

まずはコードと設定から旧フィールドを検索し、次にLRO処理をテストしてください。そのうえで、Storage Asset参照、OAuth設定、SDK生成設定を更新すれば、今回のAzure REST API documentation updateに対して実務上のリスクを大きく減らせます。

Azure
Azure Azure REST API TypeSpec API仕様 Discovery

この記事を書いた人

佐藤健司のアバター 佐藤健司

実務の現場で詰まりがちなポイントを地図にするITブログ「IT trip」を運営。Windows／Office（Teams・Excel）からSQL、サーバ運用、ガジェットまで、再現性のある手順と“なぜそうなるか”を丁寧に解説します。読んだらすぐ試せること、そして迷った人の次の一歩が見えることを大切にしています。

関連記事

コメント

コメントする

目次