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

Статья
02/22/2024

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

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

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

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

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

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

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

 POST https://[service name].search.windows.net/datasources?api-version=2023-11-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, выбрав клавиши Access в области навигации слева. Не забудьте выбрать полную строка подключения и не только ключ.

Управляемое удостоверение строка подключения
`{ "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, запрос такого типа требует просмотра всей таблицы и поэтому выполняется медленно для больших таблиц.

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

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

Например, чтобы создать источник данных для обработки диапазона секций с ключами от 000100, используйте следующий запрос: "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=2023-11-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=2023-11-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,
        "base64EncodeKeys" : null,
        "configuration" : { }
    },
    "fieldMappings" : [ ],
    "cache": null,
    "encryptionKey": null
}

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

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

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

Чтобы отслеживать состояние индексатора и журнал выполнения, отправьте запрос состояния индексатора:

GET https://myservice.search.windows.net/indexers/myindexer/status?api-version=2023-11-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: