Azure SDK documentation update: [Search] Add 2026-04-01 GA test coverage and recordings は、Azure AI Search の Python SDK azure-search-documents に関するテスト整備の更新です。結論から言うと、通常のアプリ利用者が今すぐ本番設定を変更する内容ではありません。ただし、azure-search-documents を 12.0.0 系へ上げる予定があるチーム、Azure AI Search のインデックス作成・検索・インデクサー・ナレッジベース機能を使っているチーム、SDKのテスト記録やモックを自社CIで利用しているチームは確認が必要です。該当PRは 2026年5月5日に main へマージされ、2026-04-01 GA 向けのテストスイート更新と playback recordings の更新を目的としています。(GitHub)
Azure SDK documentation updateの要点
今回の更新は、派手な新機能追加というより「2026-04-01 GA の Search SDK が、どの動作をテストで保証しているか」を明確にするための変更です。PRの説明では、以前の main ブランチにあった pytest テスト 95件をレビューし、95件すべてが同等以上の現在のテストに対応しており、既知のカバレッジギャップは 0 とされています。(GitHub)
特に重要なのは、テストが「公開クライアント」と「リソース領域」ごとに再編成された点です。たとえば、SearchClient、SearchIndexClient、SearchIndexerClient、SearchIndexingBufferedSender、ナレッジベース関連のテストが、より用途別に追いやすい構成になっています。SDK利用者にとっては、変更履歴だけでなくテスト名やテスト対象を見ることで、どの操作が想定された使い方なのか判断しやすくなります。(GitHub)
何が変わったのか
| 変更領域 | 内容 | 利用者が確認すべき観点 |
|---|---|---|
| テスト構成 | テストを公開クライアント別・リソース領域別に再編成 | 削除されたように見える旧テストファイルだけを見て「カバレッジが落ちた」と判断しない |
| Unit tests / Live tests | SDK側の動作は unit tests、サービス契約に関わる動作は live tests に整理 | 自社テストでも、SDK内部の変換確認と実サービス確認を分ける |
| Playback recordings | assets.json の録画タグを python/search/azure-search-documents_575b3d2518 に更新 | Azure SDK リポジトリをフォークしてテストする場合は recordings の更新に注意 |
| Hotel fixtures | 静的 JSON ファイルから、決定的に生成される fixture builder へ移行 | 旧 hotel_schema.json などを前提にした独自テストは見直す |
| Buffered sender | 既定値、コンテキストマネージャー、バッチング、コールバック、リトライ、413分割、upload/delete などのテストを強化 | 大量ドキュメント登録や非同期登録を使う場合は回帰テストを追加する |
| ETag関連 | Alias テストでは古い ETag 前提を削除し、Data source ではサービスが強制する条件付き ETag カバレッジを維持 | ETag 挙動を自社テストで固定しすぎていないか確認する |
Playback recordings は、実サービスとのHTTP通信を録画・再生してテストを安定させるための資産です。Azure SDK Tools Test Proxy は、record/playback に対応したテストプロキシで、外部ストア上の recordings を assets.json と組み合わせて扱える仕組みを持っています。(GitHub)
対応が必要な人、様子見でよい人
| 利用状況 | 対応の優先度 | 取るべき行動 |
|---|---|---|
azure-search-documents を 12.0.0 に上げる予定がある | 高 | 破壊的変更、APIバージョン、モデル変換、テスト結果を確認する |
| 11.x 系を固定しており、当面アップグレードしない | 中 | すぐの変更は不要だが、次回アップグレード時の確認項目として記録する |
SearchIndexingBufferedSender、特に async 版を使っている | 高 | 失敗時コールバック、リトライ、413分割、flush 後の結果をテストする |
| 自社CIで Azure SDK の playback recordings を使う | 高 | assets.json の録画タグ更新とテストプロキシ設定を確認する |
| Search の REST API を直接呼び、Python SDKは使っていない | 低 | SDK固有の影響は小さいが、2026-04-01 GA 仕様そのものは別途確認する |
| 11.7.0b 系など beta SDK を使っていた | 高 | 12.0.0 の変更履歴と比較し、削除・名称変更されたモデルやパラメーターを確認する |
2026-04-01 GAとazure-search-documents 12.0.0の関係
PyPI上の azure-search-documents は 12.0.0 が 2026年5月1日に公開されており、Python 3.9 以上が必要とされています。変更履歴では、既定の API version が 2026-04-01 に更新されたことも示されています。(PyPI)
12.0.0 はメジャーバージョン更新です。ナレッジベース関連のクライアントやモデル追加、インデックス・インデクサー関連の拡張、Markdown parsing 関連の enum や設定追加などが含まれます。一方で、モデルの serialize() / deserialize() の扱い、存在しないモデル・プロパティ・操作、enum名の変更など、移行時に確認すべき破壊的変更も記載されています。(GitHub)
今回のPRは、12.0.0 そのものの公開告知というより、2026-04-01 GA 面に対するテストの裏付けを強める更新です。特に、PR #46635 では 2026-04-01 GA Search data-plane spec からの SDK 再生成が行われ、その後の PR #46684 でテストカバレッジと recordings が整備された流れとして見ると分かりやすいです。(GitHub)
移行前に確認すべきチェックポイント
パッケージバージョンを固定してから検証する
本番環境で pip install azure-search-documents のようにバージョンを指定せずにインストールしている場合、意図せずメジャーバージョンが上がる可能性があります。まずは現在のバージョンを確認し、検証ブランチでは明示的に固定しましょう。
pip show azure-search-documents検証時は、依存関係ファイルでバージョンを固定します。
azure-search-documents==12.0.0アップグレード判断では、単にインストールが通るかではなく、検索、登録、更新、削除、インデックス作成、インデクサー実行、ナレッジベース関連の代表シナリオを実行することが重要です。
API versionを暗黙の既定値に任せすぎない
SearchClient などのコンストラクターには api_version を指定できる keyword-only parameter があります。12.0.0 では既定の API version が 2026-04-01 に更新されているため、既存システムで「SDKの既定値」を前提にしている場合は、リクエスト形状やサービス側の解釈が変わる可能性を検証してください。(Microsoft Learn)
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 version を明示し、差分を比較する |
| 新しい 2026-04-01 GA 機能を使いたい | 12.0.0 と 2026-04-01 前提で検証する |
| SDK更新のたびに挙動が変わるのを避けたい | 依存パッケージと API version の両方を管理する |
| 開発中で互換性より新機能検証を優先したい | 既定値利用でもよいが、テスト結果を記録する |
モデル変換とenum名の変更を探す
12.0.0 の変更履歴では、TypeSpec code generation への移行に伴う変更として、SearchFieldDataType の enum 値が UPPER_CASE になり、従来の PascalCase alias は実行時互換のために残ると説明されています。また、SearchField は API由来の retrievable をネイティブプロパティとして使い、hidden は後方互換の getter/setter として残るとされています。(GitHub)
次のようなコードやテストは、アップグレード時に壊れやすい箇所です。
# enum名や文字列表現をスナップショット比較している
assert str(field.type) == "String"
# hidden / retrievable の片方だけを前提にしている
assert field.hidden is False
# serialize / deserialize に依存している
payload = index.serialize()実務では、モデルの内部表現を厳密に比較するより、実際に送るリクエストの意味とサービスから返る結果を確認するテストに寄せる方が安全です。特にCIのスナップショットテストでは、enumの表記ゆれや None と False の違いだけで失敗することがあります。
boolean既定値のNone化に注意する
12.0.0 の変更履歴では、一部の boolean プロパティが True / False ではなく None を既定値にするよう変更されたと説明されています。サーバー側が同じ既定値を適用するため、サービス上の動作変更ではないとされていますが、Pythonオブジェクトを直接比較するテストでは差分として現れる可能性があります。対象例として、CommonGramTokenFilter.ignore_case、StopwordsTokenFilter.ignore_case、SynonymTokenFilter.ignore_case などが挙げられています。(GitHub)
失敗しやすいのは、次のようなテストです。
assert token_filter.ignore_case is Falseサーバー送信時に省略される値なのか、明示的に False を送りたい値なのかを区別してください。省略でよい場合は None を許容するテストに変え、明示が必要な場合はコンストラクターで値を指定します。
Buffered Sender利用者が見るべきポイント
SearchIndexingBufferedSender は、ドキュメントのインデックス操作をバッファリングして送信するためのクライアントです。公式リファレンスでは、auto_flush_interval、initial_batch_action_count、max_retries_per_action、on_new、on_progress、on_error、on_remove などの設定が説明されています。(Microsoft Learn)
今回のPRでは、async buffered sender に関する2つの修正も含まれています。1つは、413 Request Entity Too Large による再帰的な分割処理で、後半のバッチも IndexDocumentsBatch(...) として渡す修正です。もう1つは、async retry failure callbacks を asyncio.create_task で投げっぱなしにせず、await することでコールバック挙動を決定的にする修正です。(GitHub)
大量登録を行うシステムでは、次の観点でテストしてください。
| テスト観点 | 確認内容 |
|---|---|
| 大きなバッチ | 413発生時に分割後も全件処理されるか |
| 失敗コールバック | on_error や on_remove が期待した順序で呼ばれるか |
| リトライ上限 | max_retries_per_action 到達後の挙動がログ・監視に出るか |
| flush | flush() 後にキューが残らないか |
| async context | async with 終了時に未完了タスクが残らないか |
特に、コールバック内でメトリクス送信、ログ出力、失敗ドキュメントの再投入をしている場合は、挙動の決定性が改善される一方で、テストのタイミング前提が変わることがあります。sleep で待つテストではなく、flush 後の結果やコールバック呼び出し回数を明示的に検証する形にしましょう。
自社CIやフォークでrecordingsを使う場合の注意点
Azure SDK リポジトリをフォークして Search SDK のテストを回している場合、assets.json のタグ更新は見逃せません。PRでは python/search/azure-search-documents_35a2c408d6 から python/search/azure-search-documents_575b3d2518 へ更新されています。(GitHub)
よくある失敗は、テストコードだけを取り込んで recordings のタグを更新しないケースです。この場合、playback mode で古いHTTP記録が使われ、リクエストボディ、ヘッダー、API version、レスポンス形状が一致せずに失敗することがあります。
確認手順はシンプルです。
git diff sdk/search/azure-search-documents/assets.jsonあわせて、テストプロキシの storage location、TEST_PROXY_FOLDER、record/playback mode の設定も確認します。Azure SDK Tools Test Proxy は assets.json を参照して外部 recordings を復元・利用するため、録画タグとテストコードの組み合わせをそろえることが重要です。(GitHub)
実務でのおすすめ移行手順
まずは読み替え表を作る
アップグレード前に、影響範囲を機能別に棚卸ししてください。すべてを一度に検証しようとすると、失敗時に原因が分かりにくくなります。
| 機能 | 確認するクライアント | テスト例 |
|---|---|---|
| 検索 | SearchClient | search、get_document、autocomplete、suggest |
| ドキュメント更新 | SearchClient / SearchIndexingBufferedSender | upload、merge、delete、merge_or_upload |
| インデックス管理 | SearchIndexClient | create、update、delete、alias、synonym map |
| インデクサー | SearchIndexerClient | data source、indexer、skillset |
| ナレッジベース | KnowledgeBaseRetrievalClient など | retrieval、knowledge source、configuration |
| テスト基盤 | Test Proxy / recordings | playback、record、assets.json |
依存更新は小さく分ける
おすすめは、次の順序です。
- 依存関係だけを 12.0.0 に固定する
- import error と型・モデル名のエラーを直す
- unit test を通す
- Azure AI Search の検証環境で live test を回す
- 検索結果、登録件数、エラー率、処理時間を旧バージョンと比較する
- CIの recordings やモックを更新する
- 本番反映前にロールバック手順を用意する
特に検索サービスは、アプリ画面では「結果が出ている」ように見えても、ランキング、facet、semantic query、vector query、filter の組み合わせで差分が出ることがあります。代表クエリだけでなく、ゼロ件、上限件数、特殊文字、複数条件フィルター、削除済みドキュメントなども検証してください。
今回の更新から読み取れる判断基準
今回の Azure SDK documentation update で見るべき本質は、「2026-04-01 GA に向けてSDKのテスト構造が整理され、どの動作が unit test で保証され、どの動作が live test で確認されているかが分かりやすくなった」という点です。アプリ利用者はPRのファイル差分をすべて読む必要はありませんが、azure-search-documents 12.0.0 へ移行するなら、変更履歴、API version、Buffered Sender、モデル変換、recordings の5点は必ず確認してください。(GitHub)
次に取るべき行動は、自社コードで azure-search-documents の利用箇所を洗い出し、検索・登録・インデックス管理・インデクサー・ナレッジベース・テスト基盤に分けて検証リストを作ることです。依存関係と API version を明示し、代表的な live test を通してから本番へ進めることで、SDK更新による予期しない差分を最小化できます。
コメント