Azure AI Search .NET SDK バージョン 11 へのアップグレード

[アーティクル]
10/19/2023

検索ソリューションが AZURE SDK for .net 上に構築されている場合、この記事では、Microsoft.Azure.Search の以前のバージョンからバージョン 11 の新しい Azure.Search.Documents クライアントライブラリへコードを移行する方法について説明します。バージョン 11 は、Azure SDK 開発チームによってリリースされた、完全に再設計されたクライアントライブラリです (以前のバージョンは Azure AI Search 開発チームによって作成されました)。

バージョン 11 にはバージョン 10 のすべての機能が実装されています。主な違いは次のとおりです。

パッケージは 4つでなく 1 つ (Azure.Search.Documents)
クライアントは 2 つでなく 3 つ: SearchClient、SearchIndexClient、SearchIndexerClient
さまざまな API 全体の名前付けの違いと、一部のタスクを簡略化する細かい構造の違い

クライアントライブラリの変更ログに、更新内容が箇条書きで列挙されています。要約されたバージョンをこの記事で確認できます。

Azure AI Search 製品ドキュメントのすべての C# コードサンプルとスニペットが、新しい Azure.Search.Documents クライアントライブラリを使用するように改訂されました。

アップグレードする理由

アップグレードの利点は、次のようにまとめられています。

新機能は Azure.Search.Documents にのみ追加されます。以前のバージョンである Microsoft.Azure.Search は廃止されました。非推奨のライブラリに対する更新は、優先度の高いバグ修正に限定されます。
他の Azure ライブラリとの一貫性。 Azure.Search.Documents は Azure.Core と System.Text.Json に依存しており、クライアントの接続や承認といった一般的なタスクについては従来のアプローチを踏襲します。

Microsoft.Azure.Search は、正式に廃止されました。古いバージョンを使用している場合は、バージョン 11 と Azure.Search.Documents に到達するまでプロセスを連続して繰り返し、次の上位バージョンにアップグレードすることをお勧めします。増分アップグレード戦略により、ブロッキングの問題を簡単に見つけて修正できます。ガイダンスについては、以前のバージョンのドキュメントを参照してください。

パッケージの比較

バージョン11では、管理する対象が減るように、パッケージ管理を統合して簡略化します。

バージョン 10 以前	バージョン 11
Microsoft.Azure.Search Microsoft.Azure.Search.Service Microsoft.Azure.Search.Data Microsoft.Azure.Search.Common	Azure.Search.Documents パッケージ

クライアントの比較

2 つのバージョン間で対応するクライアントライブラリがある場合、その対応付けを次の表に示します。

クライアントの操作	Microsoft.Azure.Search (v10)	Azure.Search.Documents (v11)
インデックスのドキュメントコレクション (クエリとデータインポート) を対象とします。	SearchIndexClient	SearchClient
インデックス関連のオブジェクト (インデックス、アナライザー、シノニムマップ) をターゲットにします。	SearchServiceClient	SearchIndexClient
インデクサー関連のオブジェクト (インデクサー、データソース、スキルセット) を対象とします。	SearchServiceClient	SearchIndexerClient (新規)

注意事項

SearchIndexClient は両方のバージョンに存在しますが、異なる操作を対象としていることに注意してください。バージョン 10 では、SearchIndexClient によりインデックスおよびそのほかのオブジェクトが作成されます。バージョン 11 では、SearchIndexClient は既存のインデックスと連携し、クエリおよびデータインジェスト API を使用してドキュメントコレクションを対象とします。コードを更新するときの混乱を避けるために、クライアント参照が更新される順序にご注意ください。「アップグレードの手順」のシーケンスに従うと、文字列の置換の問題を軽減できます。

名前付けとその他の API の違い

クライアントの違い (既に説明したため、ここでは省略します) に加え、他の複数の API は名前が変更され、場合によっては設計が変更されています。クラス名の違いを以下のセクションにまとめます。この一覧は完全なものではありませんが、API の変更をタスクごとにグループ化しているため、特定のコードブロックを改訂する場合に役立ちます。 API 更新の項目別一覧については、GitHub の Azure.Search.Documents の変更ログを参照してください。

認証と暗号化

