Search Service REST APIs – Azure AI Searchの変更点と移行チェックポイント

Azure AI Searchの「Search Service REST APIs」は、検索インデックスの作成、ドキュメント投入、検索クエリ、エージェント検索・ナレッジベース関連の処理に関わるデータプレーンAPIです。今回の更新でまず押さえるべき結論は、通常の検索・インデックス運用だけなら、使っているapi-versionを急いで変える必要はありません。ただし、エージェント検索、ナレッジベース、ナレッジソース、SDK、課金、CORS、権限まわりを使っている環境は確認が必要という点です。

特に管理者は「どのAPIバージョンを本番で使うか」「プレビュー機能を許可するか」「Microsoft Entra ID・APIキー・課金・CORS・ネットワーク設定が意図どおりか」を確認してください。開発者は、RESTリクエストのapi-version、SDKの更新、削除されたプロパティ、取得リクエストの形式、移行時のテスト観点を洗い出す必要があります。

Search Service REST APIsとは何か

Search Service REST APIsは、Azure AI Searchのデータプレーン操作を扱うREST APIです。具体的には、検索インデックスの作成、ドキュメントのアップロード、検索クエリ、インデクサー、データソース、スキルセット、シノニムマップなど、検索データそのものに関わる処理を実行します。サービス作成や価格レベル変更などの管理操作は、別のSearch Management REST APIで扱われます。(Microsoft Learn)

実務では、この違いを取り違えないことが重要です。たとえば、検索アプリから/indexes/.../docsに問い合わせる処理はデータプレーンです。一方、検索サービスのSKU、ネットワーク、課金、マネージドIDなどの構成変更は管理プレーン側の確認が必要になる場合があります。

REST APIを呼び出す際は、HTTPS、サポート対象のapi-version、認証用のapi-keyまたはベアラートークンを明示する必要があります。api-versionを省略したり、サンプルコードの古い値をそのまま使い続けたりすると、期待した機能が使えない、または新しいスキーマと合わずにエラーになる原因になります。(Microsoft Learn)

GET https://<search-service-name>.search.windows.net/indexes?api-version=2026-04-01
api-key: <admin-or-query-key>
Content-Type: application/json

今回の更新で押さえるべき全体像

Azure AI SearchのSearch Service REST APIsでは、安定版とプレビュー版のAPIが並行して提供されています。公式のAPIバージョン一覧では、安定版の最新として2026-04-01、プレビュー版の最新として2026-05-01-previewが掲載されています。新機能は安定版に移行する前にプレビューAPIで導入されるため、本番利用では「最新だから採用する」のではなく、安定性・機能要件・コンプライアンス要件で選ぶ必要があります。(Microsoft Learn)

今回のポイントは、大きく分けると次の3つです。

観点	何が変わるか	主な対象者
APIバージョン	安定版2026-04-01とプレビュー版2026-05-01-previewの使い分けが重要	管理者、開発者
エージェント検索・ナレッジベース	ナレッジソース、取得処理、応答、SDKの扱いに影響	RAG開発者、AIアプリ担当者
運用・セキュリティ	認証、CORS、課金、ネットワーク、Purview秘密度ラベルなどの確認が必要	Azure管理者、セキュリティ担当者

単純なキーワード検索やベクター検索だけを既存APIで安定運用している場合、今回の更新は「すぐにコードを直す変更」とは限りません。一方、Azure AI SearchをRAG基盤、社内文書検索、Copilot連携、エージェント検索の根拠データ取得に使っている場合は、影響範囲が広がります。

2026-05-01-previewで追加された主な内容

2026-05-01-previewは、データプレーン操作へ新しいプレビュー機能を提供するREST APIバージョンです。公式の新着情報では、サーバーレス価格モデル、ファイル・Azure SQL・Fabric・MCP Server・Work IQなどのナレッジソース、鮮度を考慮した取得、画像コンテンツの返却、CORS、GPT-5系モデル対応、取得アクションのパラメーター追加、Purview秘密度ラベル、APIM対応、ネットワークセキュリティ境界、リストAPIのページングなどが挙げられています。(Microsoft Learn)

実務上の見方としては、すべてを一度に採用する必要はありません。むしろ、次のように自社の用途に関係するものだけを優先して確認するのが現実的です。

追加・更新項目	何に効くか	確認すべきこと
鮮度を考慮した取得	最新ドキュメントを優先したRAG・社内検索	更新日の重み付けが関連度を壊さないか
maxOutputDocuments	取得する根拠文書数の制御	回答精度、レイテンシ、トークン量のバランス
failOnError	ナレッジソースごとの必須・任意制御	一部ソース障害時に失敗させるか、部分回答を許すか
CORS設定	ブラウザーから直接取得APIを呼ぶ構成	許可オリジン、認証、情報漏えいリスク
Purview秘密度ラベル	取得結果に秘密度メタデータを含める	ラベルをUI・監査・制御にどう使うか
リストAPIのページング	大量のナレッジベース・ナレッジソース管理	一覧取得処理のページング対応
APIM対応	Azure OpenAIスキルやベクターライザーの経路制御	API Management経由の認証、監視、制限設定

