Azure AI Search .NET SDK sürüm 11'e yükseltme

Arama çözümünüz .NET için Azure SDK üzerinde oluşturulduysa, bu makale kodunuzu Microsoft.Azure.Search'ün önceki sürümlerinden yeni Azure.Search.Documents istemci kitaplığı olan sürüm 11'e geçirmenize yardımcı olur. Sürüm 11, Azure SDK geliştirme ekibi tarafından yayımlanan tamamen yeniden tasarlanmış bir istemci kitaplığıdır (önceki sürümler Azure AI Search geliştirme ekibi tarafından üretildi).

Sürüm 10'daki tüm özellikler sürüm 11'de uygulanır. Önemli farklar şunlardır:

• Dört yerine bir paket (Azure.Search.Documents)
• İki yerine üç istemci: SearchClient, SearchIndexClient, SearchIndexerClient
• Çeşitli API'ler arasındaki adlandırma farklılıkları ve bazı görevleri basitleştiren küçük yapısal farklılıklar

İstemci kitaplığının Değişiklik Günlüğü'nde listelenmiş bir güncelleştirme listesi vardır. Bu makalede özetlenmiş bir sürümü gözden geçirebilirsiniz.

Azure AI Search ürün belgelerindeki tüm C# kod örnekleri ve kod parçacıkları, yeni Azure.Search.Documents istemci kitaplığını kullanacak şekilde yeniden düzenlendi.

Neden yükseltin?

Yükseltmenin avantajları aşağıdaki gibi özetlenir:

• Yeni özellikler yalnızca Azure.Search.Documents'a eklenir. Önceki sürüm olan Microsoft.Azure.Search artık kullanımdan kaldırılmıştır. Kullanım dışı bırakılan kitaplıklara Güncelleştirmeler yalnızca yüksek öncelikli hata düzeltmeleri ile sınırlıdır.

• Diğer Azure istemci kitaplıklarıyla tutarlılık. Azure.Search.Documents, Azure.Core ve System.Text.Json'a bağımlılık alır ve istemci bağlantıları ve yetkilendirme gibi yaygın görevler için geleneksel yaklaşımları izler.

Microsoft.Azure.Search resmi olarak kullanımdan kaldırıldı. Eski bir sürüm kullanıyorsanız, 11. sürüme ve Azure.Search.Documents sürümüne ulaşana kadar işlemi sırayla tekrarlayarak sonraki daha yüksek sürüme yükseltmenizi öneririz. Artımlı yükseltme stratejisi, engelleme sorunlarını bulmayı ve çözmeyi kolaylaştırır. Yönergeler için bkz . Önceki sürüm belgeleri .

Paket karşılaştırması

Sürüm 11, paket yönetimini birleştirir ve basitleştirir, böylece yönetecek daha az şey olur.

İstemci karşılaştırması

Uygun olduğunda, aşağıdaki tablo istemci kitaplıklarını iki sürüm arasında eşler.

Adlandırma ve diğer API farklılıkları

İstemci farklılıklarının yanı sıra (daha önce not alınmıştır ve bu nedenle burada atlanmıştır), birden çok diğer API yeniden adlandırıldı ve bazı durumlarda yeniden tasarlandı. Sınıf adı farklılıkları aşağıdaki bölümlerde özetlenir. Bu liste kapsamlı değildir, ancak API değişikliklerini göreve göre gruplandırarak belirli kod bloklarında düzeltmeler için yararlı olabilir. API güncelleştirmelerinin listelenmiş listesi için GitHub'da değişiklik günlüğüne bakın.Azure.Search.Documents

Kimlik doğrulaması ve şifreleme

Dizinler, çözümleyiciler, eş anlamlı haritalar

Alan tanımları kolaylaştırılmıştır: SearchableField, SimpleField, ComplexField , alan tanımları oluşturmaya yönelik yeni API'lerdir.

Dizin oluşturucular, veri kaynakları, beceri kümeleri

Veri içeri aktarma

Sorgu istekleri ve yanıtları

JSON seri hale getirme

Azure SDK varsayılan olarak JSON serileştirmesi için System.Text.Json kullanır ve daha önce yeni kitaplıkta karşılığı olmayan yerel bir SerializePropertyNamesAsCamelCaseAttribute sınıfı aracılığıyla uygulanan metin dönüştürmelerini işlemek için bu API'lerin özelliklerine dayanır.

Özellik adlarını camelCase olarak serileştirmek için JsonPropertyNameAttribute kullanabilirsiniz (bu örneğe benzer).

Alternatif olarak, JsonSerializerOptions içinde sağlanan bir JsonNamingPolicy ayarlayabilirsiniz. Microsoft.Azure.Core.Spatial benioku dosyasından alınan aşağıdaki System.Text.Json kod örneği, her özelliği bağlamak zorunda kalmadan camelCase kullanımını gösterir:

