MENU

Azure SDK documentation update: Search 26-04-01の変更点と移行チェックリスト

Azure

Azure SDK documentation update: Search 26-04-01でまず確認すべき結論は、Azure AI Search向けPython SDKの既定APIバージョンが2026-04-01へ移り、Knowledge Base関連の機能追加と、権限まわり・モデル変換まわりのAPI整理が入っている点です。特にazure-search-documentsを更新する開発者、api_versionを明示せずに使っているアプリ、RAGやKnowledge Base関連機能を試しているチームは、依存関係を上げる前に影響範囲を確認してください。指定されたPRはclosed表示のため、実運用ではPR単体ではなく、公開パッケージ、mainブランチ、CHANGELOGを合わせて確認するのが安全です。(GitHub)

目次

Azure SDK documentation update: Search 26-04-01の要点

今回の更新は、単なるドキュメント文言の差し替えではなく、Azure AI Search向けSDKを2026-04-01 APIに合わせて整理する流れとして見るべき内容です。Python SDKでは、azure-search-documentsの既定APIバージョンが2026-04-01になっていることが確認できます。(GitHub)

確認項目変更・確認ポイント対応の優先度
APIバージョンSDK側の既定APIバージョンが2026-04-01に更新高
Pythonパッケージazure-search-documents 12.0.0が公開され、Python 3.9以上が対象高
Knowledge BaseKnowledgeBaseRetrievalClientやKnowledge Source関連モデルが追加中〜高
権限まわりingestionPermissionOptions系はGAスコープから外れる方向で整理高
モデル変換モデルのserialize() / deserialize()削除に注意中〜高
既存検索処理キーワード検索、ベクトル検索、ハイブリッド検索の回帰テストが必要中

実務上の判断としては、「SDKを更新しても検索処理はそのまま動くはず」と考えるのではなく、「APIバージョン、モデル、列挙値、シリアライズ方法が変わる可能性がある」と捉えて、ステージング環境で確認してから本番へ反映するのが安全です。

何が変わったのか

既定APIバージョンが2026-04-01へ更新

PRの差分では、Search SDKのメタデータやクライアント設定におけるAPIバージョンが2025-11-01-previewから2026-04-01へ変更されています。mainブランチ上の設定でも、既定値として2026-04-01が使われています。(GitHub)

影響が出やすいのは、次のようなコードです。

from azure.core.credentials import AzureKeyCredential
from azure.search.documents import SearchClient

client = SearchClient(
    endpoint=endpoint,
    index_name=index_name,
    credential=AzureKeyCredential(key),
)

このようにapi_versionを明示していない場合、SDKの更新によって利用されるAPIバージョンが変わる可能性があります。安定運用を重視するなら、更新作業のタイミングで明示的に指定しておくと、意図しない挙動変更を避けやすくなります。

from azure.core.credentials import AzureKeyCredential
from azure.search.documents import SearchClient

client = SearchClient(
    endpoint=endpoint,
    index_name=index_name,
    credential=AzureKeyCredential(key),
    api_version="2026-04-01",
)

ただし、古いAPIバージョンを固定し続けることが常に正解ではありません。新しい機能を使う場合や、SDK側の型定義とサービス仕様を合わせたい場合は、2026-04-01への移行を前提にテスト計画を組むべきです。

azure-search-documents 12.0.0の公開状況も確認する

PyPIでは、azure-search-documentsの12.0.0が公開されており、Python 3.9以上が対象として示されています。公開パッケージのリリース履歴では、12.0.0が2026-04-01のリリースとして確認できます。(PyPI)

依存関係を確認する場合は、まず現在のインストール状態を見ます。

python -m pip show azure-search-documents

バージョンだけを確認したい場合は、次のように実行できます。

python - <<'PY'
import importlib.metadata as metadata
print(metadata.version("azure-search-documents"))
PY

開発環境と本番環境でバージョンが違うと、「手元では動くが本番では失敗する」原因になります。Dockerイメージ、CI/CD、サーバー上の仮想環境、FunctionsやApp Serviceのデプロイパッケージまで含めて確認してください。

Knowledge Base関連の機能追加に注目

今回の更新で重要なのは、Knowledge Base関連の機能がSDK上で扱いやすくなっている点です。公開パッケージの説明では、KnowledgeBaseRetrievalClientや複数のKnowledge Source関連モデル、KnowledgeBaseActivityRecordType.MODEL_WEB_SUMMARIZATIONなどの追加が確認できます。(PyPI)

特に影響を受けるのは、Azure AI Searchを単なる全文検索としてではなく、RAG、社内ナレッジ検索、エージェント連携、Web要約を含む検索体験に使っているチームです。

