Руководство. Индексирование данных SQL Azure с помощью пакета SDK для .NET

Статья
09/23/2024

Настройте индексатор для извлечения данных, доступных для поиска, из База данных SQL Azure, отправляя его в индекс поиска в службе "Поиск ИИ Azure".

В этом руководстве используется C# и пакет SDK Azure для .NET для выполнения следующих задач:

создание источника данных, который подключается к Базе данных SQL Azure;
Создать индексатор
выполнение индексатора для загрузки данных в индекс;
обращение к индексу для проверки.

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

Необходимые компоненты

База данных SQL Azure с помощью проверки подлинности SQL Server
Visual Studio
Поиск по искусственному интеллекту Azure. Создайте службу поиска или найдите существующую службу

Примечание.

Вы можете использовать бесплатную службу поиска для этого руководства. Уровень "Бесплатный" ограничивается тремя индексами, тремя индексаторами и тремя источниками данных. В этом руководстве создается по одному объекту из каждой категории. Перед началом работы убедитесь, что у службы есть достаточно места, чтобы принять новые ресурсы.

Загрузка файлов

Исходный код для этого руководства размещен в папке DotNetHowToIndexer репозитория Azure-Samples/search-dotnet-getting-started на GitHub.

1. Создание служб

В этом руководстве используется поиск ИИ Azure для индексирования и запросов, а также База данных SQL Azure в качестве внешнего источника данных. Желательно создать обе службы в одном регионе и группе ресурсов, чтобы упростить взаимодействие и управление. На практике база данных SQL Azure может находиться в любом регионе.

Начните с базы данных SQL Azure

В этом руководстве содержатся hotels.sql файл в примере скачивания для заполнения базы данных. Поиск ИИ Azure использует плоские наборы строк, например один из созданных из представления или запроса. При помощи файла SQL в примере решения создается и заполняется одна таблица.

Если у вас есть существующий ресурс База данных SQL Azure, вы можете добавить в него таблицу отелей, начиная с шага "Открыть запрос".

Создайте базу данных SQL Azure, выполнив инструкции из краткого руководства. Создание одной базы данных.

Важно настроить сервер для базы данных.
- Выберите параметр проверки подлинности SQL Server, который предложит указать имя пользователя и пароль. Это необходимо для ADO.NET строка подключения, используемого индексатором.
- Выберите общедоступное подключение. Это упрощает выполнение этого руководства. Общедоступная не рекомендуется для рабочей среды, и мы рекомендуем удалить этот ресурс в конце руководства.
В портал Azure перейдите к новому ресурсу.
Добавьте правило брандмауэра, чтобы разрешить доступ к клиенту, используя инструкции в кратком руководстве. Создание правила брандмауэра на уровне сервера в портал Azure. Чтобы получить IP-адрес, можно запустить ipconfig из командной строки.
Используйте редактор запросов для загрузки примеров данных. В области навигации выберите редактор запросов (предварительная версия) и введите имя пользователя и пароль администратора сервера.

Если вы получаете ошибку отказа в доступе, скопируйте IP-адрес клиента из сообщения об ошибке, откройте страницу безопасности сети для сервера и добавьте правило для входящего трафика, которое разрешает доступ от клиента.
В редакторе запросов выберите "Открыть запрос " и перейдите к расположению hotels.sql файла на локальном компьютере.
Выберите файл и нажмите кнопку "Открыть". Скрипт должен выглядеть, как на следующем снимке экрана:
Выберите Выполнить для выполнения запроса. В области результатов появится сообщение об успешном выполнении запроса для трех строк.
Чтобы получить набор строк из этой таблицы, можно выполнить следующий запрос для проверки:
```
SELECT * FROM Hotels
```
Скопируйте строку подключения ADO.NET к базе данных. Щелкните Параметры>Строки подключения и скопируйте строку подключения ADO.NET, как показано в примере ниже.
```
Server=tcp:<YOUR-DATABASE-NAME>.database.windows.net,1433;Initial Catalog=hotels-db;Persist Security Info=False;User ID=<YOUR-USER-NAME>;Password=<YOUR-PASSWORD>;MultipleActiveResultSets=False;Encrypt=True;TrustServerCertificate=False;Connection Timeout=30;
```

Вам потребуется этот строка подключения в следующем упражнении, настроив среду.

Поиск с использованием ИИ Azure

