Uaktualnianie do zestawu .NET SDK usługi Azure AI Search w wersji 11

Artykuł
10/19/2023

Jeśli rozwiązanie wyszukiwania jest oparte na zestawie Azure SDK dla platformy .NET, ten artykuł ułatwia migrowanie kodu z wcześniejszych wersji usługi Microsoft.Azure.Search do wersji 11, nowej biblioteki klienta Azure.Search.Documents. Wersja 11 to w pełni przeprojektowana biblioteka kliencka wydana przez zespół deweloperów zestawu Azure SDK (poprzednie wersje zostały utworzone przez zespół deweloperów usługi Azure AI Search).

Wszystkie funkcje z wersji 10 są implementowane w wersji 11. Najważniejsze różnice obejmują:

Jeden pakiet (Azure.Search.Documents) zamiast czterech
Trzech klientów zamiast dwóch: SearchClient, SearchIndexClient, SearchIndexerClient
Nazewnictwo różnic między różnymi interfejsami API i małymi różnicami strukturalnymi, które upraszczają niektóre zadania

Dziennik zmian biblioteki klienta zawiera listę aktualizacji z elementami. W tym artykule możesz przejrzeć podsumowaną wersję .

Wszystkie przykłady kodu w języku C# i fragmenty kodu w dokumentacji produktu Azure AI Search zostały zmienione w celu korzystania z nowej biblioteki klienta Azure.Search.Documents .

Dlaczego warto uaktualnić?

Korzyści z uaktualniania są podsumowane w następujący sposób:

Nowe funkcje są dodawane tylko do pliku Azure.Search.Documents . Poprzednia wersja Microsoft.Azure.Search została wycofana. Aktualizacje do przestarzałych bibliotek są ograniczone tylko do poprawek usterek o wysokim priorytcie.
Spójność z innymi bibliotekami klienta platformy Azure. Usługa Azure.Search.Documents jest zależna od plików Azure.Core i System.Text.Json i jest zgodna z konwencjonalnymi podejściami do typowych zadań, takich jak połączenia klientów i autoryzacja.

Microsoft.Azure.Search jest oficjalnie wycofany. Jeśli używasz starej wersji, zalecamy uaktualnienie do następnej wyższej wersji, powtarzanie procesu z rzędu do momentu osiągnięcia wersji 11 i Azure.Search.Documents. Strategia uaktualniania przyrostowego ułatwia znajdowanie i rozwiązywanie problemów z blokowaniem. Aby uzyskać wskazówki, zobacz Dokumentację poprzedniej wersji .

Porównanie pakietów

Wersja 11 konsoliduje i upraszcza zarządzanie pakietami, dzięki czemu zarządzanie jest mniejsze.

Wersja 10 i starsze	Wersja 11
Microsoft.Azure.Search Microsoft.Azure.Search.Service Microsoft.Azure.Search.Data Microsoft.Azure.Search.Common	Pakiet Azure.Search.Documents

Porównanie klientów

Jeśli ma to zastosowanie, poniższa tabela mapuje biblioteki klienckie między dwiema wersjami.

Operacje klienta	Microsoft.Azure.Search (wersja 10)	Azure.Search.Documents (wersja 11)
Dotyczy kolekcji dokumentów indeksu (zapytania i importowanie danych)	SearchIndexClient	SearchClient
Obiekty docelowe obiektów powiązanych z indeksem (indeksy, analizatory, mapy synonimów)	SearchServiceClient	SearchIndexClient
Obiekty związane z indeksatorem (indeksatory, źródła danych, zestawy umiejętności)	SearchServiceClient	SearchIndexerClient (nowy)

Uwaga

Zwróć uwagę, że element SearchIndexClient istnieje w obu wersjach, ale dotyczy różnych operacji. W wersji 10 element SearchIndexClient tworzy indeksy i inne obiekty. W wersji 11 element SearchIndexClient współpracuje z istniejącymi indeksami, przeznaczonymi dla kolekcji dokumentów z interfejsami API zapytań i pozyskiwania danych. Aby uniknąć nieporozumień podczas aktualizowania kodu, należy pamiętać o kolejności aktualizowania odwołań klientów. Po wykonaniu sekwencji kroków uaktualniania powinno pomóc rozwiązać wszelkie problemy z zastępowaniem ciągów.

