Azure REST APIのAzure AI Search管理APIバージョン整理｜2026年5月更新の影響と移行注意点

Azure REST APIでAzure AI Searchを管理している場合、今回まず確認すべき結論はシンプルです。本番運用の基準は最新の安定版である 2025-05-01、新機能の検証は最新プレビューの 2026-03-01-preview を検証環境で扱う、という切り分けが重要です。特に、エージェント検索、RAG、社内Copilot風アプリの検索基盤としてAzure AI Searchを使っている組織では、api-version の指定、課金同意、CMK暗号化、IaCテンプレートのバージョン固定を見直す必要があります。Microsoft Learnの管理REST APIバージョン一覧では、安定版とプレビュー版が明確に分けて掲載されています。(Microsoft Learn)

Azure REST APIのAI検索更新で何が変わるのか

今回の「API Versions of Search Management REST APIs – Azure AI Search」は、検索クエリそのものの書き方を説明するページではありません。Azure AI Searchサービスを作成・更新・削除したり、SKU、認証、ネットワーク、キー、プライベートリンクなどを管理したりするSearch Management REST APIのバージョン一覧です。

実務上のポイントは、次の3つです。

確認ポイント	内容	実務での判断
最新安定版	`2025-05-01`	本番のARM/Bicep/REST運用では基本候補
最新プレビュー版	`2026-03-01-preview`	新機能検証向け。いきなり本番標準にしない
影響範囲	Azure AI Searchの管理操作	検索クエリやインデックス操作のデータプレーンAPIとは分けて確認する

Microsoft Learnでは、Search Management REST APIの最新安定版として 2025-05-01、最新プレビュー版として 2026-03-01-preview が示されています。また、プレビューAPIは新機能のテストやフィードバック収集のために提供され、運用環境のワークロードには推奨されないと説明されています。(Microsoft Learn)

Search Management REST APIは「検索の中身」ではなく「サービス管理」を扱う

Azure AI Searchには、大きく分けて2種類のREST APIがあります。

種類	主な用途	エンドポイントの考え方	例
Search Management REST API	サービス作成、更新、削除、キー管理、SKU、ネットワーク、認証設定	Azure Resource Manager経由	`https://management.azure.com/.../Microsoft.Search/searchServices/...`
Search Service REST API	インデックス、ドキュメント検索、インデクサー、スキルセットなど	検索サービスのエンドポイント経由	`https://{search-service}.search.windows.net/...`

混同しやすいのは、どちらもAzure AI Searchに関係し、どちらも api-version を使う点です。しかし、管理プレーンのバージョンを上げても、検索クエリのレスポンス形式が自動的に変わるわけではありません。Microsoftの新着情報でも、Search Management 2026-03-01-preview で追加された knowledgeRetrieval プロパティは、Search Service側のデータプレーンAPIバージョンには影響しないと説明されています。(Microsoft Learn)

一方で、課金、暗号化、ネットワーク、認証のような運用設定は管理API側で扱います。つまり、アプリ開発者だけでなく、Azure管理者、SRE、セキュリティ担当、IaCテンプレートを管理するチームも確認対象になります。

公式情報で確認できるSearch Management REST APIのバージョン

2026年5月末時点の公式情報で確認できるSearch Management REST APIのバージョンは次のとおりです。

区分	APIバージョン	位置付け
安定版	`2025-05-01`	最新の安定版
安定版	`2023-11-01`	過去の安定版
安定版	`2022-09-01`	過去の安定版
安定版	`2020-08-01`	過去の安定版
安定版	`2020-03-13`	過去の安定版
安定版	`2015-08-19`	過去の安定版
プレビュー版	`2026-03-01-preview`	最新のプレビュー版
プレビュー版	`2025-02-01-preview`	過去のプレビュー版
プレビュー版	`2024-06-01-preview`	過去のプレビュー版
プレビュー版	`2024-03-01-preview`	過去のプレビュー版
プレビュー版	`2021-04-01-preview`	過去のプレビュー版
プレビュー版	`2020-08-01-preview`	過去のプレビュー版
プレビュー版	`2019-10-01-preview`	過去のプレビュー版