// 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 serileştirmesi için Newtonsoft.Json kullanıyorsanız, benzer öznitelikleri kullanarak veya JsonSerializer Ayarlar üzerindeki özellikleri kullanarak genel adlandırma ilkelerini geçirebilirsiniz. Öncekine eşdeğer bir örnek için Newtonsoft.Json benioku dosyasındaki Seri durumdan çıkarma belgeleri örneğine bakın.

v11 içinde

Azure AI Search istemci kitaplığının her sürümü REST API'nin karşılık gelen bir sürümünü hedefler. REST API'nin temeli, tek tek SDK'ların REST API'nin bir sürümünü sarmalamasıyla birlikte hizmet için temel olarak kabul edilir. Bir .NET geliştiricisi olarak, belirli nesnelerin veya işlemlerin daha ayrıntılı kapsamı için daha ayrıntılı REST API belgelerini gözden geçirmek yararlı olabilir. Sürüm 11, 2020-06-30 arama hizmeti belirtimini hedefler.

Sürüm 11.0 aşağıdaki nesneleri ve işlemleri tam olarak destekler:

• Dizin oluşturma ve yönetme
• Eş anlamlı harita oluşturma ve yönetme
• Dizin oluşturucu oluşturma ve yönetme
• Dizin oluşturucu veri kaynağı oluşturma ve yönetme
• Beceri kümesi oluşturma ve yönetme
• Tüm sorgu türleri ve söz dizimi

Sürüm 11.1 eklemeleri (günlük ayrıntılarını değiştirme):

