Upgrade na sadu .NET SDK služby Azure AI Search verze 11

Pokud je vaše vyhledávací řešení založené na sadě Azure SDK pro .NET, pomůže vám tento článek migrovat kód ze starších verzí Microsoft.Azure.Search na verzi 11, což je nová klientská knihovna Azure.Search.Documents. Verze 11 je plně přepracovaná klientská knihovna, kterou vydal vývojový tým sady Azure SDK (předchozí verze vytvořil vývojový tým azure AI Search).

Všechny funkce verze 10 jsou implementovány ve verzi 11. Mezi klíčové rozdíly patří:

• Jeden balíček (Azure.Search.Documents) místo čtyř
• Tři klienti místo dvou: SearchClient, SearchIndexClient, SearchIndexerClient
• Pojmenování rozdílů v různých rozhraních API a malých strukturálních rozdílech, které zjednodušují některé úlohy

Protokol změn klientské knihovny obsahuje seznam aktualizací. Souhrnnou verzi si můžete prohlédnout v tomto článku.

Všechny ukázky kódu a fragmenty kódu jazyka C# v dokumentaci k produktu Azure AI Search byly upraveny tak, aby používaly novou klientskou knihovnu Azure.Search.Documents .

Proč upgradovat?

Výhody upgradu jsou shrnuty takto:

• Nové funkce se přidají jenom do Azure.Search.Documents . Předchozí verze Microsoft.Azure.Search je nyní vyřazena. Aktualizace zastaralých knihoven jsou omezené jenom na opravy chyb s vysokou prioritou.

• Konzistence s jinými klientskými knihovnami Azure Azure.Search.Documents využívá závislost na Azure.Core a System.Text.Json a řídí se běžnými přístupy pro běžné úlohy, jako jsou připojení klientů a autorizace.

Microsoft.Azure.Search je oficiálně vyřazený. Pokud používáte starou verzi, doporučujeme upgradovat na další vyšší verzi a postup opakovat postupně, dokud nedosáhnete verze 11 a Azure.Search.Documents. Strategie přírůstkového upgradu usnadňuje vyhledání a opravu blokujících problémů. Pokyny najdete v dokumentaci k předchozí verzi.

Porovnání balíčků

Verze 11 konsoliduje a zjednodušuje správu balíčků, aby bylo k dispozici méně správy.

Porovnání klientů

Pokud je to možné, následující tabulka mapuje klientské knihovny mezi těmito dvěma verzemi.

Pojmenování a další rozdíly v rozhraní API

Kromě rozdílů mezi klienty (které jsme si poznamenali dříve, a proto zde není uvedeno), bylo přejmenováno několik dalších rozhraní API a v některých případech bylo přepracováno. Rozdíly mezi názvy tříd jsou shrnuty v následujících částech. Tento seznam není vyčerpávající, ale seskupuje změny rozhraní API podle úlohy, což může být užitečné pro revize konkrétních bloků kódu. Seznam aktualizací rozhraní API pro položky najdete v protokolu Azure.Search.Documents změn na GitHubu.

Ověřování a šifrování

Indexy, analyzátory, mapy synonym

Definice polí jsou zjednodušené: SearchableField, SimpleField, ComplexField jsou nová rozhraní API pro vytváření definic polí.

Indexery, zdroje dat, sady dovedností

Import dat

Požadavky a odpovědi na dotazy

Serializace JSON

Sada Azure SDK ve výchozím nastavení používá system.Text.Json pro serializaci JSON a spoléhá na možnosti těchto rozhraní API ke zpracování transformací textu dříve implementovaných prostřednictvím nativní třídy SerializePropertyNamesAsCamelCaseAttribute , která nemá v nové knihovně žádný protějšk.

K serializaci názvů vlastností do camelCase můžete použít JsonPropertyNameAttribute (podobně jako v tomto příkladu).

