Поделиться через

Обновление до пакета SDK для поиска .NET для Azure для поиска .NET версии 11

  • Статья

Если решение поиска основано на пакете SDK Azure для .NET, эта статья поможет перенести код из более ранних версий Microsoft.Azure.Search в версию 11, новая клиентская библиотека Azure.Search.Documents. Версия 11 — это полностью переработанная клиентская библиотека, выпущенная командой разработки пакета SDK Для Azure (предыдущие версии были созданы командой разработки поиска ИИ Azure).

Все функции версии 10 реализованы в версии 11. Ниже приведены основные отличия.

  • Один пакет (Azure.Search.Documents) вместо четырех.
  • Три клиента вместо двух: SearchClient, SearchIndexClient, SearchIndexerClient.
  • отличия в именовании ряда API и небольшие структурные отличия, упрощающие решение некоторых задач.

В журнале изменений клиентской библиотеки есть подробный список обновлений. В этой статье можно просмотреть сводную версию .

Все примеры кода C# и фрагменты кода в документации по продуктам поиска ИИ Azure были изменены, чтобы использовать новую клиентскую библиотеку Azure.Search.Documents .

Зачем выполнять обновление

Ниже перечислены преимущества обновления.

  • Новые функции добавляются только в Azure.Search.Documents . Предыдущая версия Microsoft.Azure.Search теперь прекращена. Обновления устаревших библиотек ограничены только исправлениями ошибок с высоким приоритетом.

  • Согласованность с другими клиентскими библиотеками Azure. Azure.Search.Documents получает зависимость от Azure.Core и System.Text.Json и использует традиционные подходы для решения общих задач, таких как клиентские подключения и авторизация.

Microsoft.Azure.Search официально прекращен. Если вы используете старую версию, рекомендуем выполнить обновление до следующей более поздней версии, повторяя процесс в последовательности, пока не достигнете версии 11 и Azure.Search.Documents. Стратегия добавочного обновления упрощает поиск и устранение проблем с блокировкой. Дополнительные сведения см . в документации по предыдущей версии.

Сравнение пакетов

Версия 11 объединяет и упрощает управление пакетами, чтобы снизить необходимость управлять ими.

Версия 10 и прежние версии Версия 11
Microsoft.Azure.Search Microsoft.Azure.Search.Service

Microsoft.Azure.Search.Data
Microsoft.Azure.Search.Common		 Пакет Azure.Search.Documents

Сравнение клиентов

В приведенной ниже таблице сопоставлены клиентские библиотеки двух версий (там, где это применимо).

Операции клиента Microsoft.Azure.Search (версия 10) Azure.Search.Documents (версия 11)
Обращается к коллекции документов индекса (запросы и импорт данных). SearchIndexClient SearchClient
Обращается к объектам, связанным с индексами (индексы, анализаторы, сопоставления синонимов). SearchServiceClient SearchIndexClient
Обращается к объектам, связанным с индексатором (индексаторы, источники данных, наборы навыков). SearchServiceClient SearchIndexerClient (новинка)

Внимание

Обратите внимание, что SearchIndexClient существует в обеих версиях, но при этом используются различные операции. В версии 10 SearchIndexClient создает индексы и другие объекты. В версии 11 SearchIndexClient работает с имеющимися индексами, предназначенными для коллекции документов с помощью API запросов и приема данных. Чтобы избежать путаницы при обновлении кода, следите за порядком обновления клиентских ссылок. Выполнение инструкций, изложенных в разделе "Действия по обновлению", должно помочь в устранении возможных проблем с заменой строк.

Разница в именовании и другие отличия в API

Помимо отличий в клиентских библиотеках (которые описаны выше и поэтому опущены здесь), были переименованы, а в некоторых случаях и переработаны многие другие API. Различия имен класса приведены в следующих разделах. Этот список не является исчерпывающим, но он изменяет API групп по задачам, что может быть полезно для редакций в определенных блоках кода. Детализированный список обновлений API см. в журнале изменений Azure.Search.Documents на GitHub.

Проверка подлинности и шифрование

Версия 10 Эквивалент в версии 11
SearchCredentials AzureKeyCredential
EncryptionKey (undocumented в справочнике по API. Поддержка этого API была перенесена на общедоступную версию 10, но доступна только в пакете SDK предварительной версии) SearchResourceEncryptionKey