この一覧で重要なのは、「最新＝必ず採用」ではないことです。安定運用では 2025-05-01 を基準にし、2026-03-01-preview は必要なプレビュー機能がある場合だけ、検証環境から使うのが安全です。Microsoft Learnでも、REST APIドキュメントはバージョン管理されており、APIリファレンスページのバージョンセレクターで対象バージョンを選べると説明されています。(Microsoft Learn)

今回の更新で特に見るべき変更点

`knowledgeRetrieval`でエージェント検索の課金同意を分けて管理する

エージェント検索を利用している場合、特に注意したいのが knowledgeRetrieval です。

Search Service REST API 2026-04-01 以降では、セマンティックランカーとエージェンティックリトリーバルの課金承認が分離されます。semanticSearch とは別に、knowledgeRetrieval で有料のエージェント検索使用を制御する仕組みです。Microsoftのドキュメントでは、Search Management REST API 2026-03-01-preview 以降で knowledgeRetrieval プロパティを設定すると説明されています。(Microsoft Learn)

実務では、次のようなケースが要注意です。

状況	確認すべきこと
既に `semanticSearch=standard` を使っている	エージェント検索の有料利用まで同意したつもりになっていないか確認
Search Service APIを `2026-04-01` 以降へ移行する	事前に `knowledgeRetrieval=standard` が必要か判断
ポータル中心で運用している	ポータルの表示だけで課金分離を判断しない
RAGや社内AIエージェントでAzure AI Searchを使っている	検索品質だけでなく、課金設定もリリース条件に入れる

有料のエージェント検索を継続的に利用する場合のPATCH例は次のとおりです。実行には対象検索サービスへの適切な権限とMicrosoft Entra IDによる認証が必要です。Microsoft Learnでは、検索サービスに対する所有者または共同作成者のアクセス許可が前提条件として示されています。(Microsoft Learn)

PATCH https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Search/searchServices/{searchServiceName}?api-version=2026-03-01-preview
Content-Type: application/json
Authorization: Bearer {access-token}

{
  "properties": {
    "knowledgeRetrieval": "standard"
  }
}

無料プランに戻す場合は、standard ではなく free を指定します。ただし、実際にどちらを選ぶべきかは、利用リージョン、価格レベル、月間リクエスト量、社内の課金承認フローに合わせて判断してください。

サービスレベルCMKは「後から既存オブジェクトに足せる」と考えない

セキュリティ面では、Search Management 2026-03-01-preview に関連する変更として、サービスレベルのカスタマーマネージドキー、つまりCMKの扱いが重要です。

Microsoftの新着情報では、encryptionWithCmk 構成内の新しい serviceLevelEncryptionKey プロパティにより、検索サービス内で新しく作成されるオブジェクトに対して、既定でCMKを有効化できると説明されています。一方で、暗号化は作成時に設定され、既存オブジェクトへ後から追加することはできない点も明記されています。(Microsoft Learn)

これは、セキュリティ要件が厳しい環境では大きな判断材料になります。

判断ポイント	実務上の注意
新規検索サービスを作る	CMKを使うなら、作成前に設計に入れる
既存サービスを運用中	既存オブジェクトに後付けできる前提で計画しない
監査対応がある	キー管理、ローテーション、Key Vault権限をセットで確認
IaCで展開する	`encryptionWithCmk` 周辺を環境ごとに分岐させるか決める

「あとでセキュリティ設定を足せばよい」と考えると、再作成やデータ移行が必要になる可能性があります。CMK要件があるプロジェクトでは、検索サービス作成前のアーキテクチャレビューに含めるべきです。

`Offerings` APIの形状には新規依存しない

2026-03-01-preview のOpenAPI仕様には、リージョンごとの機能やSKU提供状況を列挙する Offerings_List が含まれています。ただし仕様上、このAPIは非ARMリソースコレクションを返し、次のプレビューでアクション形式のAPIに置き換えられる予定であるため、現行のレスポンス形状に新たな依存を作らないよう注意書きがあります。(GitHub)

そのため、SKUや機能提供状況を自動判定する社内ツールを作る場合は、次のように扱うのが安全です。