Alternativně můžete nastavit JsonNamingPolicy poskytované v JsonSerializerOptions. Následující příklad kódu System.Text.Json převzatý z souboru Microsoft.Azure.Core.Spatial readme ukazuje použití camelCase bez nutnosti přiřazovat všechny vlastnosti:

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

Pokud pro serializaci JSON používáte Newtonsoft.Json, můžete předat globální zásady pojmenování pomocí podobných atributů nebo pomocí vlastností v JsonSerializerSettings. Příklad ekvivalentní předchozímu dokumentu najdete v příkladu deserializace dokumentů v souboru readme Newtonsoft.Json.

Uvnitř v11

Každá verze klientské knihovny Azure AI Search cílí na odpovídající verzi rozhraní REST API. Rozhraní REST API je pro službu považováno za základ, přičemž jednotlivé sady SDK obtékání verze rozhraní REST API. Jako vývojář .NET může být užitečné projít si podrobnější dokumentaci k rozhraní REST API a získat tak podrobnější pokrytí konkrétních objektů nebo operací. Verze 11 cílí na specifikaci vyhledávací služby 2020-06-30.

Verze 11.0 plně podporuje následující objekty a operace:

• Vytváření a správa indexů
• Vytváření a správa map synonym
• Vytvoření a správa indexeru
• Vytvoření a správa zdroje dat indexeru
• Vytváření a správa sady dovedností
• Všechny typy dotazů a syntaxe

Přidání verze 11.1 (podrobnosti protokolu změn):

• FieldBuilder (přidáno ve verzi 11.1)
• Serializační vlastnost (přidaná v 11.1) pro podporu vlastní serializace

Přidání verze 11.2 (podrobnosti protokolu změn):

• Vlastnost EncryptionKey přidala indexery, zdroje dat a sady dovedností.

• Podpora vlastností IndexingParameters.IndexingParametersConfiguration

• Geoprostorové typy jsou nativně podporovány v FieldBuilderu. SearchFilter může kódovat geometrické typy z Microsoft.Spatial bez explicitní závislosti sestavení.

  Můžete také i nadále explicitně deklarovat závislost na microsoft.Spatial. Příklady této techniky jsou k dispozici pro System.Text.Json a Newtonsoft.Json.

Přidání verze 11.3 (podrobnosti protokolu změn):

• KnowledgeStore
• Přidání podpory pro typy Azure.Core.GeoJson ve službě SearchDocument, SearchFilter a FieldBuilder
• Přidání protokolování založeného na EventSource Název zdroje událostí je Azure-Search-Documents. Aktuální sada událostí se zaměřuje na ladění velikostí dávek pro SearchIndexingBufferedSender.
• Přidání CustomEntityLookupSkill a DocumentExtractionSkill Přidání DefaultCountryHint v LanguageDetectionSkill.

Před upgradem

• Rychlé starty, kurzy a ukázky jazyka C# byly aktualizovány tak, aby používaly balíček Azure.Search.Documents. Před zahájením cvičení migrace doporučujeme projít si ukázky a názorné postupy, abyste se seznámili s novými rozhraními API.

• Jak používat Azure.Search.Documents představuje nejčastěji používaná rozhraní API. I znalí uživatelé služby Azure AI Search si mohou chtít projít tento úvod do nové knihovny jako prekurzor migrace.

Postup upgradu

Následující kroky vám pomůžou začít s migrací kódu tím, že si projdete první sadu požadovaných úloh, zejména pokud jde o odkazy na klienty.

1. Nainstalujte balíček Azure.Search.Documents tak, že kliknete pravým tlačítkem na odkazy na projekt a vyberete Spravovat balíčky NuGet. v sadě Visual Studio.

2. Nahraďte direktivy using pro Microsoft.Azure.Search následujícími příkazy using:

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

3. Pro třídy, které vyžadují serializaci JSON, nahraďte using Newtonsoft.Json .using System.Text.Json.Serialization