Nazewnictwo i inne różnice interfejsu API

Oprócz różnic klientów (zanotowanych wcześniej i w związku z tym pominiętych w tym miejscu) zmieniono nazwy wielu innych interfejsów API i w niektórych przypadkach przeprojektowano je. Różnice nazw klas zostały podsumowane w poniższych sekcjach. Ta lista nie jest wyczerpująca, ale grupuje zmiany interfejsu API według zadania, co może być przydatne w przypadku poprawek w określonych blokach kodu. Aby uzyskać listę aktualizacji interfejsu API z elementami, zobacz dziennik zmian w Azure.Search.Documents witrynie GitHub.

Uwierzytelnianie i szyfrowanie

Wersja 10	Odpowiednik wersji 11
SearchCredentials	AzureKeyCredential
EncryptionKey (nieudokumentowany w dokumentacji interfejsu API). Obsługa tego interfejsu API została przeniesiona na ogólnie dostępną w wersji 10, ale była dostępna tylko w zestawie SDK w wersji zapoznawczej)	SearchResourceEncryptionKey

Indeksy, analizatory, mapy synonimów

Wersja 10	Odpowiednik wersji 11
Indeks	Indeks wyszukiwania
Pole	Pole wyszukiwania
Datatype	SearchFieldDataType
ItemError	SearchIndexerError
Analizator	LexicalAnalyzer (również `AnalyzerName` do `LexicalAnalyzerName`)
AnalyzeRequest	AnalyzeTextOptions
StandardAnalyzer	LuceneStandardAnalyzer
StandardTokenizer	LuceneStandardTokenizer (również `StandardTokenizerV2` do `LuceneStandardTokenizerV2`)
Tokeninfo	AnalyzedTokenInfo
Tokenizer	LeksykalizatorTokenizer (również `TokenizerName` do `LexicalTokenizerName`)
SynonimMap.Format	Brak. Usuń odwołania do `Format`elementu .

Definicje pól są usprawnione: Pola do wyszukiwania, SimpleField, ComplexField to nowe interfejsy API służące do tworzenia definicji pól.

Indeksatory, źródła danych, zestawy umiejętności

Wersja 10	Odpowiednik wersji 11
Indeksator	Indeksator wyszukiwania
DataSource	SearchIndexerDataSource Połączenie ion
Umiejętności	SearchIndexerSkill
Skillset	SearchIndexerSkillset
Datasourcetype	SearchIndexerDataSourceType

Import danych

Wersja 10	Odpowiednik wersji 11
Indeksowanie	IndexDocumentsAction
IndexBatch	IndexDocumentsBatch
IndexBatchException.FindFailedActionsToRetry()	SearchIndexingBufferedSender

Wykonywanie zapytań dotyczących żądań i odpowiedzi

Wersja 10	Odpowiednik wersji 11
DocumentsOperationsExtensions.SearchAsync	SearchClient.SearchAsync
DocumentSearchResult	SearchResult lub SearchResults, w zależności od tego, czy wynik jest pojedynczym dokumentem, czy wieloma.
DocumentSuggestResult	SuggestResults
Parametry wyszukiwania	SearchOptions
SuggestParameters	SuggestOptions
SearchParameters.Filter	SearchFilter (nowa klasa do konstruowania wyrażeń filtru OData)

Serializacja JSON

Domyślnie zestaw Azure SDK używa formatu System.Text.Json do serializacji JSON, korzystając z możliwości tych interfejsów API do obsługi przekształceń tekstu wcześniej zaimplementowanych za pomocą natywnej klasy SerializePropertyNamesAsCamelCaseAttribute , która nie ma odpowiednika w nowej bibliotece.

Aby serializować nazwy właściwości w camelCase, można użyć atrybutu JsonPropertyNameAttribute (podobnie jak w tym przykładzie).

Alternatywnie można ustawić element JsonNamingPolicy podany w JsonSerializerOptions. Poniższy przykład kodu System.Text.Json pobrany z pliku Readme Microsoft.Azure.Core.Spatial demonstruje użycie camelCase bez konieczności przypisywanie każdej właściwości:

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

