Индексирование данных из Хранилища таблиц Azure

Статья
11/23/2024

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

В этой статье описано , как создать индексатор со сведениями, которые относятся к индексации из хранилища таблиц Azure. В нем используются портал Azure и REST API для демонстрации трех частей рабочего процесса, общего для всех индексаторов: создание источника данных, создание индекса, создание индексатора. Извлечение данных происходит при отправке запроса create Indexer.

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

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

Для работы с примерами, приведенными в этой статье, вам потребуется портал Azure или клиент REST. Если вы используете портал Azure, убедитесь, что доступ ко всем общедоступным сетям включен. Другие подходы к созданию индексатора таблиц Azure включают пакеты SDK Azure.

Попробуйте использовать примеры данных

Используйте эти инструкции для создания таблицы в служба хранилища Azure для тестирования.

Войдите в портал Azure, перейдите к учетной записи хранения и создайте таблицу с именем отелей.
Установите служба хранилища Azure Explorer.
Скачайте HotelsData_toAzureSearch.csv из GitHub. Этот файл представляет собой подмножество встроенного набора данных для отелей. Он окупит коллекцию комнат, переведенные описания и географические координаты.
В обозревателе служба хранилища Azure войдите в Azure, выберите подписку и выберите учетную запись хранения.
Откройте таблицы и выберите отели.
Выберите "Импортировать" на панели команд и выберите файл HotelsData_toAzureSearch.csv .
Примите значения по умолчанию. Выберите "Импорт" , чтобы загрузить данные.

В таблице должно быть 50 записей отеля с автоматически созданным секционированием, rowKey и меткой времени. Теперь вы можете использовать это содержимое для индексирования в портал Azure, клиенте REST или пакете SDK Azure.

Поле "Описание" предоставляет наиболее подробное содержимое. Это поле должно быть предназначено для полнотекстового поиска и необязательных векторных запросов.

Использование портала Azure

С помощью мастера импорта данных или мастера импорта и векторизации данных можно автоматизировать индексирование из таблицы базы данных SQL или представления. Конфигурация источника данных аналогична обоим мастерам.

Запустите мастер.
При подключении к данным выберите или убедитесь, что тип источника данных — хранилище таблиц Azure или поля выбора данных запрашивают таблицы.

Имя источника данных ссылается на объект подключения к источнику данных в службе "Поиск ИИ Azure". При использовании мастера векторов имя источника данных автоматически создается с помощью настраиваемого префикса, указанного в конце рабочего процесса мастера.
Укажите имя учетной записи хранения и таблицы. Запрос необязателен. Это полезно, если у вас есть определенные столбцы, которые вы хотите импортировать.
Укажите метод проверки подлинности, управляемое удостоверение или встроенный ключ API. Если подключение к управляемому удостоверению не указано, портал использует ключ.

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

Для обнаружения удаления требуется, чтобы у вас было предварительно существующее поле в таблице, которое можно использовать в качестве флага обратимого удаления. Это должно быть логическое поле (можно назвать его IsDeleted). Укажите true в качестве значения обратимого удаления. В индексе поиска добавьте соответствующее поле поиска с именем IsDeleted , чтобы получить и отфильтровать его.
Выполните оставшиеся действия, чтобы завершить работу мастера:
- Краткое руководство. Мастер импорта данных
- Краткое руководство. Мастер импорта и векторизации данных

использованию REST API

В этом разделе показаны вызовы REST API, которые создают источник данных, индекс и индексатор.

Определение источника данных

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

Создайте или обновите источник данных, чтобы задать его определение:

 POST https://[service name].search.windows.net/datasources?api-version=2024-07-01 
 {
     "name": "my-table-storage-ds",
     "description": null,
     "type": "azuretable",
     "subtype": null,
     "credentials": {
        "connectionString": "DefaultEndpointsProtocol=https;AccountName=<account name>"
     },
     "container": {
        "name": "my-table-in-azure-storage",
        "query": ""
     },
     "dataChangeDetectionPolicy": null,
     "dataDeletionDetectionPolicy": null,
     "encryptionKey": null,
     "identity": null
 }