Следующим компонентом является поиск ИИ Azure, который можно создать в портал Azure. Для выполнения действий в этом пошаговом руководстве можно использовать уровень "Бесплатный".

Получение ключа api администратора и URL-адреса для поиска ИИ Azure

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

Войдите на портал Azure и на странице обзора службы поиска получите URL-адрес. Пример конечной точки может выглядеть так: https://mydemo.search.windows.net.
В разделе Параметры>Ключи получите ключ администратора, чтобы обрести полные права на службу. Существуют два взаимозаменяемых ключа администратора, предназначенных для обеспечения непрерывности бизнес-процессов на случай, если вам потребуется сменить один из них. Вы можете использовать первичный или вторичный ключ для выполнения запросов на добавление, изменение и удаление объектов.

2. Настройка среды

Запустите Visual Studio и откройте файл DotNetHowToIndexers.sln.
В обозревателе решений откройте файл appsettings.json, чтобы предоставить сведения о подключении.
Если SearchServiceEndPointполный URL-адрес на странице обзора службы имеет значение "https://my-demo-service.search.windows.net", то значением для предоставления является весь URL-адрес.
Для AzureSqlConnectionString формат строки аналогичен следующему: "Server=tcp:<your-database-name>.database.windows.net,1433;Initial Catalog=hotels-db;Persist Security Info=False;User ID=<your-user-name>;Password=<your-password>;MultipleActiveResultSets=False;Encrypt=True;TrustServerCertificate=False;Connection Timeout=30;"
```
{
  "SearchServiceEndPoint": "<placeholder-search-full-url>",
  "SearchServiceAdminApiKey": "<placeholder-admin-key-for-search-service>",
  "AzureSqlConnectionString": "<placeholder-ADO.NET-connection-string",
}
```
Замените пароль пользователя в строка подключения SQL допустимым паролем. Имя базы данных и пользователя копируются автоматически, а пароль необходимо вводить вручную.

3. Создание конвейера

Для индексаторов требуется объект источника данных и индекс. Нужный нам код находится в двух файлах:

hotel.cs содержит схему, которая определяет индекс;
Program.cs содержит функции для создания структур и управления ими в службе.

hotell.cs

Схема индексов определяет коллекцию полей, включая атрибуты, в которых указаны разрешенные операции. Например, в них указывается, поддерживает ли схема полнотекстовый поиск, фильтрацию или сортировку, как в представленном ниже определении для HotelName. SearchableField — это полнотекстовые данные с возможностью поиска по определению. Другие атрибуты назначаются явно.

. . . 
[SearchableField(IsFilterable = true, IsSortable = true)]
[JsonPropertyName("hotelName")]
public string HotelName { get; set; }
. . .

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

Program.cs

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

Объект источника данных настраивается с параметрами, характерными для База данных SQL Azure ресурсов, включая частичное или добавочное индексирование для использования встроенных функций обнаружения изменений SQL Azure. Исходная демонстрационная база данных гостиниц в SQL Azure содержит столбец "обратимого удаления", IsDeleted. Если для этого столбца задано значение true в базе данных, индексатор удаляет соответствующий документ из индекса поиска ИИ Azure.

Console.WriteLine("Creating data source...");

var dataSource =
      new SearchIndexerDataSourceConnection(
         "hotels-sql-ds",
         SearchIndexerDataSourceType.AzureSql,
         configuration["AzureSQLConnectionString"],
         new SearchIndexerDataContainer("hotels"));

indexerClient.CreateOrUpdateDataSourceConnection(dataSource);

Объект индексатора не зависит от платформы. Его настройка, планирование и вызов одинаковы независимо от источника. Этот пример индексатора включает в себя расписание, возможность сброса, которая очищает журнал индексатора и вызывает метод для создания и немедленного запуска индексатора. Чтобы создать или обновить индексатор, используйте CreateOrUpdateIndexerAsync.

Console.WriteLine("Creating Azure SQL indexer...");

var schedule = new IndexingSchedule(TimeSpan.FromDays(1))
{
      StartTime = DateTimeOffset.Now
};

var parameters = new IndexingParameters()
{
      BatchSize = 100,
      MaxFailedItems = 0,
      MaxFailedItemsPerBatch = 0
};

