Tingkatkan ke Azure AI Search .NET SDK versi 11

Artikel
10/19/2023

Jika solusi pencarian Anda dibangun di Azure SDK untuk .NET, artikel ini membantu Anda memigrasikan kode dari versi Microsoft.Azure.Search yang lebih lama ke versi 11, pustaka klien Azure.Search.Documents baru. Versi 11 adalah pustaka klien yang sepenuhnya dirancang ulang, dirilis oleh tim pengembangan Azure SDK (versi sebelumnya diproduksi oleh tim pengembangan Azure AI Search).

Semua fitur dari versi 10 diimplementasikan dalam versi 11. Perbedaan utama meliputi:

Satu paket (Azure.Search.Documents), alih-alih empat paket
Tiga klien, bukan dua: SearchClient, SearchIndexClient, SearchIndexerClient
Perbedaan penamaan di berbagai rentang API dan perbedaan struktural kecil yang menyederhanakan beberapa tugas

Log Perubahan pustaka klien memiliki daftar pembaruan terperinci. Anda dapat meninjau versi ringkasan dalam artikel ini.

Semua sampel dan cuplikan kode C# dalam dokumentasi produk Azure AI Search telah direvisi untuk menggunakan pustaka klien Azure.Search.Documents baru.

Mengapa meningkatkan?

Manfaat peningkatan diringkas sebagai berikut:

Fitur baru hanya ditambahkan ke Azure.Search.Documents . Versi sebelumnya, Microsoft.Azure.Search, sekarang dihentikan. Pembaruan untuk pustaka yang tidak digunakan lagi hanya terbatas pada perbaikan bug prioritas tinggi.
Konsistensi dengan pustaka klien Azure lainnya. Azure.Search.Documents mengambil dependensi pada Azure.Core dan System.Text.Json, serta mengikuti pendekatan konvensional untuk tugas umum seperti koneksi klien dan otorisasi.

Microsoft.Azure.Search secara resmi dihentikan. Jika Anda menggunakan versi lama, sebaiknya tingkatkan ke versi yang lebih tinggi berikutnya, ulangi proses berturut-turut hingga Anda mencapai versi 11 dan Azure.Search.Documents. Strategi peningkatan inkremental memudahkan untuk menemukan dan memperbaiki masalah pemblokiran. Lihat Dokumen versi sebelumnya untuk panduan.

Perbandingan paket

Versi 11 mengonsolidasikan dan menyederhanakan manajemen paket sehingga ada lebih sedikit untuk dikelola.

Versi 10 dan yang lebih lama	Versi 11
Microsoft.Azure.Search Microsoft.Azure.Search.Service Microsoft.Azure.Search.Data Microsoft.Azure.Search.Common	Paket Azure.Search.Documents

Perbandingan klien

Jika berlaku, tabel berikut ini memetakan pustaka klien di antara dua versi.