Индексы, анализаторы, карты синонимов

Версия 10 Эквивалент в версии 11
Указатель SearchIndex
Поле SearchField
DataType SearchFieldDataType
ItemError SearchIndexerError
Анализатор LexicalAnalyzer (также AnalyzerName — LexicalAnalyzerName)
AnalyzeRequest AnalyzeTextOptions
StandardAnalyzer LuceneStandardAnalyzer
StandardTokenizer LuceneStandardTokenizer (также StandardTokenizerV2 — LuceneStandardTokenizerV2)
TokenInfo AnalyzedTokenInfo
Tokenizer LexicalTokenizer (также TokenizerName — LexicalTokenizerName)
SynonymMap.Format Нет. Необходимо удалить ссылки на Format.

Упрощено определение полей: SearchableField, SimpleField и ComplexField — новые API для создания определений полей.

Индексаторы, источники данных, наборы навыков

Версия 10 Эквивалент в версии 11
Индексатор SearchIndexer
DataSource SearchIndexerDataSourceConnection
Мастерство SearchIndexerSkill
Набор навыков SearchIndexerSkillset
DataSourceType SearchIndexerDataSourceType

Импорт данных

Версия 10 Эквивалент в версии 11
IndexAction IndexDocumentsAction
IndexBatch IndexDocumentsBatch
IndexBatchException.FindFailedActionsToRetry() SearchIndexingBufferedSender

Запросы и ответы

Версия 10 Эквивалент в версии 11
DocumentsOperationsExtensions.SearchAsync SearchClient.SearchAsync
DocumentSearchResult SearchResult или SearchResults в зависимости от того, что представляет собой результат: один документ или несколько документов.
DocumentSuggestResult SuggestResults
SearchParameters SearchOptions
SuggestParameters SuggestOptions
SearchParameters.Filter SearchFilter (новый класс для создания выражений фильтра OData)

Сериализация JSON

По умолчанию в пакете SDK Azure для сериализации JSON используется класс System.Text.Json, который пользуется этими API для выполнения преобразований текста, которые ранее реализовывались через собственный класс SerializePropertyNamesAsCamelCaseAttribute, не имеющий аналога в новой библиотеке.

Для сериализации имен свойств в формате camelCase можно использовать класс JsonPropertyNameAttribute (как в этом примере).

Как вариант, для этого можно задать свойство JsonNamingPolicy класса JsonSerializerOptions. В следующем примере кода с использованием класса System.Text.Json, взятом из файла readme к библиотеке Microsoft.Azure.Core.Spatial, демонстрируется использование формата camelCase без необходимости устанавливать соответствующий атрибут для каждого свойства:

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

Если вы используете Newtonsoft.Json для сериализации JSON, вы можете передать глобальные политики именования с помощью аналогичных атрибутов или с помощью свойств в JsonSerializerSettings. Пример, эквивалентный предыдущему, см . в примере документов десериализации в readme Newtonsoft.Json.

Версия 11

Каждая версия клиентской библиотеки поиска ИИ Azure предназначена для соответствующей версии REST API. REST API считается основой службы, а отдельные пакеты SDK представляют собой оболочку для определенной версии REST API. Разработчикам .NET, желающим узнать подробнее о конкретных объектах или операциях, может быть полезно ознакомиться с документацией по REST API. Версия 11 предназначена для спецификации службы поиска 2020-06-30.

Версия 11.0 полностью поддерживает следующие объекты и операции:

  • создание индексов и управление ими;
  • создание карт синонимов и управление ими;
  • создание индексаторов и управление ими;
  • создание источников данных индексатора и управление ими;
  • создание наборов навыков и управление ими;
  • все типы запросов и синтаксис.

Дополнения в версии 11.1 (подробные сведения о журнале изменений):

  • FieldBuilder (начиная с версии 11.1);
  • свойство Serializer (начиная с версии 11.1) для поддержки настраиваемой сериализации.

Дополнения для версии 11.2 (подробные сведения о журнале изменений):

Дополнения версии 11.3 (сведения о журнале изменений):

Перед обновлением

  • Краткие руководства, учебники и примеры C# были обновлены для использования пакета Azure.Search.Documents. Мы рекомендуем ознакомиться с примерами и пошаговым руководствами, чтобы узнать о новых API, прежде чем приступить к выполнению упражнения по миграции.

  • В практическом руководстве Azure.Search.Documents представлены наиболее часто используемые интерфейсы API. Даже знающие пользователи службы "Поиск ИИ Azure" могут потребоваться ознакомиться с этой введением в новую библиотеку в качестве предшественника миграции.