Jeśli używasz formatu Newtonsoft.Json do serializacji JSON, możesz przekazać globalne zasady nazewnictwa przy użyciu podobnych atrybutów lub właściwości w narzędziu JsonSerializer Ustawienia. Przykładowy odpowiednik poprzedniego pliku można znaleźć w przykładzie deserializacji dokumentów w pliku readme Newtonsoft.Json.

Wewnątrz wersji 11

Każda wersja biblioteki klienta usługi Azure AI Search jest przeznaczona dla odpowiedniej wersji interfejsu API REST. Interfejs API REST jest uważany za podstawowy dla usługi, a poszczególne zestawy SDK opakowujące wersję interfejsu API REST. Jako deweloper platformy .NET warto zapoznać się z bardziej szczegółową dokumentacją interfejsu API REST, aby uzyskać bardziej szczegółowy zakres określonych obiektów lub operacji. Wersja 11 jest przeznaczona dla specyfikacji usługi wyszukiwania 2020-06-30.

Wersja 11.0 w pełni obsługuje następujące obiekty i operacje:

Tworzenie indeksów i zarządzanie nimi
Tworzenie mapy synonimów i zarządzanie nimi
Tworzenie indeksatora i zarządzanie nim
Tworzenie i zarządzanie źródłem danych indeksatora
Tworzenie zestawu umiejętności i zarządzanie nim
Wszystkie typy zapytań i składnia

Dodatki w wersji 11.1 (szczegóły dziennika zmian):

FieldBuilder (dodany w wersji 11.1)
Właściwość serializatora (dodana w wersji 11.1) do obsługi niestandardowej serializacji

Dodatki w wersji 11.2 (szczegóły dziennika zmian):

Właściwość EncryptionKey dodała indeksatory, źródła danych i zestawy umiejętności
Obsługa właściwości IndexingParameters.IndexingParametersConfiguration
Typy geoprzestrzenne są natywnie obsługiwane w narzędziu FieldBuilder. SearchFilter może kodować typy geometryczne z witryny Microsoft.Spatial bez jawnej zależności zestawu.

Możesz również jawnie zadeklarować zależność od microsoft.Spatial. Przykłady tej techniki są dostępne dla plików System.Text.Json i Newtonsoft.Json.

Dodatki w wersji 11.3 (szczegóły dziennika zmian):

Magazyn wiedzy
Dodano obsługę typów Azure.Core.GeoJson w elementach SearchDocument, SearchFilter i FieldBuilder.
Dodano rejestrowanie oparte na usłudze EventSource. Nazwa źródła zdarzeń to Azure-Search-Documents. Bieżący zestaw zdarzeń koncentruje się na dostrajaniu rozmiarów partii dla elementu SearchIndexingBufferedSender.
Dodano biblioteki CustomEntityLookupSkill i DocumentExtractionSkill. Dodano wartość DefaultCountryHint w elemecie LanguageDetectionSkill.

Przed uaktualnieniem

Zaktualizowano przewodniki Szybki start, samouczki i przykłady języka C#, aby używać pakietu Azure.Search.Documents. Zalecamy przejrzenie przykładów i przewodników, aby dowiedzieć się więcej o nowych interfejsach API przed rozpoczęciem ćwiczenia migracji.
Sposób korzystania z interfejsów API Azure.Search.Documents przedstawia najczęściej używane interfejsy API. Nawet znajomość użytkowników usługi Azure AI Search może chcieć przejrzeć to wprowadzenie do nowej biblioteki jako prekursora migracji.

Kroki uaktualniania

Poniższe kroki umożliwiają rozpoczęcie migracji kodu przez przejście przez pierwszy zestaw wymaganych zadań, szczególnie w odniesieniu do odwołań klientów.

Zainstaluj pakiet Azure.Search.Documents, klikając prawym przyciskiem myszy odwołania do projektu i wybierając pozycję "Zarządzaj pakietami NuGet..." w programie Visual Studio.

Zastąp dyrektywy using dla elementu Microsoft.Azure.Search następującymi instrukcjami using:

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

W przypadku klas wymagających serializacji JSON zastąp ciąg using Newtonsoft.Json .using System.Text.Json.Serialization
Popraw kod uwierzytelniania klienta. W poprzednich wersjach właściwości obiektu klienta można użyć do ustawienia klucza interfejsu API (na przykład właściwości SearchServiceClient.Credentials ). W bieżącej wersji użyj klasy AzureKeyCredential , aby przekazać klucz jako poświadczenia, aby w razie potrzeby zaktualizować klucz interfejsu API bez tworzenia nowych obiektów klienta.