バージョン 10	バージョン 11 の相当するもの
SearchCredentials	AzureKeyCredential
EncryptionKey (API リファレンスには記載されていません。この API のサポートは、v10 で一般提供に移行しましたが、利用できるのはプレビュー SDK のみです)	SearchResourceEncryptionKey

インデックス、アナライザー、シノニムマップ

バージョン 10	バージョン 11 の相当するもの
インデックス	SearchIndex
フィールド	SearchField
DataType	SearchFieldDataType
ItemError	SearchIndexerError
Analyzer	LexicalAnalyzer (さらに `AnalyzerName` から `LexicalAnalyzerName` へ)
AnalyzeRequest	AnalyzeTextOptions
StandardAnalyzer	LuceneStandardAnalyzer
StandardTokenizer	LuceneStandardTokenizer (さらに `StandardTokenizerV2` から `LuceneStandardTokenizerV2` へ)
TokenInfo	AnalyzedTokenInfo
Tokenizer	LexicalTokenizer (さらに `TokenizerName` から `LexicalTokenizerName` へ)
SynonymMap.Format	なし。 `Format` への参照を削除します。

フィールド定義は整理されています。SearchableField、SimpleField、ComplexField は、フィールド定義を作成するための新しい API です。

インデクサー、データソース、スキルセット

バージョン 10	バージョン 11 の相当するもの
Indexer	SearchIndexer
DataSource	SearchIndexerDataSourceConnection
Skill	SearchIndexerSkill
スキルセット	SearchIndexerSkillset
DataSourceType	SearchIndexerDataSourceType

データのインポート

バージョン 10	バージョン 11 の相当するもの
IndexAction	IndexDocumentsAction
IndexBatch	IndexDocumentsBatch
IndexBatchException.FindFailedActionsToRetry()	SearchIndexingBufferedSender

クエリの要求と応答

バージョン 10	バージョン 11 の相当するもの
DocumentsOperationsExtensions.SearchAsync	SearchClient.SearchAsync
DocumentSearchResult	結果のドキュメントが 1 つか複数かに応じて、SearchResult または SearchResults。
DocumentSuggestResult	SuggestResults
SearchParameters	SearchOptions
SuggestParameters	SuggestOptions
SearchParameters.Filter	SearchFilter (OData フィルター式を構築するための新しいクラス)

JSON シリアル化

既定では、Azure SDK は、JSON のシリアル化に System.Text.Json を使用します。これらの API の機能を使用して、新しいライブラリに対応するものがないネイティブ SerializePropertyNamesAsCamelCaseAttribute クラスを介して以前に実装されたテキスト変換を処理します。

プロパティ名を camelCase にシリアル化するには、JsonPropertyNameAttribute を使用します (こちらの例に類似)。

または、JsonSerializerOptions で提供されている JsonNamingPolicy を設定することもできます。次の System.Text.Json のコード例 (Microsoft.Azure.Core.Spatial の README から取得) は、個々のプロパティに割り当てることなく camelCase を使用する方法を示しています。

// Get the Azure AI Search service endpoint and read-only API key.
Uri endpoint = new Uri(Environment.GetEnvironmentVariable("SEARCH_ENDPOINT"));
AzureKeyCredential credential = new AzureKeyCredential(Environment.GetEnvironmentVariable("SEARCH_API_KEY"));

// Create serializer options with our converter to deserialize geographic points.
JsonSerializerOptions serializerOptions = new JsonSerializerOptions
{
    Converters =
    {
        new MicrosoftSpatialGeoJsonConverter()
    },
    PropertyNamingPolicy = JsonNamingPolicy.CamelCase
};

SearchClientOptions clientOptions = new SearchClientOptions
{
    Serializer = new JsonObjectSerializer(serializerOptions)
};

SearchClient client = new SearchClient(endpoint, "mountains", credential, clientOptions);
Response<SearchResults<Mountain>> results = client.Search<Mountain>("Rainier");

JSON シリアル化に Newtonsoft.Json を使用している場合は、同様の属性を使用するか、JsonSerializerSettings のプロパティを使用して、グローバル名前付けポリシーを渡すことができます。上記と同等の例については、Newtonsoft.Json の README のドキュメントの逆シリアル化の例を参照してください。

