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

Узнайте, как настроить индексатор для извлечения данных, доступных для поиска, из базы данных 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 AI Search использует плоские наборы строк, например тот, который создан с помощью представления или запроса. При помощи файла SQL в примере решения создается и заполняется одна таблица.

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

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

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

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

   

2. На портале Azure войдите в новый ресурс.

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

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

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

5. В редакторе запросов выберите "Открыть запрос " и перейдите к расположению hotels.sql файла на локальном компьютере.

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

   

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

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

   SELECT * FROM Hotels
   

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

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

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

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

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

   

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

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

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

3. Если SearchServiceEndPointполный URL-адрес на странице обзора службы указан 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

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

Объект источника данных настраивается с параметрами, характерными для База данных 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);
}

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

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

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

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

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

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

Искать

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

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

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

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

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

   

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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