特にCORSは便利な反面、設定を誤るとブラウザー経由で外部ページからサービスにアクセスされるリスクがあります。公式情報でも、CORSの有効化は利用者側の責任であり、構成によっては外部Webページがユーザーのブラウザーコンテキストでサービスやデータにアクセスできる可能性があると説明されています。(Microsoft Learn)

2026-04-01安定版で重要な変更点

2026-04-01は、エージェント検索に関する最初の安定版APIとして位置づけられています。ナレッジベース、検索インデックス・Blob・OneLake・Webのナレッジソース、インデックスエイリアス、GenAI Prompt skill、Markdown解析モード、インデクサー接続のユーザー割り当てマネージドIDなどが一般提供として整理されています。(Microsoft Learn)

一方で、安定版になったからといって、プレビュー版の全機能がそのまま使えるわけではありません。2026-04-01では、抽出型の取得契約を安定化する一方で、プレビュー期のメッセージベースのクエリ計画や応答合成など、一部の機能は削除または非対応になっています。移行時にはここを見落としやすいので注意が必要です。(Microsoft Learn)

項目	2026-04-01での扱い	実務上の注意
ナレッジベース	一般提供	ただし対応する機能範囲を確認する
応答合成	安定版では非対応の扱い	合成回答が必要ならプレビュー版の要件を確認
retrievalReasoningEffort	削除	以前の設定を含むナレッジベースは再作成が必要な場合あり
outputMode	削除	デフォルトは抽出されたグラウンディングコンテンツ
messagesベースの複数ターン	非対応	取得要求ごとに設計を見直す
ingestionPermissionOptions	azureBlob、indexedOneLakeで削除	ドキュメントレベル権限を使う構成はプレビュー要件を確認
GenAI Prompt skill	一般提供	削除されたプロパティを送ると検証エラーの原因になる

GenAI Prompt skillでは、httpMethod、timeout、batchSize、degreeOfParallelism、httpHeaders、authResourceIdなどのプロパティが2026-04-01で削除されています。これらをスキル定義に残したまま移行すると、検証エラーにつながります。(Microsoft Learn)

管理者が確認すべき設定

Azure AI SearchのREST API更新で管理者が見るべきポイントは、コードそのものよりも「どの機能を許可し、どこまで本番運用に入れるか」です。

APIバージョンの利用方針

まず、環境ごとに使用中のapi-versionを棚卸ししてください。アプリケーションコード、Azure Functions、Logic Apps、CI/CDスクリプト、Postmanコレクション、TerraformやBicepの補助スクリプト、社内ライブラリに値が分散していることがあります。

判断基準はシンプルです。

利用状況	推奨される判断
安定した検索APIだけを利用	安定版を優先し、不要なプレビュー移行は避ける
エージェント検索・ナレッジベースを本番利用	2026-04-01で要件を満たすか確認
応答合成や高度な取得制御が必要	プレビュー版の利用条件とリスクを確認
SDKを併用	RESTの互換性だけでなくSDKの破壊的変更を確認

2026-05-01-previewでは、2025-11-01-previewとの間でREST API上の重大な変更はないと説明されています。ただし、同バージョンをサポートする言語SDKではコード構造に破壊的変更が入るため、REST呼び出しだけを見て安全と判断しないことが重要です。(Microsoft Learn)

認証とアクセス制御

Azure AI Searchでは、APIキーによる認証とMicrosoft Entra IDを使ったロールベース認証が利用できます。APIキーは実装が簡単ですが、キーの保管、ローテーション、権限分離が課題になります。Microsoft Entra ID認証では、アプリケーションやマネージドIDに必要なロールを割り当て、ベアラートークンでアクセスします。(Microsoft Learn)

本番環境では、次の観点で確認してください。

確認項目	推奨アクション
管理APIキーの利用範囲	アプリ側で不要に使っていないか確認
クエリAPIキー	読み取り専用用途に限定できるか確認
Microsoft Entra ID	マネージドID化できる処理を洗い出す
ロール割り当て	最小権限になっているか確認
キーのローテーション	手順と影響範囲を文書化する

課金設定とknowledgeRetrieval

2026-04-01以降では、セマンティックランカーとエージェント検索の課金同意が分離されています。公式情報では、すべての検索サービスは無料のエージェント検索プランに自動設定され、課金分離はSearch Service 2026-04-01以降に適用されると説明されています。既にsemanticSearch=standardを使っている場合、2026-04-01へアップグレードする前にknowledgeRetrieval=standardを明示設定する必要があります。(Microsoft Learn)

