Udostępnij za pośrednictwem

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

  • Artykuł

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 przestarzałych bibliotek są ograniczone tylko do poprawek błędów 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 Formatelementu .

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 SearchIndexerDataSourceConnection
Zręczność SearchIndexerSkill
Zestaw umiejętności SearchIndexerSkillset
Typ źródła danych 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 pliku JsonSerializerSettings. 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):

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

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.

  1. 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.

  2. 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;

  3. W przypadku klas wymagających serializacji JSON zastąp ciąg using Newtonsoft.Json .using System.Text.Json.Serialization

  4. 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);

  5. 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.

  6. 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ć.

  7. 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.

  8. Aktualizowanie odwołań klienta dla obiektów indeksu, mapy synonimów i analizatora. Wystąpienia klasy SearchServiceClient należy zmienić na SearchIndexClient.

  9. 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.

  10. 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.

Następne kroki