利用シーン確認すべきこと
RAGアプリを構築しているKnowledge Base関連クライアントやモデルを利用できるか確認
社内文書検索を運用しているKnowledge Sourceの種類と同期状態の扱いを確認
活動ログや監査ログを処理しているMODEL_WEB_SUMMARIZATIONなど新しい活動種別を想定
独自ラッパーを作っている新しいモデルを隠蔽せず、将来の拡張に耐える設計にする

注意したいのは、列挙値を固定的に扱っているコードです。たとえば、活動種別をif文やmatch文で分岐している場合、新しい値が入ったときに例外扱いになったり、ログが欠落したりする可能性があります。

activity_type = record.activity_type

if activity_type == "modelWebSummarization":
    # Web要約系の活動としてログやメトリクスを記録
    handle_web_summarization(record)
else:
    # 未知の値でも落とさず、少なくとも記録する
    handle_generic_activity(record)

実務では、「知らない活動種別はエラーにする」よりも、「未知の値として記録し、後から分類できるようにする」ほうが運用に向いています。クラウドサービスのSDKでは、新しい列挙値が追加されることがあるためです。

ingestionPermissionOptionsまわりは使う前提を外す

Azure REST API仕様側のPRでは、2026-04-01 GAスコープに対する修正として、KnowledgeSourceIngestionParametersからingestionPermissionOptionsを削除し、KnowledgeBaseActivityRecordTypeにmodelWebSummarizationを追加する内容が示されています。説明では、GAではクエリ側のx-ms-query-source-authorizationをサポートしないため、取り込み権限オプションを公開すべきではないという整理がされています。(GitHub)

Python SDKの再生成PRでも、KnowledgeSourceIngestionPermissionOption enumとKnowledgeSourceIngestionParameters.ingestion_permission_optionsの削除、MODEL_WEB_SUMMARIZATIONの追加が変更点として挙げられています。(GitHub)

まずは、コードベースに該当する文字列がないか確認してください。

rg "ingestion_permission_options|ingestionPermissionOptions|KnowledgeSourceIngestionPermissionOption"

rgがない環境では、grepでも確認できます。

grep -R "ingestion_permission_options\|ingestionPermissionOptions\|KnowledgeSourceIngestionPermissionOption" .

該当コードが見つかった場合は、単純な名称変更ではなく「その機能を前提にした設計自体を見直す」必要があります。特定ソースだけを権限付きで取り込む、またはクエリ時に権限情報を渡して絞り込むような設計をしていた場合は、サービス側のGA仕様と整合する代替設計を確認してください。

モデルのserializeとdeserialize削除に注意

azure-search-documents 12.0.0のリリース情報では、モデルからserialize()とdeserialize()が削除され、代わりにas_dict()とモデルコンストラクターを使う旨が示されています。(PyPI)

既存コードで次のように書いている場合は、更新後に失敗する可能性があります。

payload = search_index.serialize()

移行後は、次のようにas_dict()を使う形へ変更します。

payload = search_index.as_dict()

逆に、辞書からモデルを復元する処理では、deserialize()の代わりにモデルのコンストラクターを使う形へ寄せます。

from azure.search.documents.indexes.models import SearchIndex

index = SearchIndex(saved_index_data)

この変更は、検索処理そのものよりも、設定管理やテストコードで影響が出やすいです。たとえば、インデックス定義をJSONとして保存している、CIでスキーマ差分を比較している、管理画面からインデックス設定を出力している、といったケースでは必ず確認してください。

影響を受ける人と対応優先度

今回のAzure SDK documentation update: Search 26-04-01で、全ユーザーが同じレベルの対応を求められるわけではありません。次の表を目安に、優先度を判断してください。

対象者・システム影響優先度
api_versionを明示せずにSearchClientを使っているSDK更新でAPIバージョンが変わる可能性高
Knowledge BaseやKnowledge Sourceを使っている新モデル追加、権限まわり削除の影響を受けやすい高
ingestion_permission_optionsを使っているそのままでは使えない可能性高
モデルのserialize() / deserialize()を使っているSDK更新後にコード修正が必要高
キーワード検索だけを使っている影響は限定的だが回帰テストは必要中
ベクトル検索・ハイブリッド検索を使っているクエリ条件、型、結果処理の確認が必要中〜高
SDKラッパーや共通ライブラリを提供している利用者全体へ影響が波及する高

最も危険なのは、「アプリ本体では何も変更していないのに、依存関係の更新でSDKの既定動作が変わる」パターンです。特に、requirements.txtやpyproject.tomlでバージョン範囲を広く指定している場合は注意してください。

azure-search-documents>=11.0.0