Действия по обновлению

Следующие шаги по началу миграции кода см. в первом наборе необходимых задач, особенно в отношении ссылок клиентов.

  1. Установите пакет Azure.Search.Documents, щелкнув правой кнопкой мыши ссылки проекта и выбрав пункт "Управление пакетами NuGet...". в Visual Studio.

  2. Замените директивы using для Microsoft.Azure.Search следующими операторами using:

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

  3. Для классов, требующих сериализации JSON, поменяйте using Newtonsoft.Json на using System.Text.Json.Serialization.

  4. Переработайте клиентский код проверки подлинности. В предыдущих версиях для задания ключа API использовались свойства клиентского объекта (например, SearchServiceClient.Credentials). В текущей версии следует использовать класс AzureKeyCredential для передачи ключа в качестве учетных данных, чтобы при необходимости можно было обновить ключ API, не создавая новые клиентские объекты.

    Набор свойств клиента упрощен: остались только Endpoint, ServiceName и IndexName (там, где это уместно). В следующем примере используется системный класс URI для задания конечной точки и класс Environment для считывания значения ключа:

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

  5. Добавьте новые клиентские ссылки для объектов, связанных с индексаторами. Если вы используете индексаторы, источники данных или наборы навыков, измените клиентские ссылки на SearchIndexerClient. Этот клиент впервые появился в версии 11 и не имеет предшественника.

  6. Переработайте коллекции и списки. В новом пакете SDK все списки доступны только для чтения, чтобы избежать возникновения проблем ниже по цепочке, если список содержит значения NULL. Изменение в коде заключается в том, что элементы теперь добавляются в список. Например, вместо того, чтобы присваивать строковые значения свойству Select, необходимо добавлять их следующим образом:

    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 и OrderBy — вот все списки, которые требуется переделать.

  7. Обновите клиентские ссылки для запросов и импорта данных. Все вхождения SearchIndexClient необходимо поменять на SearchClient. Чтобы избежать путаницы с именами, убедитесь, что вы не пропустили ни одного вхождения, прежде чем переходить к следующему шагу.

  8. Обновите клиентские ссылки для объектов индексов, карт синонимов и анализаторов. Все вхождения SearchServiceClient необходимо поменять на SearchIndexClient.

  9. В оставшейся части кода обновите классы, методы и свойства так, чтобы использовать API новой библиотеки. Хорошей отправной точкой здесь может быть раздел "Разница в именовании и другие отличия в API", но вы также можете изучить журнал изменений.

    Если у вас возникли затруднения с поиском эквивалентных API, мы рекомендуем заявить о проблеме в https://github.com/MicrosoftDocs/azure-docs/issues, чтобы мы могли улучшить документацию или исследовать выявленную проблему.

  10. Заново постройте решение. После устранения предупреждений и ошибок сборки вы можете при необходимости внести изменения в приложение, чтобы воспользоваться новыми функциональными возможностями.

Критические изменения

Учитывая масштабные изменения в библиотеках и API, обновление до версии 11 — задача нетривиальная и представляет собой критическое изменение в том смысле, что ваш код потеряет обратную совместимость с версией 10 и более ранними версиями. Подробный обзор отличий двух версий см. в журнале изменений пакета Azure.Search.Documents.

С точки зрения обновлений версий службы, в которых изменения кода в версии 11 связаны с существующими функциями (а не только рефакторингом API), вы найдете следующие изменения в поведении:

  • Алгоритм ранжирования BM25 заменяет предыдущий алгоритм ранжирования более новой технологией. Новые службы используют этот алгоритм автоматически. Чтобы использовать его в имеющихся службах, необходимо установить соответствующие параметры.

  • В этой версии было изменено упорядочивание результатов со значениями NULL: значения NULL отображаются первыми при сортировке asc и последними при сортировке desc. Если у вас написан код, обрабатывающий сортировку значений NULL, следует проверить этот код и, возможно, удалить его, если он больше не нужен.

Из-за этих изменений поведения, скорее всего, есть небольшие вариации в ранжированных результатах.

Следующие шаги