4. Revidovat ověřovací kód klienta V předchozích verzích byste pomocí vlastností klientského objektu nastavili klíč rozhraní API (například vlastnost SearchServiceClient.Credentials ). V aktuální verzi použijte třídu AzureKeyCredential k předání klíče jako přihlašovacích údajů, takže v případě potřeby můžete klíč rozhraní API aktualizovat bez vytváření nových klientských objektů.

   Vlastnosti klienta byly zjednodušeny pouze EndpointServiceName, a IndexName (tam, kde je to vhodné). Následující příklad používá systémovou třídu URI k poskytnutí koncového bodu a třídy prostředí ke čtení v hodnotě klíče:

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

5. Přidání nových odkazů na klienta pro objekty související s indexerem Pokud používáte indexery, zdroje dat nebo sady dovedností, změňte odkazy klientů na SearchIndexerClient. Tento klient je nový ve verzi 11 a nemá žádné tecedenty.

6. Revidovat kolekce a seznamy V nové sadě SDK jsou všechny seznamy jen pro čtení, aby se zabránilo podřízeným problémům, pokud seznam obsahuje hodnoty null. Změnou kódu je přidání položek do seznamu. Například místo přiřazování řetězců k vlastnosti Select byste je přidali takto:

   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 a OrderBy jsou všechny seznamy, které je teď potřeba rekonstruovat.

7. Aktualizujte odkazy klientů na dotazy a import dat. Instance SearchIndexClient by se měly změnit na SearchClient. Abyste se vyhnuli nejasnostem názvů, nezapomeňte před pokračováním k dalšímu kroku zachytit všechny instance.

8. Aktualizujte odkazy klientů na objekty indexu, synonym a analyzátoru. Instance SearchServiceClient by se měly změnit na SearchIndexClient.

9. Ve zbývající části kódu aktualizujte třídy, metody a vlastnosti tak, aby používaly rozhraní API nové knihovny. Oddíl rozdíly v pojmenování je místo, kde začít, ale můžete si také projít protokol změn.

   Pokud máte potíže s vyhledáním ekvivalentních rozhraní API, doporučujeme protokolovat problém https://github.com/MicrosoftDocs/azure-docs/issues , abychom mohli vylepšit dokumentaci nebo problém prozkoumat.

10. Znovu sestavte řešení. Po opravě chyb sestavení nebo upozornění můžete v aplikaci provést další změny, abyste mohli využívat nové funkce.

Změny způsobující chyby

Vzhledem k tomu, že uklidit změny knihoven a rozhraní API, upgrade na verzi 11 není triviální a představuje zásadní změnu v tom smyslu, že váš kód už nebude zpětně kompatibilní s verzí 10 a staršími. Důkladnou kontrolu rozdílů najdete v protokolu Azure.Search.Documentszměn.

Pokud jde o aktualizace verzí služby, kde změny kódu ve verzi 11 souvisejí s existujícími funkcemi (a ne pouze refaktoringem rozhraní API), najdete následující změny chování:

• Algoritmus řazení BM25 nahrazuje předchozí algoritmus řazení novější technologií. Nové služby používají tento algoritmus automaticky. U existujících služeb je nutné nastavit parametry tak, aby používaly nový algoritmus.

• Seřazené výsledky pro hodnoty null se v této verzi změnily, přičemž hodnoty null se zobrazují jako první, pokud je asc řazení a poslední, pokud je descřazení . Pokud jste napsali kód pro zpracování řazení hodnot null, měli byste zkontrolovat a případně odebrat tento kód, pokud už není nutný.

Vzhledem k těmto změnám chování je pravděpodobné, že se v seřazených výsledcích mírně liší.

Další kroky

• Jak používat Azure.Search.Documents v aplikaci .NET v jazyce C#
• Kurz: Přidání vyhledávání do webových aplikací
• Balíček Azure.Search.Documents
• Ukázky na GitHubu
• Referenční informace k rozhraní API služby Azure.Search.Document