用途	推奨判断
検証用の一時スクリプト	利用可。ただしレスポンス形状変更を前提にする
本番のデプロイ判定	強く依存しない
CI/CDの必須ゲート	変更時に壊れない抽象化層を挟む
長期運用する管理ツール	次プレビュー以降の仕様変更を追跡する

管理者と開発者が確認すべき設定

Azure REST APIのAPIバージョン更新で事故が起きやすいのは、コード本体よりも、周辺の自動化スクリプトやIaCです。まずは次の場所を確認してください。

確認場所	見るべきポイント	失敗しやすい例
ARMテンプレート、Bicep	`Microsoft.Search/searchServices@...` のバージョン	古いプレビュー版のまま放置
Terraformやデプロイスクリプト	内部で使うAzure APIバージョンやプロバイダー更新	provider更新で挙動が変わる
PowerShell、Azure CLI、curl	`api-version=` の直書き	環境ごとに違う値が散在
CI/CD	検証環境と本番環境のAPIバージョン差	検証だけプレビュー、本番で未検証
セキュリティ設定	`disableLocalAuth`、`authOptions`、CMK、Private Link	認証方式変更で既存アプリが失敗
課金設定	`semanticSearch` と `knowledgeRetrieval`	エージェント検索の課金同意を見落とす
キー管理	Admin keys、Query keysの取得方法	データプレーンのGET応答から秘密情報を読む前提

なお、2024年3月以降、GET Skillset、GET Index、GET Indexerは応答でキーや接続プロパティを返さなくなっており、管理者キーまたはクエリAPIキーが必要な場合はSearch Management REST APIを使う必要があります。接続文字列などの機密情報をGET応答から読む設計は、今後の移行でも壊れやすいので見直すべきです。(Microsoft Learn)

APIバージョン移行の実務手順

まず`api-version`の棚卸しをする

最初にやるべきことは、現行システムのどこでAzure AI SearchのREST APIバージョンを指定しているかを洗い出すことです。

PowerShellなら、リポジトリ直下で次のように検索できます。

Get-ChildItem -Recurse -File |
  Select-String -Pattern "api-version=|Microsoft.Search/searchServices@"

ripgrepを使える環境なら、次のコマンドでも十分です。

rg "api-version=|Microsoft.Search/searchServices@"

この段階では、見つかった箇所をすぐ置換しないでください。管理プレーンとデータプレーンを混ぜて一括置換すると、別のAPIに誤ったバージョンを指定してしまう可能性があります。

管理プレーンとデータプレーンを分類する

見つかったAPI呼び出しは、次の基準で分類します。

分類	URLの特徴	代表的な処理
管理プレーン	`management.azure.com` を使う	サービス作成、更新、削除、SKU、キー、ネットワーク
データプレーン	`{service}.search.windows.net` を使う	インデックス、検索、インデクサー、スキルセット

Microsoftの移行ガイドでも、最新REST APIとしてデータプレーンとコントロールプレーンを分けて整理しており、コントロールプレーンの安定版は 2025-05-01、プレビューは 2026-03-01-preview とされています。(Microsoft Learn)

本番と検証で採用バージョンを分ける

APIバージョンの選び方は、次のように判断すると迷いにくくなります。

目的	推奨する考え方
本番で安定運用したい	Search Management REST API `2025-05-01` を優先
エージェント検索の課金設定を検証したい	`2026-03-01-preview` を検証環境で使用
サービスレベルCMKを設計したい	新規サービス作成前に `2026-03-01-preview` の仕様を確認
既存の古いプレビューを使っている	一足飛びではなく、差分を確認しながら移行
Azure SDKを使っている	SDKパッケージが対象とするREST APIバージョンを変更ログで確認

Microsoftの移行ガイドでは、APIバージョンを連続してアップグレードし、最新バージョンに到達するまで各バージョンを操作することが推奨されています。また、Azure SDKを使う場合は、各パッケージが対象とするREST APIバージョンを変更ログで確認する必要があります。(Microsoft Learn)

スモークテストは「作成」より先に「取得」と「差分確認」から始める

いきなり本番相当の作成・更新APIを叩くのではなく、まずは読み取り系のAPIでレスポンス差分を確認します。

おすすめの順序は次のとおりです。

| 順序 | テスト内容 | 確認すること |
| -: | ———————– | ——————- |
| 1 | 対象サービスのGET | 既存レスポンスのパースが壊れないか |
| 2 | タグだけのPATCH | 更新処理と権限が通るか |
| 3 | 非本番環境でSKUやレプリカ数変更 | 長時間操作やロールバック手順を確認 |
| 4 | knowledgeRetrieval 設定 | 課金同意の意図どおりに設定されるか |
| 5 | IaCで再デプロイ | 差分なしデプロイが差分ありにならないか |

API応答に未知のプロパティが増えたときに失敗するクライアントは、アップグレードで壊れやすくなります。Microsoftの移行ガイドでも、認識できないプロパティがAPI応答で返された場合に失敗するコードは注意点として挙げられており、ベストプラクティスとして未知のプロパティを無視する実装が示されています。(Microsoft Learn)

展開時に失敗しやすいポイント

プレビュー版を「最新だから安全」と判断する

2026-03-01-preview は最新ですが、安定版ではありません。プレビューは新機能の検証、フィードバック収集、問題の発見・修正を目的としており、運用環境のワークロードには推奨されていません。(Microsoft Learn)

本番で使う場合は、少なくとも次の条件を満たしてからにしてください。

条件	理由
プレビュー機能が本当に必要	安定版で足りるならプレビューを避ける
仕様変更時の改修余力がある	プレビューは将来変更される可能性がある
障害時の切り戻し手順がある	APIバージョンだけ戻しても設定差分が残る場合がある
課金・セキュリティレビュー済み	`knowledgeRetrieval` やCMKは運用影響が大きい

`api-version`をリポジトリ内で直書きし続ける

REST API呼び出しのたびに api-version=2025-05-01 のように直書きしていると、移行時に漏れが出ます。環境変数、共通設定ファイル、ラッパー関数などに寄せておくと、次回以降の更新が楽になります。

例として、シェルスクリプトでは次のように共通化できます。

AZURE_SEARCH_MGMT_API_VERSION="2025-05-01"

curl -X GET \
  "https://management.azure.com/subscriptions/${SUBSCRIPTION_ID}/resourceGroups/${RESOURCE_GROUP}/providers/Microsoft.Search/searchServices/${SEARCH_SERVICE}?api-version=${AZURE_SEARCH_MGMT_API_VERSION}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"

プレビュー検証だけ別バージョンにする場合も、コード中に直接書くのではなく、環境ごとに切り替えられる形にしておくと安全です。

ポータルの設定だけで課金分離を判断する

エージェント検索の課金分離は、ポータル操作だけ見ていると判断を誤る可能性があります。Microsoftのドキュメントでは、Search Service REST API 2026-04-01 以降では knowledgeRetrieval がエージェント検索課金を semanticSearch とは別に管理すると説明されています。一方、2025-11-01-preview 以前では semanticSearch がセマンティックランカーと有料エージェント検索の両方の同意を制御し、knowledgeRetrieval は無視されます。(Microsoft Learn)

移行前には、次の確認を入れてください。

確認項目	確認方法
現在のSearch Service APIバージョン	アプリ、SDK、REST呼び出しを確認
`semanticSearch` の現在値	管理APIまたはIaC定義を確認
`knowledgeRetrieval` の現在値	`2026-03-01-preview`以降の管理APIで確認
有料利用の社内承認	コスト管理・予算アラートと合わせて確認

管理者・開発者別のアクション

Azure管理者がやること

Azure管理者は、サービス構成とガバナンスを中心に確認します。

やること	具体例
管理APIバージョンの棚卸し	ARM/Bicep/スクリプトの `api-version` を確認
本番標準バージョンの決定	原則 `2025-05-01`、必要時のみプレビュー
課金設定の確認	`semanticSearch` と `knowledgeRetrieval` の扱いを整理
セキュリティ設定の確認	CMK、Private Link、Public Network Access、ローカル認証
権限の確認	更新APIを実行するサービスプリンシパルのRBACを確認
監査ログの確認	変更者、変更日時、設定差分を追跡可能にする

開発者がやること

開発者は、アプリケーションコードとSDK依存関係を中心に確認します。