Właściwości klienta zostały usprawnione tylko do Endpoint, ServiceNamei IndexName (tam, gdzie jest to konieczne). W poniższym przykładzie użyto klasy identyfikatora URI systemu, aby udostępnić punkt końcowy i klasę Environment do odczytu w wartości klucza:
```
Uri endpoint = new Uri(Environment.GetEnvironmentVariable("SEARCH_ENDPOINT"));
AzureKeyCredential credential = new AzureKeyCredential(
   Environment.GetEnvironmentVariable("SEARCH_API_KEY"));
SearchIndexClient indexClient = new SearchIndexClient(endpoint, credential);
```
Dodaj nowe odwołania klienta dla obiektów powiązanych z indeksatorem. Jeśli używasz indeksatorów, źródeł danych lub zestawów umiejętności, zmień odwołania klienta do elementu SearchIndexerClient. Ten klient jest nowy w wersji 11 i nie ma antecedent.
Popraw kolekcje i listy. W nowym zestawie SDK wszystkie listy są tylko do odczytu, aby uniknąć problemów podrzędnych, jeśli lista ma zawierać wartości null. Zmiana kodu polega na dodawaniu elementów do listy. Na przykład zamiast przypisywać ciągi do właściwości Select, należy dodać je w następujący sposób:
```
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 i OrderBy to wszystkie listy, które należy teraz odtworzyć.
Aktualizowanie odwołań klientów do zapytań i importowania danych. Wystąpienia klasy SearchIndexClient należy zmienić na SearchClient. Aby uniknąć nieporozumień nazw, przed przejściem do następnego kroku upewnij się, że przechwytujesz wszystkie wystąpienia.
Aktualizowanie odwołań klienta dla obiektów indeksu, mapy synonimów i analizatora. Wystąpienia klasy SearchServiceClient należy zmienić na SearchIndexClient.
W pozostałej części kodu zaktualizuj klasy, metody i właściwości, aby używać interfejsów API nowej biblioteki. Sekcja różnic nazw jest miejscem do uruchomienia, ale można również przejrzeć dziennik zmian.

Jeśli masz problemy ze znalezieniem równoważnych interfejsów API, sugerujemy rejestrowanie problemu https://github.com/MicrosoftDocs/azure-docs/issues , abyśmy mogli ulepszyć dokumentację lub zbadać problem.
Skompiluj ponownie rozwiązanie. Po naprawieniu błędów kompilacji lub ostrzeżeń możesz wprowadzić dodatkowe zmiany w aplikacji, aby skorzystać z nowych funkcji.

Zmiany powodujące niezgodność

Biorąc pod uwagę zamiatanie zmian w bibliotekach i interfejsach API, uaktualnienie do wersji 11 nie jest proste i stanowi przełomową zmianę w sensie, że kod nie będzie już zgodny z poprzednimi wersjami 10 i starszych. Aby zapoznać się z dokładnym przeglądem różnic, zobacz dziennik zmian dla elementu Azure.Search.Documents.

Jeśli chodzi o aktualizacje wersji usługi, gdzie zmiany kodu w wersji 11 odnoszą się do istniejących funkcji (a nie tylko refaktoryzacji interfejsów API), znajdziesz następujące zmiany zachowania:

Algorytm klasyfikacji BM25 zastępuje poprzedni algorytm klasyfikacji nowszą technologią. Nowe usługi automatycznie używają tego algorytmu. W przypadku istniejących usług należy ustawić parametry, aby używać nowego algorytmu.
Uporządkowane wyniki dla wartości null zostały zmienione w tej wersji, a wartości null są wyświetlane jako pierwsze, jeśli sortowanie to asc i ostatnie, jeśli sortowanie to desc. Jeśli napisałeś kod do obsługi sposobu sortowania wartości null, należy przejrzeć i potencjalnie usunąć ten kod, jeśli nie jest już potrzebny.

Ze względu na te zmiany zachowania prawdopodobnie występują niewielkie różnice w sklasyfikowanych wynikach.