Azure REST APIでAzure AI Searchを使っている場合、今回まず確認すべき結論はシンプルです。本番環境は最新の安定版である2026-04-01を基準にし、検証・新機能評価では2026-05-01-previewを分けて扱うのが安全です。公式の「API Versions of Search Service REST APIs」は、Azure AI SearchのSearch Service REST API、つまり主にデータプレーン操作の利用可能なAPIバージョンを整理したページで、最新の安定版とプレビュー版の位置づけを確認できます。(Microsoft Learn)
特に、RAG、エージェント型検索、社内Copilot風アプリ、ベクトル検索、ナレッジベースを運用しているチームは、単にapi-versionを書き換えるだけでは不十分です。SDKの対応バージョン、課金設定、CORS、権限、ナレッジソース、プレビュー機能の扱いまで確認しないと、移行後に検索結果・認証・課金・レスポンス形式で想定外の差分が出る可能性があります。
Azure REST APIのAI/Copilot更新で何が変わるのか
今回のポイントは、Azure AI Search REST APIのバージョン一覧が更新され、安定版とプレビュー版の使い分けがより重要になったことです。
Microsoft LearnのAPIバージョン一覧では、Search Service REST APIの安定版として2026-04-01が最新、プレビュー版として2026-05-01-previewが最新とされています。REST APIリファレンスはバージョン管理され、各リファレンスページでバージョンセレクターを使って対象バージョンの内容を確認できます。(Microsoft Learn)
| 区分 | 最新バージョン | 実務での位置づけ |
|---|---|---|
| データプレーン安定版 | 2026-04-01 | 本番運用の第一候補。既存機能の安定利用や一般提供機能の利用に向く |
| データプレーンプレビュー | 2026-05-01-preview | 新機能の検証向け。ナレッジソース拡張、CORS、取得制御などを試す場合に使う |
| コントロールプレーン安定版 | 2025-05-01 | Searchサービス作成・更新など管理操作の安定版 |
| コントロールプレーンプレビュー | 2026-03-01-preview | knowledgeRetrievalなど一部の新しい管理設定で必要になる |
ここで混同しやすいのが、Search Service REST APIとSearch Management REST APIは別物という点です。検索インデックス、ドキュメント検索、ナレッジベース取得などは主にデータプレーンです。一方、サービス自体の設定、課金同意、管理キー取得などはコントロールプレーン側で扱います。Microsoftの移行ガイドでも、最新のREST APIとしてデータプレーン安定版2026-04-01、データプレーンプレビュー2026-05-01-preview、コントロールプレーン安定版2025-05-01、コントロールプレーンプレビュー2026-03-01-previewが整理されています。(Microsoft Learn)
最新の安定版2026-04-01で押さえるべき変更点
2026-04-01は、Azure AI SearchのデータプレーンREST APIにおける最新の安定版です。Microsoftの新機能情報では、Search Service 2026-04-01がデータプレーン操作に対応する新しい安定版REST APIとして示されています。(Microsoft Learn)
管理者・開発者が最初に見るべきポイントは次の3つです。
ナレッジベースとナレッジソースの一部が一般提供に移行
2026-04-01では、ナレッジベース、検索インデックスナレッジソース、Blobナレッジソース、OneLakeナレッジソース、Webナレッジソースなどが一般提供として扱われます。ただし、BlobやOneLakeのドキュメントレベル権限に関する一部機能は引き続きプレビュー扱いで、特定のプレビューAPIが必要です。(Microsoft Learn)
実務上は、「一般提供になった機能」と「まだプレビューが必要な細部機能」を分けて棚卸しすることが重要です。たとえば、ナレッジソース自体は安定版で使えても、ACLや権限制御の細かい挙動まで本番要件に含める場合は、プレビュー依存が残る可能性があります。
GenAI Prompt skillの定義変更に注意
2026-04-01では、GenAI Prompt skillの定義からhttpMethod、timeout、batchSize、degreeOfParallelism、httpHeaders、authResourceIdの6プロパティが削除されました。これらを含む定義を残したままアップグレードすると、400 Bad Requestエラーになると案内されています。(Microsoft Learn)
移行前には、スキルセット定義のJSONを検索し、該当プロパティが残っていないか確認してください。特に、過去にパフォーマンス調整目的でtimeoutやbatchSizeを明示していた環境は見落としやすいポイントです。
{
"skills": [
{
"@odata.type": "#Microsoft.Skills.Custom.GenAI.PromptSkill",
"name": "sample-genai-prompt-skill"
}
]
}上記は概念例です。実際の定義では、古いプロパティを削除したうえで、現在のAPIリファレンスに合わせて再検証してください。
エージェント型検索の課金同意が分離
2026-04-01以降では、セマンティックランカーとエージェント型検索の課金同意が分離されます。エージェント型検索の有料利用はknowledgeRetrievalで制御され、従来のsemanticSearchとは別に扱われます。(Microsoft Learn)
これが重要なのは、既存環境でsemanticSearch=standardを設定していても、knowledgeRetrieval=standardへ自動的に引き継がれるとは限らないためです。Microsoftのドキュメントでは、semanticSearchに依存して有料のエージェント型検索を有効化していた場合、Search Service REST API 2026-04-01以降へ移行する前に、knowledgeRetrievalを明示的にstandardへ設定する必要があると説明されています。(Microsoft Learn)
プレビュー版2026-05-01-previewで追加された主な機能
2026-05-01-previewは、最新のプレビュー版です。プレビューAPIは新機能を先行導入する場であり、安定版へ移行する前の機能が含まれます。公式ページでも、新機能は安定版へ移る前にプレビューAPIで導入されると説明されています。(Microsoft Learn)
今回のプレビューでは、Copilot型アプリやRAG基盤に関係する更新が多く含まれています。
| 変更領域 | 追加・更新内容 | 確認すべき利用者 |
|---|---|---|
| ナレッジソース | File、Azure SQL、Fabric Data Agent、Fabric Ontology、MCP Server、Work IQなどのナレッジソース | 社内データを横断検索・RAGに使う開発者 |
| 取得制御 | baseFilter、filterAddOn、maxOutputDocuments、failOnErrorなど | 検索精度・根拠文書数を制御したい開発者 |
| セキュリティ・ガバナンス | Microsoft Purview感度ラベル、SharePoint ACL関連の更新 | 情報保護・権限管理を重視する管理者 |
| 接続・ネットワーク | APIM経由のazure-api.net、Network Security Perimeter、Shared Private Link | 閉域接続・API管理を行うインフラ担当 |
| フロントエンド連携 | Knowledge baseのCORS設定 | ブラウザーから直接取得APIを呼ぶWebアプリ開発者 |
| 運用性 | List APIのページング、サービス統計の追加 | 大量オブジェクト管理・監視担当 |
特に注目すべきは、ナレッジソースの拡張です。2026-05-01-previewでは、ファイルを直接ナレッジベースへアップロードするFile knowledge source、Azure SQL Databaseを使うAzure SQL knowledge source、FabricやMCP Server、Work IQを利用するナレッジソースなどがプレビューとして追加されています。(Microsoft Learn)
また、取得処理では、検索インデックスナレッジソースに永続的な取得デフォルトを設定でき、baseFilterと実行時のfilterAddOnをAND条件で組み合わせる仕組みが追加されています。取得結果数を制御するmaxOutputDocuments、必須・任意のナレッジソースを指定するfailOnErrorなども追加されています。(Microsoft Learn)
影響範囲：誰が何を確認すべきか
Azure REST APIのAPIバージョン更新は、検索機能そのものだけでなく、アプリ、インフラ、セキュリティ、課金にまたがって影響します。
| 立場 | まず確認すること | 見落とすと起きやすい問題 |
|---|---|---|
| アプリ開発者 | REST呼び出しのapi-version、レスポンス形式、SDKバージョン | コンパイルは通るが検索結果処理や取得レスポンス処理が壊れる |
| Azure管理者 | Search Management REST APIのバージョン、knowledgeRetrieval、キー管理 | 課金同意が反映されない、管理キー取得処理が失敗する |
| セキュリティ担当 | CORS、ACL、Purview感度ラベル、外部サービス連携 | ブラウザー経由の不要なアクセス経路や権限反映の遅延を見落とす |
| RAG/Copilot担当 | ナレッジベース、ナレッジソース、取得パラメーター | 根拠文書数、回答生成、推論設定の差分で品質が変わる |
| 運用担当 | プレビュー利用範囲、本番と検証環境の分離 | プレビュー依存のまま本番展開し、後続変更の影響を受ける |
実務では、まずリポジトリ全体でapi-version=を検索してください。REST Client、curl、Postmanコレクション、Terraform外部スクリプト、CI/CD内の検証スクリプト、アプリ設定ファイルに分散していることがあります。
grep -R "api-version=" .
grep -R "2025-11-01-preview" .
grep -R "2026-04-01" .SDKを利用している場合は、コード上にREST APIバージョンが見えないことがあります。Microsoftの移行ガイドでは、各Azure SDKパッケージは特定のREST APIバージョンを対象にしているため、パッケージがサポートするREST APIバージョンを変更ログで確認し、最新機能を使うにはパッケージ更新が必要と説明されています。(Microsoft Learn)
移行時の基本手順
Azure AI Search REST APIの移行は、いきなり本番のapi-versionを置き換えるのではなく、次の順序で進めるのが安全です。
| 手順 | 作業内容 | 判断基準 |
| -: | ———————— | ——————————————– |
| 1 | 現在利用中のAPIバージョンを棚卸しする | 安定版、プレビュー版、非推奨版を分ける |
| 2 | 利用機能を分類する | 通常検索、ベクトル検索、セマンティックランカー、ナレッジベース、スキルセットなど |
| 3 | 破壊的変更を確認する | GenAI Prompt skill、エージェント型検索、ベクトル構文、接続情報取得など |
| 4 | 検証環境でapi-versionを変更する | レスポンス形式、検索順位、エラー、認証、課金設定を確認 |
| 5 | SDK利用時はパッケージ更新と変更ログ確認を行う | REST APIの対象バージョンとSDKの実装差分を確認 |
| 6 | 本番展開は段階的に行う | ロールバック手順、監視、エラー閾値を決めておく |
Microsoftは、APIバージョンを連続的にアップグレードし、最新バージョンに到達するまで各バージョンの差分を確認することを推奨しています。また、直接REST APIを呼んでいるコードでは、既存バージョンを検索して新しいバージョンへ置き換え、破壊的変更を確認する流れが案内されています。(Microsoft Learn)
古い2023-07-01-previewは使い続けない
特に注意したいのが2023-07-01-previewです。このバージョンはベクトル検索サポートの初期REST APIでしたが、現在は非推奨であり、安定版または新しいプレビューREST APIへ移行する必要があると説明されています。(Microsoft Learn)
ベクトル検索を早期導入した環境では、古いベクトル構成やクエリ構文が残っている可能性があります。新しいAPIへ直接移行すると、フィールド定義やクエリ形式の差分でエラーになることがあるため、インデックス定義と検索リクエストをセットで確認してください。
エージェント型検索を使っている場合の注意点
エージェント型検索、ナレッジベース、ナレッジソースを使っている場合は、通常のキーワード検索や単純なベクトル検索より移行確認が重くなります。
Microsoftの移行ガイドでは、エージェント型検索をサポートする各バージョンで破壊的変更が導入されており、プレビュー版を対象にしているコードは、利用ケースが2026-04-01で完全にサポートされる場合のみ最新安定版への移行を推奨すると説明されています。回答合成、非最小の推論努力、マルチターンメッセージに依存する場合は、移行前に差分確認が必要です。(Microsoft Learn)
2025-11-01-previewから2026-04-01へ移行する場合、インデックスとコンテンツはそのままでも、ナレッジベースのスキーマとretrieveリクエストの形を更新する必要があります。たとえば、retrieveリクエストではmessagesではなくintentsを使い、maxOutputSizeではなくmaxOutputSizeInTokensを使う形へ変わります。(Microsoft Learn)
開発現場では、次の観点でテストケースを用意すると差分を見つけやすくなります。
| テスト観点 | 確認例 |
|---|---|
| 入力形式 | 既存のmessagesベースのリクエストが残っていないか |
| 出力形式 | 合成回答ではなく、抽出的な根拠コンテンツとして処理できるか |
| 参照情報 | referencesやactivityを既存UIが正しく扱えるか |
| 権限 | Blob、OneLake、SharePointなどの権限付きデータで期待通りに絞り込めるか |
| 課金 | knowledgeRetrievalが意図したプランになっているか |
CORSと外部サービス接続は本番投入前に必ず確認する
2026-05-01-previewでは、Knowledge baseにCORSを設定し、ブラウザーからサービスのretrieve呼び出しを直接行えるようにするcorsOptionsが追加されています。一方で、公式ドキュメントでは、CORS設定によって外部Webページがユーザーのブラウザーコンテキストを使ってサービスやデータへアクセス・呼び出しできる可能性があり、CORSの有効化は自己責任であると注意されています。(Microsoft Learn)
これは、社内ポータルや業務Webアプリから直接Azure AI Searchを呼びたい場合には便利ですが、安易に広いオリジンを許可すると危険です。
避けるべき設定例は次の通りです。
{
"corsOptions": {
"allowedOrigins": ["*"]
}
}本番では、少なくとも以下を確認してください。
- 許可するオリジンを本番ドメインに限定する
- 管理者用画面と一般ユーザー用画面で呼び出し経路を分ける
- APIキーをブラウザーに埋め込まない設計にする
- Entra ID、バックエンドAPI、APIMなどを組み合わせて認可を制御する
- CORS有効化後にブラウザーの開発者ツールで実際のリクエストヘッダーを確認する
また、2026-05-01-previewは他のMicrosoftサービスやサードパーティサービスへの接続をサポートし、データ処理や保存がAzureのコンプライアンス境界外で発生する可能性にも触れられています。規制業種や個人情報を扱うシステムでは、技術検証だけでなく、データ所在・契約・社内承認の確認も必要です。(Microsoft Learn)
管理者が確認すべき設定
管理者は、アプリのapi-versionだけでなく、サービス管理側の設定も確認してください。特に次の3点は移行トラブルの原因になりやすいです。
knowledgeRetrievalの課金設定
エージェント型検索の有料利用を継続するには、Search Management REST APIでknowledgeRetrievalを設定する必要があります。Microsoftのドキュメントでは、2026-04-01以降はknowledgeRetrievalがエージェント型検索の課金を制御し、ポータルには専用の課金制御がないためREST APIで管理する必要があると説明されています。(Microsoft Learn)
PATCH https://management.azure.com/subscriptions/{subscriptionId}/resourcegroups/{resourceGroup}/providers/Microsoft.Search/searchServices/{serviceName}?api-version=2026-03-01-preview
Content-Type: application/json
Authorization: Bearer {token}
{
"properties": {
"knowledgeRetrieval": "standard"
}
}無料枠で検証している環境と、有料利用を許可する本番環境を分けて管理すると、意図しない課金や本番停止を防ぎやすくなります。
管理キー・接続文字列をGETレスポンスから読まない
2024年3月29日以降、サポートされるREST APIでは、GET Skillset、GET Index、GET Indexerがキーや接続プロパティをレスポンスで返さなくなっています。管理キーやクエリキーが必要な場合は、Search Management REST APIを使う必要があります。(Microsoft Learn)
過去に「既存設定をGETして、そのままPUTする」タイプのデプロイスクリプトを書いている場合は要注意です。接続情報が欠落したまま再デプロイし、インデクサーやスキルセットが動かなくなる可能性があります。
日本語ドキュメントと英語ドキュメントの反映差
Microsoft Learnの日本語ページは便利ですが、最新APIバージョンの反映に差が出る場合があります。実務で最新バージョンを確認する場合は、英語版のAPIバージョン一覧、各APIリファレンスのバージョンセレクター、OpenAPI仕様を優先して確認するのが安全です。英語版では2026-05-01-previewが最新プレビューとして掲載されていますが、確認時点の日本語版では最新プレビューの表示が異なる場合があります。(Microsoft Learn)
開発者向けの移行チェックリスト
移行前に、次のチェックリストを使って影響範囲を洗い出してください。
| チェック項目 | 確認方法 |
|---|---|
| REST APIを直接呼んでいる箇所 | api-version=でリポジトリ検索 |
| SDKのREST API対応 | SDKの変更ログ、パッケージバージョンを確認 |
| プレビューAPI依存 | previewを含むバージョン指定を検索 |
| GenAI Prompt skill | 削除済みプロパティが残っていないか確認 |
| エージェント型検索 | messages、retrieveKnowledge、旧ナレッジエージェント名を検索 |
| 課金設定 | semanticSearchとknowledgeRetrievalの関係を確認 |
| CORS | 許可オリジン、ブラウザー直呼び出し、APIキー露出を確認 |
| 権限付きデータ | SharePoint、Blob、OneLake、Purviewラベルの挙動を検証 |
| 継続トークン | 古いAPIの継続トークンを新APIへ再送していないか確認 |
| 本番展開 | 検証環境、段階リリース、ロールバック手順を用意 |
特にSDK利用時は、REST APIのapi-versionを直接書いていなくても影響を受けます。PythonやJavaScript SDKでエージェント型検索を使っている場合、2026-05-01-previewではretrieveクライアント名がKnowledgeBaseRetrievalClientへ変更され、retrieveKnowledge(...)がretrieve(...)に置き換わる点も案内されています。(Microsoft Learn)
本番展開で失敗しやすいポイント
Azure REST APIのバージョン更新でよくある失敗は、「新しいバージョンに変えれば新機能が使える」と考えてしまうことです。実際には、機能の種類によって必要な確認が異なります。
たとえば、通常の検索APIであればapi-versionの変更と回帰テストで済むことがあります。一方、ナレッジベース、エージェント型検索、スキルセット、CORS、課金同意が絡む場合は、レスポンス形式・設定スキーマ・管理API・セキュリティ要件まで確認が必要です。
本番展開前には、最低でも次の順序で進めるのが現実的です。
- 現行バージョンのAPI呼び出しログを取得する
- 検証環境で
2026-04-01へ切り替える - 既存機能の検索結果、レスポンスJSON、エラー率を比較する
- プレビュー機能が必要な箇所だけ
2026-05-01-previewを使う - 本番では機能フラグや環境変数でAPIバージョンを切り替えられるようにする
- 切り戻し時に古いナレッジベースやナレッジソースを参照できる状態を残す
エージェント型検索の移行では、既存オブジェクトを上書きするのではなく、新しい一意の名前を持つオブジェクトを作成し、テスト後に古いバージョンを削除する流れが推奨されています。(Microsoft Learn)
まとめ：まずはAPIバージョンの棚卸しから始める
Azure REST APIでAzure AI Searchを利用しているチームは、まずapi-versionの棚卸しから始めてください。本番では最新安定版の2026-04-01を基準にし、2026-05-01-previewは新しいナレッジソース、CORS、取得制御、SharePoint更新、APIM連携などを検証する用途に分けるのが安全です。
管理者はknowledgeRetrieval、CORS、管理キー取得、権限付きデータの扱いを確認し、開発者はSDKバージョン、レスポンス形式、スキルセット定義、エージェント型検索のリクエスト形状を確認しましょう。特にRAGや社内Copilot型アプリでは、検索APIの更新が回答品質・根拠表示・課金・セキュリティに直結します。
次に取るべき行動は、リポジトリと運用スクリプトからapi-versionとpreview指定を洗い出し、2026-04-01へ移行できる部分、2026-05-01-previewを検証すべき部分、古いプレビューから段階移行すべき部分を分けることです。これだけで、移行時の手戻りを大きく減らせます。
コメント