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

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

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

Предпосылки

• Хранилище таблиц Azure

• Таблицы, содержащие текст. Если у вас есть двоичные данные, рассмотрите возможность обогащения ИИ для анализа изображений.

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

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

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

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

1. Войдите в портал Azure, перейдите к учетной записи хранения и создайте таблицу с именем отелей.

2. Установите служба хранилища Azure Explorer.

3. Скачайте HotelsData_toAzureSearch.csv из GitHub. Этот файл представляет собой подмножество предустановленного образца данных о гостиницах. Он пропускает коллекцию комнат, переведенные описания и географические координаты.

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

5. Откройте таблицы и выберите отели.

6. Выберите "Импортировать" на панели команд и выберите файл HotelsData_toAzureSearch.csv .

7. Примите значения по умолчанию. Выберите "Импорт" , чтобы загрузить данные.

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

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

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

Мастер импорта данных можно использовать для автоматизации индексирования из таблицы базы данных SQL или представления.

1. Запустите мастер.

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

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

3. Укажите имя учетной записи хранения и таблицы. Запрос необязателен. Это полезно, если у вас есть определенные столбцы, которые вы хотите импортировать.

4. Укажите метод проверки подлинности, управляемое удостоверение или встроенный ключ API. Если вы не указываете подключение управляемой идентификации, портал Azure использует ключ аутентификации.

   Если вы настроите Поиск с использованием ИИ Azure на использование управляемого удостоверения и создадите назначение роли в служба хранилища Azure, предоставляющее этому удостоверению роль Storage Table Data Reader, индексатор сможет подключаться к хранилищу таблиц с помощью Microsoft Entra ID.

5. Можно указать настройки обнаружения удаления.

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

6. Выполните оставшиеся действия , чтобы завершить работу мастера.

Используйте REST API

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

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

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

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

    POST https://[service name].search.windows.net/datasources?api-version=2026-04-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
    }
   

2. Задайте для параметра type "azuretable" (обязательный).

3. Установите значение параметра "credentials" в строку подключения к хранилищу Azure. В следующем разделе описаны поддерживаемые форматы.

4. Присвойте "контейнеру" имя таблицы.

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

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

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

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

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

По умолчанию поиск ИИ 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> запроса, основываясь на значении последнего успешного верхнего предела.

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

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

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

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

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

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

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

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

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

    "fieldMappings" : [
      {
        "sourceFieldName" : "Key",
        "targetFieldName" : "MyDocumentKeyFieldName"
      }
   ]
   

3. Теперь добавьте любые другие поля сущностей, которые вы хотите в индексе. Например, если сущность выглядит следующим образом, индекс поиска должен иметь поля для HotelName, Description и Category для получения этих значений.

   

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

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

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

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

   POST https://[service name].search.windows.net/indexers?api-version=2026-04-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
   }
   

2. Укажите сопоставления полей, если существуют различия в имени или типе поля, или если в индексе поиска требуется несколько версий исходного поля. Целевое поле — это имя поля в индексе поиска.

    "fieldMappings" : [
      {
        "sourceFieldName" : "Description",
        "targetFieldName" : "HotelDescription"
      }
   ]
   

3. Дополнительные сведения о других свойствах см. в статье "Создание индексатора ".

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

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

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

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

• Руководство: Индексирование объектов BLOB JSON из службы хранилища Azure
• Руководство по индексированию зашифрованных Blob-объектов в хранилище Azure