Обновление до пакета SDK .NET версии 9 для службы "Поиск Azure"

  • Статья

Если вы используете версию 7.0-preview пакета SDK .NET для службы поиска Azure или более раннюю версию, то сведения в этой статье помогут вам обновить приложение для использования версии 9.

Примечание

Если вы хотите использовать версию 8.0-preview для анализа функций, которые недоступны в общедоступной версии, следуйте инструкциям, приведенным в этой статье, чтобы выполнить обновление до версии 8.0-preview.

Более общее пошаговое руководство по пакету SDK, включая примеры, см. в разделе Использование службы поиска Azure в приложении .NET.

Версия 9 пакета SDK службы "Поиск Azure" для .NET содержит некоторые отличия от более ранних версий. Некоторые изменения являются критическими, но даже они требуют относительно незначительных изменений в коде. В разделе Действия по обновлению вы найдете инструкции о том, как изменить код для использования новой версии пакета SDK.

Примечание

Если вы используете версию 4.0-preview или более раннюю, то сначала следует установить версию 5 и только затем обновить ее до версии 9. Инструкции приведены в разделе Обновление пакета SDK службы поиска Azure для .NET до версии 5.

Экземпляр службы поиска Azure поддерживает несколько версий REST API, включая последнюю. Можно продолжать использовать версию, которая больше не является последней, но рекомендуется выполнить перенос кода, чтобы использовать последнюю версию. При использовании REST API необходимо указывать версию API в каждом запросе с помощью параметра api-version. При использовании пакета SDK для .NET версия пакета SDK, которую вы используете, определяет соответствующую версию REST API. Если вы используете устаревшую версию пакета SDK, можно продолжать выполнять этот код без изменений, даже если служба обновлена для поддержки более новой версии API.

Новые возможности версии 9

Версия 9 пакета SDK .NET для службы поиска Azure предназначена для версии 2019-05-06 REST API службы поиска Azure и включает в себя следующие функции.

  • Обогащение с помощью ИИ — эта функция служит для извлечения текста из изображений, больших двоичных объектов и других неструктурированных источников данных, а также для обогащения содержимого, чтобы сделать его более доступным для поиска в индексе службы "Поиск Azure".
  • Поддержка сложных типов позволяет моделировать почти любую вложенную структуру JSON в индексе службы "Поиск Azure".
  • Функция автозаполнения служит альтернативой API-интерфейса Suggest для реализации поиска по мере ввода. Автозаполнение "завершает" набираемое пользователем слово или фразу.
  • Режим синтаксического анализа JsonLines при индексировании больших двоичных объектов создает отдельный документ поиска для каждой сущности JSON, отделенной символом новой строки.

Новые функции предварительного просмотра в версии 8.0-preview

Версия 8.0-preview пакета SDK .NET для службы поиска Azure предназначена для версии API 2017-11-11-Preview. Эта версия включает в себя все функции версии 9, а также:

  • новую функцию предварительной версии — управляемые клиентом ключи шифрования для шифрования неактивных данных на стороне службы. В дополнение к встроенному средству шифрования неактивных данных, предоставляемому корпорацией Майкрософт, теперь доступен дополнительный уровень шифрования, где пользователь является единственным владельцем ключей.

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

Прежде всего обновите справочник NuGet для Microsoft.Azure.Search , воспользовавшись консолью диспетчера пакетов NuGet или щелкнув правой кнопкой мыши ссылки проекта и выбрав "Управление пакетами NuGet" в Visual Studio.

После того как NuGet загрузит новые пакеты и их зависимости, перестройте проект. Сборка может быть выполнена успешно — в зависимости от того, как структурирован ваш код. Если она выполнена, то теперь все готово.

В случае сбоя сборки необходимо исправить все связанные с ней ошибки. Дополнительные сведения об устранении возможных ошибок сборки см. в разделе Критические изменения в версии 9.

Могут появиться дополнительные предупреждения о сборке, связанные с устаревшими методами или свойствами. В предупреждениях будет указано, что следует использовать вместо устаревшей функции. Например, если приложение использует свойство DataSourceType.DocumentDb, отобразится предупреждение "Этот элемент не рекомендован. Используйте CosmosDb".

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

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

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

Примечание

Приведенный ниже список изменений не является исчерпывающим. Некоторые изменения, скорее всего, не приведут к ошибкам сборки, но являются критическими с технической точки зрения, так как нарушают двоичную совместимость со сборками, которые используют предыдущие версии сборок пакета SDK .NET для службы поиска Azure. Такие изменения не перечислены ниже. Чтобы избежать проблем с совместимостью двоичных файлов, при обновлении до версии 9 соберите приложение заново.

Неизменяемые свойства

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

  • AutocompleteItem
  • DocumentSearchResult
  • DocumentSuggestResult
  • FacetResult
  • SearchResult
  • SuggestResult

Изменения класса Field

В класс Field внесены изменения — теперь его можно использовать для представления сложных полей.

Следующие свойства класса bool теперь допускают значение null:

  • IsFilterable
  • IsFacetable
  • IsSearchable
  • IsSortable
  • IsRetrievable
  • IsKey

Это обусловлено тем, что такие свойства теперь должны принимать значение null при использовании сложных полей. Если у вас есть код, считывающий эти свойства, необходимо подготовить его к обработке значения null. Обратите внимание, что все остальные свойства класса Field всегда допускали и продолжают допускать значения null, а некоторые из них также будут иметь значение null при использовании сложных полей, в частности:

  • Analyzer
  • SearchAnalyzer
  • IndexAnalyzer
  • SynonymMaps