Operasi klien	Microsoft.Azure.Search (v10)	Azure.Search.Documents (v11)
Menargetkan pengumpulan dokumen indeks (kueri dan impor data)	SearchIndexClient	SearchClient
Menarget objek terkait indeks (indeks, penganalisis, peta sinonim	SearchServiceClient	SearchIndexClient
Menarget objek terkait pengindeks (pengindeks, sumber data, skillsets)	SearchServiceClient	SearchIndexerClient (baru)

Perhatian

Perhatikan bahwa SearchIndexClient ada di kedua versi, tetapi menargetkan operasi yang berbeda. Dalam versi 10, SearchIndexClient membuat indeks dan objek lainnya. Dalam versi 11, SearchIndexClient bekerja dengan indeks yang ada, yang menargetkan pengumpulan dokumen dengan API kueri dan konsumsi data. Untuk menghindari kebingungan saat memperbarui kode, perhatikan urutan di mana referensi klien diperbarui. Mengikuti urutan dalam Langkah-langkah untuk peningkatan akan membantu mengurangi masalah penggantian untai (karakter).

Penamaan dan perbedaan API lainnya

Selain perbedaan klien (telah dicatat sebelumnya dan dengan demikian dihilangkan di sini), beberapa API lain telah diganti namanya dan dalam beberapa kasus didesain ulang. Perbedaan nama kelas dirangkum di bagian berikut. Daftar ini tidak lengkap tetapi api grup berubah berdasarkan tugas, yang dapat membantu untuk revisi pada blok kode tertentu. Untuk daftar pembaruan API per item, lihat log perubahan untuk Azure.Search.Documents di GitHub.

Autentikasi dan Enkripsi

Versi 10	Versi 11 setara
SearchCredentials	AzureKeyCredential
EncryptionKey (Tidak terdokumentasi dalam referensi API. Dukungan untuk API ini ditransisikan ke tersedia secara umum di v10, tetapi hanya tersedia di SDK pratinjau)	SearchResourceEncryptionKey

Indeks, penganalisis, peta sinonim

Versi 10	Versi 11 setara
Index	SearchIndex
Bidang	SearchField
DataType	SearchFieldDataType
ItemError	SearchIndexerError
Penganalisis	LexicalAnalyzer (juga, `AnalyzerName` ke `LexicalAnalyzerName`)
AnalyzeRequest	AnalyzeTextOptions
StandardAnalyzer	LuceneStandardAnalyzer
StandardTokenizer	LuceneStandardTokenizer (juga, `StandardTokenizerV2` untuk `LuceneStandardTokenizerV2`)
TokenInfo	AnalyzedTokenInfo
Pembuat token	LexicalTokenizer (juga, `TokenizerName` ke `LexicalTokenizerName`)
SynonymMap.Format	Tidak ada. Hapus referensi ke `Format`.

Definisi bidang disederhanakan: SearchableField, SimpleField, ComplexField adalah API baru untuk membuat definisi bidang.

Pengindeks, sumber data, keterampilan

Versi 10	Versi 11 setara
Pengindeks	SearchIndexer
DataSource	SearchIndexerDataSourceConnection
Keterampilan	SearchIndexerSkill
Skillset	SearchIndexerSkillset
DataSourceType	SearchIndexerDataSourceType

Impor data

Versi 10	Versi 11 setara
IndexAction	IndexDocumentsAction
IndexBatch	IndexDocumentsBatch
IndexBatchException.FindFailedActionsToRetry()	SearchIndexingBufferedSender

Permintaan kueri dan respons

Versi 10	Versi 11 setara
DocumentsOperationsExtensions.SearchAsync	SearchClient.SearchAsync
DocumentSearchResult	SearchResult atau SearchResults, tergantung pada apakah hasilnya adalah satu dokumen atau beberapa.
DocumentSuggestResult	SuggestResults
SearchParameters	SearchOptions
SuggestParameters	SuggestOptions
SearchParameters.Filter	SearchFilter (kelas baru untuk membangun ekspresi filter OData)

Serialisasi JSON

Secara default, Azure SDK menggunakan System.Text.Json untuk serialisasi JSON, mengandalkan kemampuan API tersebut untuk menghandel transformasi teks yang sebelumnya diterapkan melalui kelas SerializePropertyNamesAsCamelCaseAttribute asli, yang tidak memiliki mitra di pustaka baru.

Untuk serialisasi nama properti ke dalam camelCase, Anda dapat menggunakan JsonPropertyNameAttribute (mirip dengan contoh ini).

Atau, Anda dapat set JsonNamingPolicy yang disediakan di JsonSerializerOptions. Contoh kode System.Text.Json, yang diambil dari readme Microsoft.Azure.Core.Spatial menunjukkan penggunaan camelCase tanpa harus atribut setiap properti:

// 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");

Jika Anda menggunakan Newtonsoft.Json untuk serialisasi JSON, Anda dapat meneruskan kebijakan penamaan global menggunakan atribut serupa, atau dengan menggunakan properti di JsonSerializer Pengaturan. Untuk contoh yang setara dengan yang sebelumnya, lihat contoh Deserialisasi dokumen di readme Newtonsoft.Json.

Di dalam v11

Setiap versi pustaka klien Azure AI Search menargetkan versi REST API yang sesuai. REST API dianggap sebagai dasar untuk layanan, dengan SDK individual membungkus versi REST API. Sebagai pengembang .NET, akan sangat membantu untuk meninjau dokumentasi REST API yang lebih verbose untuk lebih banyak cakupan objek atau operasi tertentu. Versi 11 menargetkan spesifikasi layanan pencarian 2020-06-30.

Versi 11.0 sepenuhnya mendukung objek dan operasi berikut:

Pembuatan dan manajemen indeks
Pembuatan dan manajemen peta sinonim
Pembuatan dan manajemen pengindeks
Pembuatan dan manajemen sumber data pengindeks
Pembuatan dan manajemen skillset
Semua jenis kueri dan sintaks

Tambahan versi 11.1 (detail log perubahan):

FieldBuilder (ditambahkan dalam 11.1)
Properti pembuat serialisasi (ditambahkan dalam 11.1) untuk mendukung serialisasi kustom

Tambahan versi 11.2 (detail log perubahan):

Properti EncryptionKey menambahkan pengindeks, sumber data, dan skillset
Dukungan properti IndexingParameters.IndexingParametersConfiguration
Jenis geospasial secara native didukung dalam FieldBuilder. SearchFilter dapat menyandikan jenis geometris dari Microsoft.Spatial tanpa ketergantungan perakitan eksplisit.

Anda juga dapat terus secara eksplisit menyatakan dependensi pada Microsoft.Spatial. Contoh-contoh teknik ini tersedia untuk System.Text.Json dan Newtonsoft.Json.

Penambahan versi 11.3 (ubah detail log ):

KnowledgeStore
Menambahkan dukungan untuk jenis Azure.Core.GeoJson di SearchDocument, SearchFilter, dan FieldBuilder.
Menambahkan pengelogan berbasis EventSource. Nama sumber peristiwa adalah Azure-Search-Documents. Kumpulan peristiwa saat ini difokuskan pada penyetelan ukuran batch untuk SearchIndexingBufferedSender.
Menambahkan CustomEntityLookupSkill dan DocumentExtractionSkill. Menambahkan DefaultCountryHint dalam LanguageDetectionSkill.

Sebelum peningkatan

Mulai cepat, tutorial, dan sampel C# telah diperbarui untuk menggunakan paket Azure.Search.Documents. Sebaiknya tinjau sampel dan panduan untuk mempelajari TENTANG API baru sebelum memulai latihan migrasi.
Cara menggunakan Azure.Search.Documents memperkenalkan API yang paling umum digunakan. Bahkan pengguna Azure AI Search yang berpengetahuan luas mungkin ingin meninjau pengenalan pustaka baru ini sebagai pendahulu migrasi.

Langkah-langkah untuk peningkatan

Langkah-langkah berikut membuat Anda memulai migrasi kode dengan menelusuri serangkaian tugas pertama yang diperlukan, terutama mengenai referensi klien.

Pasang paket Azure.Search.Documents dengan mengklik kanan referensi proyek Anda dan memilih "Kelola Paket NuGet..." di Visual Studio.

Ganti menggunakan direktif untuk Microsoft.Azure.Search dengan pernyataan penggunaan berikut:

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

Untuk kelas yang memerlukan serialisasi JSON, ganti using Newtonsoft.Json dengan using System.Text.Json.Serialization.
Merevisi kode autentikasi klien. Di versi sebelumnya, Anda akan menggunakan properti pada objek klien untuk mengatur kunci API (misalnya, properti SearchServiceClient.Credentials). Dalam versi saat ini, gunakan kelas AzureKeyCredential untuk meneruskan kunci sebagai info masuk, sehingga jika diperlukan, Anda dapat memperbarui kunci API tanpa membuat objek klien baru.

Properti klien telah disederhanakan menjadi hanya Endpoint, ServiceName, dan IndexName (jika sesuai). Contoh berikut menggunakan kelas Uri sistem untuk menyediakan titik akhir dan kelas Lingkungan untuk dibaca dalam nilai kunci:
```
Uri endpoint = new Uri(Environment.GetEnvironmentVariable("SEARCH_ENDPOINT"));
AzureKeyCredential credential = new AzureKeyCredential(
   Environment.GetEnvironmentVariable("SEARCH_API_KEY"));
SearchIndexClient indexClient = new SearchIndexClient(endpoint, credential);
```
Tambahkan referensi klien baru untuk objek terkait pengindeks. Jika Anda menggunakan pengindeks, sumber data, atau set keterampilan, ubah referensi klien ke SearchIndexerClient. Klien ini baru dalam versi 11 dan tidak memiliki versi pendahulu.
Merevisi koleksi dan daftar. Di SDK baru, semua daftar bersifat baca-saja untuk menghindari masalah hilir jika daftar tersebut berisi nilai null. Perubahan kode ini menambahkan item ke daftar. Misalnya, alih-alih menetapkan untai (karakter) ke properti Pilih, Anda akan menambahkannya sebagai berikut:
```
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");
```
Pilih, Faset, SearchFields, SourceFields, ScoringParameters, dan OrderBy adalah semua daftar yang sekarang perlu direkonstruksi.
Perbarui referensi klien untuk kueri dan impor data. Contoh SearchIndexClient harus diubah ke SearchClient. Untuk menghindari kebingungan nama, pastikan Anda menangkap semua instans sebelum melanjutkan ke langkah berikutnya.
Perbarui referensi klien untuk objek indeks, peta sinonim, dan penganalisis. Instans SearchServiceClient harus diubah ke SearchIndexClient.
Untuk sisa kode Anda, perbarui kelas, metode, dan properti untuk menggunakan API pustaka baru. Bagian perbedaan penamaan adalah tempat untuk memulai tetapi Anda juga dapat mengulas log perubahan.

Jika Anda mengalami masalah saat menemukan API yang setara, sebaiknya gunakan untuk mencatat masalah pada https://github.com/MicrosoftDocs/azure-docs/issues sehingga kami dapat meningkatkan dokumentasi atau menyelidiki masalah tersebut.
Bangun kembali solusinya. Setelah memperbaiki kesalahan bangun atau peringatan, Anda dapat membuat perubahan tambahan kepada aplikasi untuk memanfaatkan fungsionalitas baru.

Perubahan mencolok

Mengingat perubahan penyapuan pada pustaka dan API, upgrade ke versi 11 tidak mudah dan merupakan perubahan pemutus, dalam arti bahwa kode Anda tidak akan lagi kompatibel dengan versi 10 dan yang lebih lama. Untuk tinjauan menyeluruh tentang perbedaannya, lihat log perubahan untuk Azure.Search.Documents.

Dalam hal pembaruan versi layanan, di mana perubahan kode dalam versi 11 terkait dengan fungsionalitas yang ada (dan bukan hanya pemfaktoran ulang API), Anda akan menemukan perubahan perilaku berikut:

Algoritma peringkat BM25 menggantikan algoritma peringkat sebelumnya dengan teknologi yang lebih baru. Layanan baru menggunakan algoritma ini secara otomatis. Untuk layanan yang ada, Anda harus mengatur parameter untuk menggunakan algoritma yang baru.
Hasil yang diurutkan untuk nilai kosong telah berubah dalam versi ini, dengan nilai kosong muncul terlebih dahulu jika pengurutannya asc dan terakhir jika pengurutannya desc. Jika Anda menulis kode untuk menangani bagaimana nilai kosong diurutkan, Anda harus meninjau dan berpotensi menghapus kode tersebut jika tidak lagi diperlukan.

Karena perubahan perilaku ini, kemungkinan ada sedikit variasi dalam hasil berpangkat.

Share via