これは、管理者が見落としやすい変更です。検索品質の問題だと思って調査したら、実際には課金同意やプラン設定が原因で意図したエージェント検索機能を使えていなかった、という事態を避けるためにも、移行前に設定値を確認しておきましょう。

CORSとブラウザー直接アクセス

2026-05-01-previewでは、ナレッジベースのcorsOptionsにより、ブラウザーからREST取得エンドポイントへ直接アクセスする構成が可能になります。フロントエンド開発には便利ですが、安易に*に近い許可設定をすると、外部ページからの不正な呼び出しや情報漏えいリスクが高まります。

CORSを有効にする場合は、少なくとも次の基準でレビューしてください。

項目	確認内容
許可オリジン	本番ドメインだけに限定しているか
認証方式	ブラウザーに管理キーを持たせていないか
レスポンス内容	秘密情報や内部文書のメタデータを返しすぎていないか
監査	どのアプリから呼ばれたか追跡できるか
環境分離	開発・検証・本番でCORS設定を分けているか

開発者が確認すべき移行ポイント

開発者が最初に行うべきことは、コード内のapi-versionとSDKバージョンの棚卸しです。Azure AI SearchはREST APIが明示的なバージョン指定を前提にしているため、ライブラリの更新だけでは移行が完了しません。

移行前チェックリスト

チェック項目	見る場所	失敗しやすいポイント
api-version	RESTクライアント、コード、設定ファイル	サンプルの古い値が残る
SDKバージョン	requirements.txt、package.json、.csprojなど	REST互換でもSDKメソッド名が変わる
ナレッジベース定義	作成・更新APIのJSON	削除プロパティを残す
取得リクエスト	/retrieve呼び出し	messagesとintentsの違いを混同
スキルセット	GenAI Prompt skill定義	削除済みプロパティで400エラー
テストデータ	実クエリ、権限付き文書、空結果	正常系だけで移行判断する
監視	レイテンシ、HTTPステータス、部分応答	206 Partial Contentや一部ソース失敗を見落とす

既存オブジェクトを直接上書きしない

移行では、既存のナレッジベースやナレッジソースをいきなり上書きするのではなく、現在の定義を取得し、新しい名前のオブジェクトとして作り直して検証する進め方が推奨されます。公式の移行ガイドでも、プロパティが追加・削除された場合は既存オブジェクトを上書きできないため、以前の動作を実装する一意の名前の新しいオブジェクトを作成する考え方が示されています。(Microsoft Learn)

実務では、次のような流れが安全です。

手順	作業内容
現状取得	既存のナレッジソース、ナレッジベース、スキルセット定義をGETで保存
差分確認	削除されたプロパティ、名称変更、非対応機能を確認
新規作成	新しいAPIバージョン用に別名でオブジェクトを作成
並行テスト	同じクエリで旧版・新版の結果、参照、レイテンシを比較
アプリ切替	設定値やルーティングを新版に向ける
旧版削除	本番監視後、不要になった旧オブジェクトだけ削除

2026-04-01へ移行する場合の注意

2025-11-01-previewから2026-04-01へ移行する場合、インデックスやコンテンツ自体は変更されません。更新が必要なのは主にナレッジベーススキーマと取得要求の形式です。公式ガイドでは、ナレッジソース、ナレッジベース、取得要求、課金同意、コードとクライアントの更新が移行作業として整理されています。(Microsoft Learn)

特に注意したいのは、削除されたフィールドを送信すると400 Bad Requestになる点です。retrievalReasoningEffort、outputMode、alwaysQuerySource、ingestionPermissionOptionsなどを移行後のリクエストや定義に残していないか確認してください。(Microsoft Learn)

2026-05-01-previewへ移行する場合の注意

2026-04-01または2025-11-01-previewから2026-05-01-previewへ移行する場合、RESTの要求、応答、永続化オブジェクトには互換性が保たれると説明されています。違いは主に追加機能と言語SDKの名前変更です。(Microsoft Learn)

つまり、RESTだけで実装している場合は、まずapi-version=2026-05-01-previewに変更して検証し、必要な新機能だけを段階的に採用するのが現実的です。一方、Python、JavaScript、.NET、JavaなどのSDKを使っている場合は、クライアント名、メソッド名、モデル名、エンドポイント指定の変更を必ず確認してください。

影響を受けやすいシステム例

今回の更新で特に確認が必要なのは、次のようなシステムです。

システム例	確認理由
社内文書RAGチャット	ナレッジベース、ナレッジソース、取得応答、秘密度ラベルが影響する
Copilot連携・エージェント連携	エージェント検索、Foundry、APIM、ネットワーク制御が関係する
ブラウザー完結型検索UI	CORSと認証方式の設計ミスがリスクになる
SharePointやBlobを使う検索基盤	ACL、権限変更の反映、ドキュメントレベル制御を確認する必要がある
大量インデックス管理システム	リストAPIのページング対応が必要になる可能性がある
SDK中心の開発チーム	REST互換でもSDKの破壊的変更でビルドや実行時に影響が出る