Задайте для параметра type "azuretable" (обязательный).
Задайте для параметра "Учетные данные" значение служба хранилища Azure строка подключения. В следующем разделе описаны поддерживаемые форматы.
Присвойте "контейнеру" имя таблицы.
При необходимости задайте параметр "query" фильтру в PartitionKey. Установка этого свойства — это рекомендация, которая повышает производительность. Если "query" имеет значение NULL, индексатор выполняет полную проверку таблицы, что может привести к низкой производительности, если таблицы большие.

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

Поддерживаемые учетные данные и строка подключения

Индексаторы могут подключаться к таблице с помощью следующих подключений.

Строка подключения учетной записи хранения полного доступа
`{ "connectionString" : "DefaultEndpointsProtocol=https;AccountName=<your storage account>;AccountKey=<your account key>;" }`
Вы можете получить строка подключения на странице учетной записи хранения в портал Azure, выбрав ключи доступа в области навигации слева. Не забудьте выбрать полную строка подключения и не только ключ.

Управляемое удостоверение строка подключения
`{ "connectionString" : "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.Storage/storageAccounts/<your storage account name>/;" }`
Для этого строка подключения не требуется ключ учетной записи, но необходимо ранее настроить службу поиска для подключения с помощью управляемого удостоверения.

Подписанный URL-адрес учетной записи хранения** (SAS) строка подключения
`{ "connectionString" : "BlobEndpoint=https://<your account>.blob.core.windows.net/;SharedAccessSignature=?sv=2016-05-31&sig=<the signature>&spr=https&se=<the validity end time>&srt=co&ss=b&sp=rl;" }`
SAS должен иметь список и разрешения на чтение для таблиц и сущностей.

Подписанный URL-адрес контейнера
`{ "connectionString" : "ContainerSharedAccessUri=https://<your storage account>.blob.core.windows.net/<container name>?sv=2016-05-31&sr=c&sig=<the signature>&se=<the validity end time>&sp=rl;" }`
Подписанный URL-адрес должен иметь разрешения "Список" и "Чтение" для контейнера. Дополнительные сведения см. в разделе "Использование подписанных URL-адресов".

Примечание.

Если вы используете учетные данные SAS, необходимо периодически обновлять учетные данные источника данных с обновленными подписями, чтобы предотвратить их истечение срока действия. При истечении срока действия учетных данных SAS индексатор завершится ошибкой, аналогичной "Учетные данные, предоставленные в строка подключения, являются недействительными или истекли".

Секционирование для повышения производительности

По умолчанию поиск ИИ Azure использует следующий внутренний фильтр запросов, чтобы отслеживать, какие исходные сущности были обновлены с момента последнего выполнения. Timestamp >= HighWaterMarkValue Поскольку в таблицах Azure отсутствует вторичный индекс в поле Timestamp, запрос такого типа требует просмотра всей таблицы и поэтому выполняется медленно для больших таблиц.

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

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

Например, чтобы создать источник данных для обработки диапазона секций с ключами от 000 100, используйте следующий запрос: "container" : { "name" : "my-table", "query" : "PartitionKey ge '000' and PartitionKey lt '100' " }
Если данные секционируются по времени (например, если вы создаете новую секцию каждый день или неделю), рассмотрите следующий подход:
- В определении источника данных укажите запрос, аналогичный следующему примеру: (PartitionKey ge <TimeStamp>) and (other filters)
- Отслеживайте работу индексатора с помощью API получения сведений о состоянии индексатора и периодически обновляйте условие <TimeStamp> запроса, основываясь на значении последнего успешного верхнего предела.
- При таком подходе, если необходимо активировать полный переиндекс, сбросьте запрос источника данных в дополнение к сбросу индексатора.

Добавление полей поиска в индекс

В индексе поиска добавьте поля, чтобы принять содержимое и метаданные сущностей таблицы.

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

POST https://[service name].search.windows.net/indexes?api-version=2024-07-01 
{
  "name" : "my-search-index",
  "fields": [
    { "name": "Key", "type": "Edm.String", "key": true, "searchable": false },
    { "name": "SomeColumnInMyTable", "type": "Edm.String", "searchable": true }
  ]
}

