Обновление до пакета 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 (подробные сведения о журнале изменений):

• Индексаторы, источники данных и наборы навыков с добавлением свойства EncryptionKey.

• Поддержка свойства IndexingParameters.IndexingParametersConfiguration.

• Геопространственные типы изначально поддерживаются в FieldBuilder. SearchFilter может кодировать геометрические типы из Microsoft.Spatial без явной зависимости сборки.

  Кроме того, можно продолжить явно объявлять зависимость от Microsoft.Spatial. Имеются примеры данного метода для System.Text.Json и Newtonsoft.Json.

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

• Хранилище знаний
• Добавлена поддержка типов Azure.Core.GeoJson в SearchDocument, SearchFilter и FieldBuilder.
• Добавлено ведение журнала на основе EventSource. Имя источника событий — Azure-Search-Documents. Текущий набор событий ориентирован на настройку размеров пакетов для SearchIndexingBufferedSender.
• Добавлены CustomEntityLookupSkill и DocumentExtractionSkill. Добавлен DefaultCountryHint в LanguageDetectionSkill.

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

• Краткие руководства, учебники и примеры 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, следует проверить этот код и, возможно, удалить его, если он больше не нужен.

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

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

• Использование Azure.Search.Documents в приложении .NET на C#
• Учебник. Добавление поиска в веб-приложения
• Пакет Azure.Search.Documents
• Примеры на GitHub
• Справочник по API Azure.Search.Document