このような指定では、環境再構築やCI実行時に新しいメジャー・マイナー・パッチへ上がる可能性があります。安定運用中の本番システムでは、次のようにバージョンを固定し、検証後に段階的に上げるほうが安全です。

azure-search-documents==12.0.0

ただし、固定したまま放置すると、セキュリティ修正や仕様追従が遅れます。固定は「止めるため」ではなく、「検証して計画的に上げるため」の手段として使ってください。

移行前に確認するチェックリスト

現在のSDKバージョンとPythonバージョンを確認する

azure-search-documents 12.0.0はPython 3.9以上が対象です。古い実行環境を使っている場合は、SDK更新より先にPythonランタイムの確認が必要です。(PyPI)

python --version
python -m pip show azure-search-documents

CI/CDで複数のPythonバージョンを使っている場合は、ローカルだけでなく、テスト環境や本番ビルド環境でも同じ確認を行ってください。

api_versionを明示する

SDKの既定APIバージョンに任せると、将来のSDK更新時にも同じ問題が起きます。検索処理が重要なアプリでは、クライアント生成時にapi_versionを明示しておくと、変更点を管理しやすくなります。

client = SearchClient(
    endpoint=endpoint,
    index_name=index_name,
    credential=AzureKeyCredential(key),
    api_version="2026-04-01",
)

インデックス管理側のクライアントでも、同じ考え方で確認します。

from azure.search.documents.indexes import SearchIndexClient

index_client = SearchIndexClient(
    endpoint=endpoint,
    credential=AzureKeyCredential(key),
    api_version="2026-04-01",
)

本番では旧APIバージョンを維持し、検証環境だけ2026-04-01にする方法もあります。その場合は、環境変数で明示的に切り替えると管理しやすくなります。

import os

api_version = os.getenv("AZURE_SEARCH_API_VERSION", "2026-04-01")

削除・変更されたAPIを検索する

移行時は、まず文字列検索で影響箇所を洗い出します。

rg "serialize\(|deserialize\(|ingestion_permission_options|ingestionPermissionOptions|KnowledgeSourceIngestionPermissionOption"

該当箇所が多い場合は、先に共通処理を修正してください。各画面や各バッチに直接SDKのモデル変換処理を書いていると、修正漏れが起きやすくなります。

回帰テストで見るべき項目を決める

SDK更新後のテストでは、単に「検索結果が返るか」だけでは不十分です。検索アプリでは、結果の順位、フィルター、ファセット、ハイライト、ベクトル検索、ハイブリッド検索の挙動がユーザー体験に直結します。

テスト項目確認内容
基本検索キーワード検索で期待する件数・上位結果が返るか
フィルター$filter条件が従来どおり効くか
ソート並び順が変わっていないか
ファセット集計値やカテゴリ件数が想定どおりか
ベクトル検索類似度検索の結果が大きく変わっていないか
ハイブリッド検索キーワードとベクトルの組み合わせ結果を確認
インデクサーデータソース、スキルセット、スケジュールが動くか
Knowledge Base取得結果、活動ログ、同期状態を確認

特にベクトル検索やハイブリッド検索は、検索結果の「正しさ」を単純な件数だけで判断しにくい領域です。代表的な検索語を10〜20個ほど用意し、旧環境と新環境で上位結果を比較するのが現実的です。

設定・運用で失敗しやすいポイント

PRがclosedだからといって、変更が不要とは限らない

指定されたPR #45434はclosed表示です。一方で、mainブランチ上では2026-04-01が既定APIバージョンとして確認でき、PyPIでもazure-search-documents 12.0.0が公開されています。つまり、PR単体の状態だけで「反映されていない」と判断するのは危険です。(GitHub)

実務では、次の3つをセットで確認してください。

確認先見るべき内容
GitHub PRどのような変更が検討・実装されたか
mainブランチ現在のソースコード上の最終状態
PyPI / CHANGELOG利用者がインストールできる公開版の内容

この3点が一致していない時期は、SDK更新のタイミングとして慎重に扱うべきです。

ドキュメントと実際のインストール済みSDKがずれる

クラウドSDKでは、ドキュメント、GitHubのmainブランチ、PyPIの公開パッケージ、社内環境に入っているSDKが完全に同時更新されるとは限りません。ドキュメントに新機能が載っていても、実行環境のSDKが古ければそのクラスやプロパティは使えません。

エラー例としては、次のようなものが考えられます。

ImportError: cannot import name 'KnowledgeBaseRetrievalClient'
AttributeError: 'SearchIndex' object has no attribute 'serialize'
TypeError: got an unexpected keyword argument 'ingestion_permission_options'

このようなエラーが出た場合は、コードだけを疑うのではなく、SDKのバージョン、APIバージョン、ドキュメントの対象バージョンを合わせて確認してください。

権限まわりの仕様をプレビュー機能前提で設計しない

ingestionPermissionOptionsの削除は、単なるプロパティ削除以上の意味があります。REST API仕様側では、GAスコープとの整合性を取るために、取り込み権限まわりの表面を公開しない整理がされています。(GitHub)

プレビュー段階の機能を使って権限設計を組んでいた場合、GA版でそのまま使えるとは限りません。ユーザーや部署ごとのアクセス制御を検索結果に反映したい場合は、インデックス設計、フィルター用フィールド、アプリ側の認可処理、Microsoft Entra ID連携など、複数の選択肢を改めて整理する必要があります。

実務での判断基準：すぐ上げるか、慎重に進めるか

SDK更新の判断は、「新しいから上げる」「怖いから上げない」ではなく、機能要件とリスクで分けるのが現実的です。

状況推奨判断
Knowledge Base関連の新機能を使いたいステージングで早めに検証し、移行計画を作る
既存の検索アプリが安定稼働しているバージョン固定後、回帰テストを通して段階的に更新
api_versionを指定していないまず明示指定し、SDK更新の影響を切り分ける
serialize() / deserialize()を多用している先に変換処理を共通化し、修正範囲を小さくする
権限まわりのプレビュー機能を使っている仕様変更を前提に設計を見直す
SDKラッパーを社内提供している利用チーム向けの移行ガイドを用意する

おすすめの進め方は、最初に「バージョン確認」「文字列検索」「代表クエリの回帰テスト」を行い、その結果で移行規模を判断することです。いきなり全コードを読み直すよりも、影響のある箇所を短時間で絞り込めます。

移行作業の実践手順

まず依存関係を固定する

本番環境で意図しない更新が起きないように、現在のバージョンを固定します。

python -m pip freeze | grep azure-search-documents

requirements.txtやpyproject.tomlに現在のバージョンを明記し、検証用ブランチで更新します。

python -m pip install --upgrade azure-search-documents

更新後は、必ずバージョンを再確認します。

python -m pip show azure-search-documents

影響箇所を機械的に洗い出す

次に、変更の影響を受けやすい文字列を検索します。

rg "api_version|serialize\(|deserialize\(|ingestion_permission_options|KnowledgeBase|KnowledgeSource"

検索結果を、次の3種類に分けると作業しやすくなります。

分類例対応
すぐ修正が必要serialize()、deserialize()、ingestion_permission_options新しいAPIに置き換える
設定確認が必要api_version未指定のクライアント生成明示指定する
テスト重点箇所KnowledgeBase、ベクトル検索、ハイブリッド検索回帰テストを追加する

検索結果の品質を比較する

SDK更新では、例外が出ないだけでは合格にしないほうが安全です。検索サービスでは、検索結果の順位や絞り込みが変わると、ユーザーにとっては大きな品質低下になります。

比較用に、次のようなテストデータを用意します。

テストクエリ確認観点
よく検索される商品名・文書名上位結果が変わりすぎていないか
部署名やカテゴリ名フィルターとファセットが正しいか
表記ゆれのある単語検索漏れが増えていないか
長い自然文クエリベクトル検索やハイブリッド検索の品質
権限が必要な文書表示してはいけない結果が出ないか

この比較は、できれば自動テストに組み込んでください。少なくとも、リリース前チェックリストとして毎回同じクエリを確認できる状態にしておくと、SDK更新時の不安を減らせます。

まとめ：次にやるべきこと

Azure SDK documentation update: Search 26-04-01では、Azure AI Search向けSDKの2026-04-01 API対応が中心です。特に、既定APIバージョンの変更、Knowledge Base関連機能の追加、ingestionPermissionOptionsまわりの整理、serialize() / deserialize()削除は、実装に直接影響する可能性があります。(GitHub)

最初に行うべき作業は、次の3つです。

  • 現在のazure-search-documentsのバージョンとPythonバージョンを確認する
  • api_versionを明示し、SDK更新による意図しない変更を防ぐ
  • ingestion_permission_options、serialize()、deserialize()、Knowledge Base関連の利用箇所を検索する

この3点を確認すれば、今回の更新が自社システムに与える影響をかなり絞り込めます。そのうえで、ステージング環境で代表クエリとインデクサー、Knowledge Base関連処理の回帰テストを実施し、問題がなければ段階的に本番へ反映してください。

Azure
移行 APIバージョン Azure AI Search Azure SDK Python SDK

この記事を書いた人

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

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

関連記事

コメント

コメントする

目次