Создайте поле ключа документа ("key": true"), но разрешите индексатору автоматически заполнять его. Индексатор таблицы заполняет поле ключа объединенными разделами и ключами строк из таблицы. Например, если строка partitionKey имеет 1 значение RowKey и RowKey 1_123, значение ключа — 11_123это значение. Если ключ секции имеет значение NULL, используется только ключ строки.

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

Если вы используете ИНТЕРФЕЙСы REST API и хотите неявное сопоставление полей, создайте и присвойте ей имя поля ключа документа "Ключ" в определении индекса поиска, как показано на предыдущем шаге ({ "name": "Key", "type": "Edm.String", "key": true, "searchable": false }). Индексатор автоматически заполняет поле "Ключ" без обязательных сопоставлений полей.

Если поле с именем "Ключ" в индексе поиска не требуется, добавьте явное сопоставление полей в определении индексатора с нужным именем поля, присвойте исходному полю значение Key:
```
 "fieldMappings" : [
   {
     "sourceFieldName" : "Key",
     "targetFieldName" : "MyDocumentKeyFieldName"
   }
]
```
Теперь добавьте любые другие поля сущностей, которые вы хотите в индексе. Например, если сущность выглядит следующим образом, индекс поиска должен иметь поля для HotelName, Description и Category для получения этих значений.

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

Настройка и запуск индексатора таблиц

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

Создайте или обновите индексатор , предоставив ему имя и ссылаясь на источник данных и целевой индекс:

POST https://[service name].search.windows.net/indexers?api-version=2024-07-01
{
    "name" : "my-table-indexer",
    "dataSourceName" : "my-table-storage-ds",
    "targetIndexName" : "my-search-index",
    "disabled": null,
    "schedule": null,
    "parameters" : {
        "batchSize" : null,
        "maxFailedItems" : null,
        "maxFailedItemsPerBatch" : null,
        "configuration" : { }
    },
    "fieldMappings" : [ ],
    "cache": null,
    "encryptionKey": null
}

Укажите сопоставления полей, если существуют различия в имени или типе поля, или если в индексе поиска требуется несколько версий исходного поля. Целевое поле — это имя поля в индексе поиска.
```
 "fieldMappings" : [
   {
     "sourceFieldName" : "Description",
     "targetFieldName" : "HotelDescription"
   }
]
```
Дополнительные сведения о других свойствах см. в статье "Создание индексатора ".

Индексатор запускается автоматически при его создании. Это можно предотвратить, задав для параметра "Отключено" значение true. Чтобы управлять выполнением индексатора, запустите индексатор по запросу или поместите его в расписание.

Проверка состояния индексатора

Чтобы отслеживать состояние индексатора и журнал выполнения, проверьте журнал выполнения индексатора в портал Azure или отправьте REST APIrequest состояния индексатора.

Портал
REST

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

GET https://myservice.search.windows.net/indexers/myindexer/status?api-version=2024-07-01
  Content-Type: application/json  
  api-key: [admin key]

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

    {
        "status":"running",
        "lastResult": {
            "status":"success",
            "errorMessage":null,
            "startTime":"2023-02-21T00:23:24.957Z",
            "endTime":"2023-02-21T00:36:47.752Z",
            "errors":[],
            "itemsProcessed":1599501,
            "itemsFailed":0,
            "initialTrackingState":null,
            "finalTrackingState":null
        },
        "executionHistory":
        [
            {
                "status":"success",
                "errorMessage":null,
                "startTime":"2023-02-21T00:23:24.957Z",
                "endTime":"2023-02-21T00:36:47.752Z",
                "errors":[],
                "itemsProcessed":1599501,
                "itemsFailed":0,
                "initialTrackingState":null,
                "finalTrackingState":null
            },
            ... earlier history items
        ]
    }

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

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

Узнайте больше о том, как запустить индексатор, отслеживать состояние или запланировать выполнение индексатора. Следующие статьи относятся к индексаторам, которые извлекает содержимое из служба хранилища Azure:

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