逆に、既存の検索インデックスに対して単純な検索クエリを投げるだけのアプリで、エージェント検索やナレッジベースを使っていない場合、影響は限定的です。ただし、将来的な移行に備えて、api-versionを設定ファイル化し、API更新時に差し替えやすくしておくと運用が楽になります。

よくある失敗と回避策

最新プレビューを本番に入れればよいと考える

プレビュー版は新機能を早く試せますが、安定版と同じ扱いではありません。特にコンプライアンス、外部サービス接続、データの処理場所、CORS、権限変更の反映タイミングなどは、管理者とセキュリティ担当者の確認が必要です。

新機能検証は検証環境で行い、本番は「安定版で足りるか」「プレビューが必要な機能は何か」を明確にしてから採用しましょう。

RESTの移行だけ見てSDKを見落とす

2026-05-01-previewではREST APIとしては重大な変更がない一方、SDKレイヤーではコード構造の変更が入ります。ビルドが通らない、メソッドが見つからない、レスポンスモデルの扱いが変わるといった問題は、APIサーバー側ではなくクライアント側の変更で発生します。

SDKを使うチームは、RESTの差分表だけでなくSDKの変更ログ、サンプル、型定義も確認してください。

削除されたプロパティを残したまま送信する

移行時の典型的なエラーは、古いJSONをコピーして新しいapi-versionに投げることです。APIバージョンが変わると、同じプロパティでもサポート状況が変わります。削除されたフィールドを送ると400 Bad Requestが返るため、定義ファイルやテンプレートを機械的に使い回さないようにしましょう。

CORSを広く許可しすぎる

ブラウザーから直接Azure AI Searchを呼べる構成は魅力的ですが、検索サービスは社内文書や顧客データの入口になることが多いサービスです。CORSを広く許可する前に、APIキーをブラウザーへ渡していないか、認証済みユーザーの権限で想定外のデータを取得できないか、ログで追跡できるかを確認してください。

課金同意を移行手順から外す

エージェント検索やセマンティックランカーを使う環境では、コード移行だけでなく課金同意の確認が必要です。semanticSearchとknowledgeRetrievalの役割が分かれるため、移行後に「機能が動かない」「無料枠の挙動になっている」といった問題が起きないよう、管理プレーン側の設定もチェックリストに入れてください。

展開前に実施したいテスト

本番反映前には、単にHTTP 200が返るかだけでなく、検索品質、権限、部分失敗、監査まで確認してください。

テスト観点	確認内容
機能テスト	代表クエリで旧版と新版の検索結果、参照文書、スコアを比較
権限テスト	閲覧権限のない文書が返らないことを確認
失敗テスト	一部ナレッジソース停止時のfailOnError動作を確認
性能テスト	レイテンシ、スループット、トークン量、取得文書数を比較
セキュリティテスト	CORS、APIキー露出、Entra IDロール、ネットワーク経路を確認
課金テスト	semanticSearchとknowledgeRetrievalの設定を確認
監視テスト	400、401、403、429、206などを検知できるか確認

RAGやエージェント検索では、1つのクエリが複数の検索、再ランキング、モデル呼び出し、外部データ参照に分解されることがあります。そのため、検索結果が返るだけでなく、「根拠として妥当か」「新しい文書を過度に優先していないか」「秘密度ラベルやACLを無視していないか」まで確認する必要があります。

まず何から着手すべきか

最初にやるべきことは、移行そのものではなく棚卸しです。次の順番で進めると、影響範囲を過不足なく把握できます。

優先度	作業	目的
高	使っているapi-versionを一覧化	影響を受けるコードと環境を特定する
高	エージェント検索・ナレッジベース利用有無を確認	移行要否を判断する
高	APIキー、Entra ID、CORS、ネットワークを確認	セキュリティ事故を防ぐ
中	SDK利用箇所を洗い出す	SDKレイヤーの破壊的変更を把握する
中	knowledgeRetrievalなど課金設定を確認	移行後の想定外課金・機能制限を防ぐ
中	検証環境で新APIバージョンをテスト	本番影響を出さず差分を確認する
低	新機能を段階採用	鮮度考慮、ページング、Purview連携などを必要に応じて使う

今回のSearch Service REST APIs更新は、単なるAPIリファレンスの追加ではなく、Azure AI SearchをRAGやエージェント検索の基盤として使う場合の設計・運用に関わる更新です。安定版2026-04-01で本番運用に寄せるのか、2026-05-01-previewで新機能を検証するのかを切り分け、まずはapi-version、ナレッジベース、SDK、認証、課金、CORSの6点を確認してください。