Inside v11

Azure AI Search クライアントライブラリの各バージョンは、対応するバージョンの REST API をターゲットとします。この REST API はサービスの基盤と見なされ、個々の SDK によって REST API のバージョンがラップされます。 .NET 開発者として、特定のオブジェクトや操作についてもっと詳しく知りたい場合は、REST API ドキュメントの方が情報量が多く参考になるでしょう。バージョン 11 は、2020-06-30 の Search サービス仕様を対象としています。

バージョン 11.0 では、次のオブジェクトと操作が完全にサポートされています。

インデックスの作成と管理
シノニムマップの作成と管理
インデクサーの作成と管理
インデクサーのデータソースの作成と管理
スキルセットの作成と管理
すべてのクエリタイプと構文

バージョン 11.1 の追加 (変更ログの詳細):

FieldBuilder (11.1 で追加)
カスタムのシリアル化をサポートするためのシリアライザープロパティ (11.1 で追加)

バージョン 11.2 の追加 (変更ログの詳細):

EncryptionKey プロパティにインデクサー、データソース、スキルセットが追加されました
IndexingParameters.IndexingParametersConfiguration プロパティのサポート
地理空間型は、FieldBuilder でネイティブにサポートされています。 SearchFilter では、明示的なアセンブリの依存関係を使用せずに、Microsoft.Spatial からジオメトリック型をエンコードできます。

Microsoft.Spatial への依存関係を引き続き明示的に宣言することもできます。この技術の例は、System.Text.Json および Newtonsoft.Json で使用できます。

バージョン 11.3 の追加 (変更ログの詳細):

KnowledgeStore
SearchDocument、SearchFilter、FieldBuilder に Azure.Core.GeoJson 型のサポートが追加されました。
EventSource ベースのログが追加されました。イベントソース名は Azure-Search-Documents です。現在の一連のイベントは SearchIndexingBufferedSender のバッチサイズのチューニングに重点を置いています。
CustomEntityLookupSkill と DocumentExtractionSkill が追加されました。 LanguageDetectionSkill に DefaultCountryHint が追加されました。

アップグレードする前に

クイックスタート、チュートリアル、C# サンプルは、Azure.Search.Documents パッケージを使用するように更新されています。サンプルとチュートリアルを確認し、新しい API についての知識を深めたうえで、移行の演習に取り組むことをお勧めします。
Azure.Search.Documents を使用する方法に関する記事では、最もよく使用される API を紹介しています。 Azure AI Search の知識のあるユーザーであっても、移行の前に新しいライブラリの概要を確認することをお勧めします。

アップグレードの手順

次の手順では、コードの移行の基本について説明します。まず必要な最初の一連のタスク (特にクライアント参照) について手順を説明します。

Visual Studio でプロジェクト参照を右クリックし、[NuGet パッケージの管理] を選択して、Azure.Search.Documents パッケージをインストールします。

Microsoft.Azure.Search の using ディレクティブを次の using ステートメントに置き換えます。

using Azure;
using Azure.Search.Documents;
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;
using Azure.Search.Documents.Models;

JSON のシリアル化を必要とするクラスの場合は、using Newtonsoft.Json を using System.Text.Json.Serialization で置き換えます。
クライアント認証コードを変更します。以前のバージョンでは、クライアントオブジェクトのプロパティを使用して、API キー (SearchServiceClient.Credentials プロパティなど) を設定します。現在のバージョンでは、AzureKeyCredential クラスを使用して、キーを資格情報として渡します。これにより、必要な場合は、新しいクライアントオブジェクトを作成せずに API キーを更新することができます。