Конструктор без параметров класса Field теперь имеет атрибут internal. Теперь во время создания каждого объекта класса Field требуется указать явное имя и тип данных.

Упрощенные типы пакетов и результатов

В версии 7.0-preview и более ранних версиях различные классы, инкапсулирующие группы документов, были структурированы в параллельные иерархии классов:

  • DocumentSearchResult и DocumentSearchResult<T> наследуются от DocumentSearchResultBase;
  • DocumentSuggestResult и DocumentSuggestResult<T> наследуются от DocumentSuggestResultBase;
  • IndexAction и IndexAction<T> наследуются от IndexActionBase;
  • IndexBatch и IndexBatch<T> наследуются от IndexBatchBase;
  • SearchResult и SearchResult<T> наследуются от SearchResultBase;
  • SuggestResult и SuggestResult<T> наследуются от SuggestResultBase.

Производные типы без параметра универсального типа были предназначены для использования в сценариях с динамическим типированием и предполагают использование типа Document.

Начиная с версии 8.0-preview базовые классы и неуниверсальные производные классы были удалены. Для сценариев с динамическим типированием можно использовать классы IndexBatch<Document>, DocumentSearchResult<Document> и т. д.

Удаление класса ExtensibleEnum

Базовый класс ExtensibleEnum был удален. Все классы, производные от него, теперь являются структурами, например AnalyzerName, DataType и DataSourceType. Их методы Create также были удалены. Можно просто удалить вызовы Create, так как эти типы могут быть неявно преобразованы из строк. Если это приводит к ошибкам компилятора, можно явно вызвать оператор преобразования с помощью приведения для устранения неоднозначности типов. Например, можно изменить следующий код:

var index = new Index()
{
    Fields = new[]
    {
        new Field("id", DataType.String) { IsKey = true },
        new Field("message", AnalyzerName.Create("my_email_analyzer")) { IsSearchable = true }
    },
    ...
}

на такой:

var index = new Index()
{
    Fields = new[]
    {
        new Field("id", DataType.String) { IsKey = true },
        new Field("message", (AnalyzerName)"my_email_analyzer") { IsSearchable = true }
    },
    ...
}

Свойства, которые удерживают необязательные значения этих типов, теперь явно типизированы как допускающие значение null, поэтому они по-прежнему являются необязательными.

Удаление классов FacetResults и HitHighlights

Классы FacetResults и HitHighlights были удалены. Результаты аспекта теперь типируются как IDictionary<string, IList<FacetResult>>, а выделение совпадений — как IDictionary<string, IList<string>>. Чтобы быстро устранить ошибки сборки, появившиеся в связи с этим изменением, необходимо добавить псевдонимы using в верхней части каждого файла, где были использованы удаленные типы. Пример:

using FacetResults = System.Collections.Generic.IDictionary<string, System.Collections.Generic.IList<Models.FacetResult>>;
using HitHighlights = System.Collections.Generic.IDictionary<string, System.Collections.Generic.IList<string>>;

Изменения в конструкторе SynonymMap

Конструктор SynonymMap больше не использует параметр enum для SynonymMapFormat. Это перечисление имело только одно значение, следовательно, оно было избыточным. Если вы видите ошибки сборки в результате этого, просто удалите ссылки на параметр SynonymMapFormat.

Различные изменения в классах моделей

Свойство AutocompleteMode объекта AutocompleteParameters больше не может иметь значение null. Если у вас есть код, который присваивает этому свойству значение null, можно просто удалить его, и свойство будет автоматически инициализировано со значением по умолчанию.

Порядок параметров в конструкторе IndexAction был изменен, теперь этот конструктор создается автоматически. Вместо конструктора рекомендуется использовать методы фабрики IndexAction.Upload, IndexAction.Merge и т. д.

Удалены функции предварительной версии

При выполнении обновления с версии 8.0-preview до версии 9 следует иметь в виду, что шифрование с помощью ключей, управляемых клиентом, было удалено, так как доступна только предварительная версия этой функции. В частности, были удалены свойства EncryptionKey для Index и SynonymMap.

Если ваше приложение имеет жесткую зависимость от этих функций, вы не сможете обновить пакет SDK .NET для службы поиска Azure до версии 9. Вы можете и далее использовать версию 8.0-preview. Однако необходимо учитывать, что использовать предварительные версии пакетов SDK в рабочих приложениях не рекомендуется. Предварительные версии функций предназначены исключительно для оценки и могут изменяться.

Примечание

Если вы создали зашифрованные индексы или сопоставления синонимов с помощью версии 8.0-preview пакета SDK, вы по-прежнему сможете использовать их и изменять их определения с помощью версии 9 пакета SDK, это не повлияет на состояние шифрования. Версия 9 пакета SDK не отсылает свойство encryptionKey в REST API. В результате REST API не меняет состояние шифрования ресурса.

Изменение поведения при получении данных

Если вы используете "динамически типизированные" API Search, Suggest или Get, которые возвращают экземпляры типа Document, обратите внимание, что теперь они десериализуют пустые массивы JSON в object[] вместо string[].

Заключение

Если вам нужны дополнительные сведения об использовании пакета SDK .NET для службы поиска Azure, то ознакомьтесь с практическим руководством по .NET.

Будем рады вашим отзывам о пакете SDK. Если у вас возникли проблемы, то вы всегда можете обратиться за помощью на форуме Stack Overflow. При обнаружении ошибки можно зарегистрировать проблему в репозитории GitHub пакета SDK .NET для Azure. Добавьте в заголовок вашей проблемы префикс "[Azure Search]".

Благодарим вас за использование поиска Azure!