// Indexer declarations require a data source and search index.
// Common optional properties include a schedule, parameters, and field mappings
// The field mappings below are redundant due to how the Hotel class is defined, but 
// we included them anyway to show the syntax 
var indexer = new SearchIndexer("hotels-sql-idxr", dataSource.Name, searchIndex.Name)
{
      Description = "Data indexer",
      Schedule = schedule,
      Parameters = parameters,
      FieldMappings =
      {
         new FieldMapping("_id") {TargetFieldName = "HotelId"},
         new FieldMapping("Amenities") {TargetFieldName = "Tags"}
      }
};

await indexerClient.CreateOrUpdateIndexerAsync(indexer);

Запуски индексаторов обычно выполняются по расписанию, но если при разработке вам потребуется немедленно запустить индексатор, используйте RunIndexerAsync.

Console.WriteLine("Running Azure SQL indexer...");

try
{
      await indexerClient.RunIndexerAsync(indexer.Name);
}
catch (RequestFailedException ex) when (ex.Status == 429)
{
      Console.WriteLine("Failed to run indexer: {0}", ex.Message);
}

4. Сборка решения

Нажмите клавишу F5 для сборки и запуска решения. Программа выполняется в режиме отладки. В окне консоли отображаются сведения о состоянии каждой операции.

Код выполняется локально в Visual Studio. Устанавливается подключение к службе поиска в Azure, которая в свою очередь подключается к Базе данных SQL Azure, чтобы получить набор данных. При таком большом количестве операций есть несколько возможных точек сбоя. Если поступает сообщение об ошибке, прежде всего проверьте следующее:

Выполните поиск данных подключения к службе, которые вы указали в полном URL-адресе. Если вы ввели только имя службы, выполнение операций прекращается на создании индекса и отображается сообщение о сбое подключения.
Сведения о подключении к базе данных в appsettings.json. Это должен быть ADO.NET строка подключения, полученный из портал Azure, изменен, чтобы включить имя пользователя и пароль, допустимые для вашей базы данных. Учетная запись пользователя должна предоставлять разрешение на получение данных. Для IP-адреса локального клиента должен быть разрешен входящий доступ через брандмауэр.
Ограничения ресурсов. Помните, что уровень "Бесплатный" имеет ограничения на три индекса, индексаторы и источники данных. Служба с максимальным ограничением не может создавать новые объекты.

5. Поиск

Проверьте создание объекта на портале Azure и создайте запрос по индексу с помощью обозревателя поиска.

Войдите в портал Azure и в левой области навигации службы поиска откройте каждую страницу, чтобы убедиться, что объект создан. Индексы, индексаторы и источники данных будут иметь "hotels-sql-idx", "hotels-sql-indexer" и "hotels-sql-ds", соответственно.
На вкладке Indexes выберите индекс hotels-sql-idx. На странице индекса hotels на первой вкладке вы найдете обозреватель поиска.
Выберите "Поиск", чтобы выдать пустой запрос.

В индексе возвращаются три записи в виде документов JSON. Проводник поиска возвращает документы в формате JSON, чтобы можно было просматривать всю структуру.
Затем перейдите в представление JSON, чтобы можно было ввести параметры запроса:
```
{
     "search": "river",
     "count": true
}
```
При помощи этого запроса вызывается полнотекстовый поиск по слову river. В результате выводится количество соответствующих документов. Количество соответствующих документов полезно знать при тестировании, когда используется большой индекс с тысячами или миллионами документов. В этом случае только один документ соответствует запросу.
Наконец, введите параметры, ограничивающие результаты поиска полями, интересующими:
```
{
     "search": "river",
     "select": "hotelId, hotelName, baseRate, description",
     "count": true
}
```
Ответ на запрос сокращается до выбранных полей, обеспечивая более точный результат.

Сброс и повторный запуск

На ранних экспериментальных этапах разработки наиболее практический подход к итерации проектирования заключается в удалении объектов из службы "Поиск ИИ Azure" и их перестроении. Имена ресурсов являются уникальными. Удаление объекта позволяет воссоздать его с использованием того же имени.

Пример кода для этого учебника проверяет имеющиеся объекты и удаляет их, чтобы вы могли повторно выполнить код.

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

Очистка ресурсов

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

Ресурсы можно найти и управлять ими в портал Azure, используя ссылку "Все ресурсы" или "Группы ресурсов" в области навигации слева.

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

Теперь, когда вы знакомы с основами индексирования Базы данных SQL, давайте подробнее рассмотрим конфигурацию индексатора.

Настройка индексатора Базы данных SQL

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