クライアントのプロパティは、Endpoint、ServiceName、および IndexName のみに簡素化されています (該当する場合)。次の例では、システムの Uri クラスを使用して、エンドポイント、およびキー値を読み取るための環境クラスを提供しています。
```
Uri endpoint = new Uri(Environment.GetEnvironmentVariable("SEARCH_ENDPOINT"));
AzureKeyCredential credential = new AzureKeyCredential(
   Environment.GetEnvironmentVariable("SEARCH_API_KEY"));
SearchIndexClient indexClient = new SearchIndexClient(endpoint, credential);
```
インデクサー関連オブジェクトの新しいクライアント参照を追加します。インデクサー、データソース、またはスキルセットを使用している場合は、クライアント参照を SearchIndexerClient に変更します。このクライアントはバージョン 11 で新しく追加されたものであり、元の機能はありません。
コレクションとリストを変更します。新しい SDK では、リストに null 値が含まれている場合にダウンストリームの問題が発生するのを回避するため、すべてのリストが読み取り専用になっています。コードを変更して、リストに項目を追加するようにします。たとえば、Select プロパティに文字列を割り当てる代わりに、次のように文字列を追加します。
```
var options = new SearchOptions
 {
    SearchMode = SearchMode.All,
    IncludeTotalCount = true
 };

 // Select fields to return in results.
 options.Select.Add("HotelName");
 options.Select.Add("Description");
 options.Select.Add("Tags");
 options.Select.Add("Rooms");
 options.Select.Add("Rating");
 options.Select.Add("LastRenovationDate");
```
Select、Facets、SearchFields、SourceFields、ScoringParameters、OrderBy はすべて、現在再構築が必要なリストです。
クエリとデータインポートのクライアント参照を更新します。 SearchIndexClient のインスタンスは SearchClient に変更する必要があります。名前の混乱を避けるために、次の手順に進む前に、すべてのインスタンスをキャッチしてください。
インデックス、シノニムマップ、およびアナライザーオブジェクトのクライアント参照を更新します。 SearchServiceClient のインスタンスは SearchIndexClient に変更する必要があります。
コードの残りの部分では、新しいライブラリの API を使用するようにクラス、メソッド、およびプロパティを更新します。名前付けの違いのセクションから始めることができますが、変更ログを確認することもできます。

同等の API が見つからない場合は、Microsoft でドキュメントを改善し、問題を調査することができるように、https://github.com/MicrosoftDocs/azure-docs/issues で問題を記録することをお勧めします。
ソリューションをリビルドします。すべてのビルドエラーまたは警告を修正した後、新しい機能を利用するようにアプリケーションを変更できます。

破壊的変更

ライブラリと API に加えられた全面的な変更を考えると、バージョン 11 へのアップグレードは重大であり、コードがバージョン 10 以前との下位互換性を失うという点で、破壊的変更に相当します。違いの詳細については、Azure.Search.Documents の変更ログを参照してください。

サービス使用条件の更新時に、バージョン 11 のコード変更が、API のリファクタリングに限らず、既存の機能に関連している場合は、次のような動作変更があります。

BM25 ランク付けアルゴリズムでは、前のランク付けアルゴリズムがより新しいテクノロジに置き換えられます。新しいサービスはこのアルゴリズムを自動的に使用します。既存のサービスについては、新しいアルゴリズムを使用するようにパラメーターを設定する必要があります。
このバージョンでは、順序付けされた null 値の結果が変更されていて、null 値は、並べ替えが asc の場合は最初に、並べ替えが desc の場合は最後に表示されます。 null 値の並べ替え方法を処理するコードを記述した場合、そのコードを確認し、不要になった場合は削除する必要があります。

これらの動作の変更により、ランク付けされた結果にわずかな変化が生じる可能性があります。

Azure AI Search .NET SDK バージョン 11 へのアップグレード

アップグレードする理由

パッケージの比較

クライアントの比較

名前付けとその他の API の違い

認証と暗号化

インデックス、アナライザー、シノニムマップ

インデクサー、データソース、スキルセット

データのインポート

クエリの要求と応答

JSON シリアル化

Inside v11

アップグレードする前に

アップグレードの手順

破壊的変更

次のステップ

その他のリソース

Azure AI Search .NET SDK バージョン 11 へのアップグレード

アップグレードする理由

パッケージの比較

クライアントの比較

名前付けとその他の API の違い

認証と暗号化

インデックス、アナライザー、シノニム マップ

インデクサー、データソース、スキルセット

データのインポート

クエリの要求と応答

JSON シリアル化

Inside v11

アップグレードする前に

アップグレードの手順

破壊的変更

次のステップ

その他のリソース

インデックス、アナライザー、シノニムマップ