• FieldBuilder (11.1'de eklendi)
• Özel serileştirmeyi desteklemek için Seri hale getirici özelliği (11.1'de eklendi)

Sürüm 11.2 eklemeleri (günlük ayrıntılarını değiştirme):

• EncryptionKey özelliği dizin oluşturucular, veri kaynakları ve beceri kümeleri eklendi

• IndexingParameters.IndexingParametersConfiguration özellik desteği

• Jeo-uzamsal türler FieldBuilder'da yerel olarak desteklenir. SearchFilter , açık bir derleme bağımlılığı olmadan Microsoft.Spatial'dan geometrik türleri kodlayabilir.

  Ayrıca, Microsoft.Spatial'a açıkça bağımlılık bildirmeye devam edebilirsiniz. Bu tekniğin örnekleri System.Text.Json ve Newtonsoft.Json için kullanılabilir.

Sürüm 11.3 eklemeleri (günlük ayrıntılarını değiştirme):

• Bilgi Deposu
• SearchDocument, SearchFilter ve FieldBuilder'da Azure.Core.GeoJson türleri için destek eklendi.
• EventSource tabanlı günlük kaydı eklendi. Olay kaynağı adı Azure-Search-Documents'tır. Geçerli olay kümesi SearchIndexingBufferedSender için toplu iş boyutlarını ayarlamaya odaklanmıştır.
• CustomEntityLookupSkill ve DocumentExtractionSkill eklendi. LanguageDetectionSkill içinde DefaultCountryHint eklendi.

Yükseltmeden önce

• Hızlı başlangıçlar, öğreticiler ve C# örnekleri Azure.Search.Documents paketini kullanacak şekilde güncelleştirildi. Geçiş alıştırmasına başlamadan önce yeni API'ler hakkında bilgi edinmek için örnekleri ve kılavuzları gözden geçirmenizi öneririz.

• Azure.Search.Documents'ın nasıl kullanılacağı, en yaygın kullanılan API'leri tanıtır. Azure AI Search'ün bilgili kullanıcıları bile yeni kitaplığa geçişin öncüsü olarak bu girişi gözden geçirmek isteyebilir.

Yükseltme adımları

Aşağıdaki adımlar, özellikle istemci başvuruları ile ilgili olarak gerekli görevlerin ilk kümesinde ilerleyerek kod geçişiyle çalışmaya başlamanızı sağlar.

1. Proje başvurularınıza sağ tıklayıp "NuGet Paketlerini Yönet..." seçeneğini belirleyerek Azure.Search.Documents paketini yükleyin öğesini seçin.

2. Microsoft.Azure.Search için using yönergelerini aşağıdaki using deyimleriyle değiştirin:

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

3. JSON serileştirmesi gerektiren sınıflar için değerini ile using System.Text.Json.Serializationdeğiştirinusing Newtonsoft.Json.

4. İstemci kimlik doğrulama kodunu düzeltin. Önceki sürümlerde, API anahtarını (örneğin, SearchServiceClient.Credentials özelliği) ayarlamak için istemci nesnesindeki özellikleri kullanırsınız. Geçerli sürümde, anahtarı kimlik bilgisi olarak geçirmek için AzureKeyCredential sınıfını kullanın, böylece gerekirse yeni istemci nesneleri oluşturmadan API anahtarını güncelleştirebilirsiniz.

   İstemci özellikleri yalnızca Endpoint, ServiceNameve IndexName (uygunsa) olarak kolaylaştırılmıştır. Aşağıdaki örnek, anahtar değerinde okumak üzere uç noktayı ve Ortam sınıfını sağlamak için sistem Uri sınıfını kullanır:

   Uri endpoint = new Uri(Environment.GetEnvironmentVariable("SEARCH_ENDPOINT"));
   AzureKeyCredential credential = new AzureKeyCredential(
      Environment.GetEnvironmentVariable("SEARCH_API_KEY"));
   SearchIndexClient indexClient = new SearchIndexClient(endpoint, credential);
   

5. Dizin oluşturucuyla ilgili nesneler için yeni istemci başvuruları ekleyin. Dizin oluşturucular, veri kaynakları veya beceri kümeleri kullanıyorsanız, istemci başvurularını SearchIndexerClient olarak değiştirin. Bu istemci sürüm 11'de yenidir ve öncül özelliği yoktur.

6. Koleksiyonları ve listeleri gözden geçirme. Yeni SDK'da, liste null değerler içeriyorsa aşağı akış sorunlarını önlemek için tüm listeler salt okunur durumdadır. Kod değişikliği, listeye öğe eklemektir. Örneğin, bir Select özelliğine dize atamak yerine bunları aşağıdaki gibi ekleyebilirsiniz:

   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, Model, SearchFields, SourceFields, ScoringParameters ve OrderBy artık yeniden yapılandırılması gereken tüm listelerdir.

7. Sorgular ve veri içeri aktarma için istemci başvurularını güncelleştirin. SearchIndexClient örnekleri SearchClient olarak değiştirilmelidir. Ad karışıklığını önlemek için, sonraki adıma geçmeden önce tüm örnekleri yakaladığınıza emin olun.

8. Dizin, eş anlamlı eşleme ve çözümleyici nesneleri için istemci başvurularını güncelleştirin. SearchServiceClient örnekleri SearchIndexClient olarak değiştirilmelidir.

9. Kodunuzun geri kalanı için sınıfları, yöntemleri ve özellikleri yeni kitaplığın API'lerini kullanacak şekilde güncelleştirin. Adlandırma farklılıkları bölümü başlatabileceğiniz bir yerdir, ancak değişiklik günlüğünü de gözden geçirebilirsiniz.

   Eşdeğer API'leri bulma konusunda sorun yaşıyorsanız, belgeleri geliştirebilmemiz veya sorunu araştırabilmemiz için bir sorunu https://github.com/MicrosoftDocs/azure-docs/issues günlüğe kaydetmenizi öneririz.

10. Çözümü yeniden oluşturun. Derleme hatalarını veya uyarılarını düzelttikkten sonra, yeni işlevlerden yararlanmak için uygulamanızda ek değişiklikler yapabilirsiniz.

Hataya neden olan değişiklikler

Kitaplıklarda ve API'lerde yapılan süpürme değişiklikleri göz önünde bulundurulduğunda, sürüm 11'e yükseltme önemsiz değildir ve kodunuzun artık sürüm 10 ve önceki sürümlerle geriye dönük olarak uyumlu olmaması nedeniyle hataya neden olan bir değişiklik oluşturur. Farkları ayrıntılı bir şekilde gözden geçirmek için, için Azure.Search.Documentsdeğişiklik günlüğüne bakın.

Sürüm 11'deki kod değişikliklerinin mevcut işlevlerle (api'lerin yeniden düzenlenmesiyle değil) ilgili olduğu hizmet sürümü güncelleştirmeleri açısından aşağıdaki davranış değişikliklerini görürsünüz:

• BM25 derecelendirme algoritması , önceki derecelendirme algoritmasını daha yeni teknolojiyle değiştirir. Yeni hizmetler bu algoritmayı otomatik olarak kullanır. Mevcut hizmetler için parametreleri yeni algoritmayı kullanacak şekilde ayarlamanız gerekir.

• Bu sürümde null değerler için sıralı sonuçlar değişti; sıralama asc ise önce null değerler, sıralama ise son olarak descgörüntülenir. Null değerlerin nasıl sıralandığını işlemek için kod yazdıysanız, artık gerekli değilse bu kodu gözden geçirmeniz ve potansiyel olarak kaldırmanız gerekir.

Bu davranış değişiklikleri nedeniyle, dereceli sonuçlarda küçük farklılıklar olabilir.

Sonraki adımlar

• C# .NET Uygulamasında Azure.Search.Documents kullanma
• Öğretici: Web uygulamalarına arama ekleme
• Azure.Search.Documents paketi
• GitHub’daki örnekler
• Azure.Search.Document API başvurusu