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

Узнайте, как настроить indexer для извлечения доступных для поиска данных из База данных SQL Azure и отправки его в индекс поиска в Поиск с использованием ИИ Azure.

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

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

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

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

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

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

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

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

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

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

1. Create Azure SQL database. Важно настроить сервер для базы данных:

   • Выберите параметр проверки подлинности SQL Server, который предложит указать имя пользователя и пароль. Это необходимо для строки подключения ADO.NET, используемой индексатором.

   • Выберите общедоступное подключение, что упрощает выполнение этого руководства. Публичная конфигурация не рекомендуется для использования в рабочей среде, и мы рекомендуем удалить этот ресурс в конце руководства.

   

2. В Azure portal перейдите к новому ресурсу.

3. Добавьте правило брандмауэра, позволяющее доступ от вашего клиента. Чтобы получить IP-адрес, можно запустить ipconfig из командной строки.

4. Используйте Query editor для загрузки примеров данных. В области навигации выберите Query editor (предварительная версия) и введите имя пользователя и пароль администратора сервера.

   Если вы получаете ошибку "доступ запрещен", скопируйте IP-адрес клиента из сообщения об ошибке, откройте страницу безопасности сети для сервера и добавьте правило для входящего трафика, которое позволяет доступ с клиента.

5. В Query editor выберите Open query и перейдите к расположению файла hotels.sql на локальном компьютере.

6. Выберите файл и нажмите кнопку "Открыть". Скрипт должен выглядеть, как на следующем снимке экрана:

   

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

8. Чтобы получить набор строк из этой таблицы, можно выполнить следующий запрос для проверки:

   SELECT * FROM Hotels
   

9. Скопируйте строку подключения ADO.NET для базы данных. В разделе Settings>Connection Strings скопируйте 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. Чтобы завершить работу с этим руководством, можно использовать уровень "Бесплатный".

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

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

1. Перейдите в службу поиска в портал Azure.

2. На странице обзора скопируйте URL-адрес конечной точки. Пример конечной точки может выглядеть как https://mydemo.search.windows.net.

3. В разделе Настройки>Ключи получите ключ администратора для полного доступа в службе. Существуют два взаимозаменяемых ключа администратора, предназначенных для обеспечения непрерывности бизнес-процессов на случай, если вам потребуется сменить один из них. Вы можете использовать либо один из ключей для запросов чтобы добавлять, изменять или удалять объекты.

   

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

1. Запустите Visual Studio и откройте DotNetHowToIndexers.sln.

2. В Обозреватель решений откройте appsettings.json для предоставления сведений о подключении.

3. Для SearchServiceEndPoint, если полный URL страницы службы Overview равен https://my-demo-service.search.windows.net, укажите весь URL.

4. Для 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",
   }
   

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

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

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

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

hotell.cs

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

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

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

В Program.cs

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

Объект источника данных настраивается с параметрами, характерными для ресурсов База данных SQL Azure, включая частичное или инкрементное индексирование для использования встроенных функций обнаружения изменений в Azure SQL. Исходная демонстрационная база данных отелей в Azure SQL содержит столбец "обратимое удаление" с именем 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);
}

Создание решения

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

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

• Сведения о подключении службы поиска, которые вы предоставляете, являются полным URL-адресом. Если вы ввели только имя службы, операции останавливаются при создании индекса с сообщением об ошибке подключения.

• Сведения о подключении к базе данных в appsettings.json. Она должна быть ADO.NET строка подключения, полученная из Azure portal, изменённая для включения допустимых имени пользователя и пароля для вашей базы данных. Учетная запись пользователя должна предоставлять разрешение на получение данных. IP-адрес локального клиента должен быть разрешен для входящего доступа через брандмауэр.

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

Искать

Используйте Azure portal для проверки создания объекта, а затем используйте обозреватель Search для запроса индекса.

1. Перейдите в службу поиска в портал Azure.

2. На левой панели откройте каждую страницу, чтобы проверить создание объектов. Индексы, индексаторы и источники данных должны иметь hotels-sql-idx, hotels-sql-idxr и hotels-sql-ds соответственно.

3. На вкладке Indexes выберите индекс hotels-sql-idx . На странице отелей первая вкладка - это Поиск обозреватель.

4. Выберите "Поиск", чтобы выдать пустой запрос.

   Три записи в вашем индексе возвращаются в виде документов JSON. Проводник поиска возвращает документы в формате JSON, чтобы можно было просматривать всю структуру.

   

5. Перейдите в представление JSON , чтобы можно было ввести параметры запроса.

   {
        "search": "river",
        "count": true
   }
   

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

6. Введите параметры, ограничивающие результаты поиска полями, интересующими вас.

   {
        "search": "river",
        "select": "hotelId, hotelName, baseRate, description",
        "count": true
   }
   

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

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

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

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

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

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

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

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

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

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