やること	具体例
REST呼び出しの分類	管理APIと検索APIを分ける
直書きバージョンの整理	共通設定や環境変数に移す
SDKの変更ログ確認	利用パッケージが対象とするREST APIを確認
レスポンスパースの耐性確認	未知のプロパティで失敗しない実装にする
秘密情報の取得方法を見直す	GET応答から接続情報を読む設計をやめる
検証環境で差分テスト	本番データを直接変更しない

次に取るべき行動

今回のAzure REST API更新で、すべての利用者が即座にコードを変更する必要があるとは限りません。ただし、Azure AI SearchをREST APIやIaCで管理している場合は、放置すると次回の機能追加や移行時に影響が大きくなります。

まずは、リポジトリとデプロイパイプラインから api-version を棚卸ししてください。次に、管理プレーンとデータプレーンを分け、本番はSearch Management REST API 2025-05-01 を基準にします。エージェント検索の課金分離やサービスレベルCMKを検証する場合だけ、2026-03-01-preview を検証環境で扱うのが現実的です。

特に、RAGや社内Copilot風アプリでAzure AI Searchを使っているチームは、検索精度だけでなく、課金同意、暗号化、認証、ネットワーク設定までをリリースチェックリストに入れてください。APIバージョン更新は単なるURLパラメーターの変更ではなく、運用設計を見直すタイミングです。

この記事を書いた人

佐藤健司

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

Azure REST APIのAzure AI Search管理APIバージョン整理｜2026年5月更新の影響と移行注意点

Azure REST APIのAI検索更新で何が変わるのか

Search Management REST APIは「検索の中身」ではなく「サービス管理」を扱う

公式情報で確認できるSearch Management REST APIのバージョン

今回の更新で特に見るべき変更点

最新プレビューは`2026-03-01-preview`

`knowledgeRetrieval`でエージェント検索の課金同意を分けて管理する

サービスレベルCMKは「後から既存オブジェクトに足せる」と考えない

`Offerings` APIの形状には新規依存しない

管理者と開発者が確認すべき設定

APIバージョン移行の実務手順

まず`api-version`の棚卸しをする

管理プレーンとデータプレーンを分類する

本番と検証で採用バージョンを分ける

スモークテストは「作成」より先に「取得」と「差分確認」から始める

展開時に失敗しやすいポイント

プレビュー版を「最新だから安全」と判断する

`api-version`をリポジトリ内で直書きし続ける

ポータルの設定だけで課金分離を判断する

管理者・開発者別のアクション

Azure管理者がやること

開発者がやること

次に取るべき行動

この記事を書いた人

コメント

コメントするコメントをキャンセル

Azure REST APIのAzure AI Search管理APIバージョン整理｜2026年5月更新の影響と移行注意点

Azure REST APIのAI検索更新で何が変わるのか

Search Management REST APIは「検索の中身」ではなく「サービス管理」を扱う

公式情報で確認できるSearch Management REST APIのバージョン

今回の更新で特に見るべき変更点

最新プレビューは2026-03-01-preview

knowledgeRetrievalでエージェント検索の課金同意を分けて管理する

サービスレベルCMKは「後から既存オブジェクトに足せる」と考えない

Offerings APIの形状には新規依存しない

管理者と開発者が確認すべき設定

APIバージョン移行の実務手順

まずapi-versionの棚卸しをする

管理プレーンとデータプレーンを分類する

本番と検証で採用バージョンを分ける

スモークテストは「作成」より先に「取得」と「差分確認」から始める

展開時に失敗しやすいポイント

プレビュー版を「最新だから安全」と判断する

api-versionをリポジトリ内で直書きし続ける

ポータルの設定だけで課金分離を判断する

管理者・開発者別のアクション

Azure管理者がやること

開発者がやること

次に取るべき行動

この記事を書いた人

関連記事

コメント

コメントする コメントをキャンセル

最新プレビューは`2026-03-01-preview`

`knowledgeRetrieval`でエージェント検索の課金同意を分けて管理する

`Offerings` APIの形状には新規依存しない

まず`api-version`の棚卸しをする

`api-version`をリポジトリ内で直書きし続ける

コメントするコメントをキャンセル