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

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

В этой статье используются REST API службы поиска для демонстрации настройки и запуска индексатора. Однако вы также можете использовать следующее:

• Пакет Azure SDK (любая версия)
• Мастер импорта данных на портале Azure

Предпосылки

• Хранилище BLOB Azure, стандартная производительность (универсальная версия 2).

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

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

• Поддерживаемая конфигурация сети и доступ к данным. Как минимум, в службе хранилища Azure требуются разрешения на чтение. Строка подключения к хранилищу, включающая ключ доступа, дает права на чтение к содержимому хранилища. Если вы вместо этого используете вход в систему и роли Microsoft Entra, убедитесь, что управляемое удостоверение службы поиска имеет разрешения на чтение данных BLOB-объектов хранилища.

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

• Используйте клиент REST, чтобы сформулировать вызовы REST, аналогичные приведенным в этой статье.

Поддерживаемые задачи

Этот индексатор можно использовать для следующих задач:

• Индексирование и добавочное индексирование данных: индексатор может индексировать файлы и связанные метаданные из BLOB-контейнеров и папок. Он обнаруживает новые и обновленные файлы и метаданные с помощью встроенного обнаружения изменений. Вы можете настроить обновление данных по расписанию или по запросу.
• Обнаружение удаления: индексатор может обнаруживать удаления с помощью родного мягкого удаления или с помощью пользовательских метаданных.
• Применение ИИ с помощью наборов навыков: Индексатор полностью поддерживает наборы навыков. Эта поддержка включает ключевые функции, такие как встроенная векторизация, которая добавляет разбиение данных на сегменты и встраивание.
• Режимы синтаксического анализа: индексатор поддерживает режимы синтаксического анализа JSON, если требуется проанализировать массивы JSON или строки в отдельные документы поиска. Он также поддерживает режим синтаксического анализа Markdown.
• Совместимость с другими функциями: Индексатор легко работает с другими функциями индексатора, такими как сеансы отладки, кэш индексатора для добавочных обогащений и хранилища знаний.

Поддерживаемые форматы документов

Индексатор Blob может извлекать текст из документов следующих форматов:

• CSV (см. раздел индексирование CSV блобов)
• EML
• EPUB
• GZ
• HTML
• JSON (см. индексирование BLOB-объектов JSON);
• KML (XML для географических представлений)
• Markdown (язык разметки)
• Форматы Microsoft Office: DOCX/DOC/DOCM, XLSX/XLSM, PPTX/PPT/PPTM, MSG (outlook emails), XML (как 2003, так и 2006 WORD XML)
• Форматы открытых документов: ODT, ODS, ODP
• Формат pdf
• обычные текстовые файлы (см. также индексирование обычного текста);
• Формат RTF
• XML
• ЗИП

Определите, какие BLOB нужно индексировать.

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

• Поместите объекты blob в виртуальную папку. Определение источника данных индексатора включает query параметр, который может принимать виртуальную папку. Если указать виртуальную папку, индексатор индексирует только те объекты данных (blobs) в папке.

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

• Включите или исключите произвольные большие двоичные объекты. Чтобы пропустить определенный блоб, добавьте следующие свойства и значения метаданных в блобы в хранилище Azure Blob. Когда индексатор обнаруживает это свойство, он пропускает BLOB или его содержимое во время процесса индексирования.

  Название свойства	Значение свойства	Explanation
  AzureSearch_Skip	true	Указывает индексатору больших двоичных объектов пропустить весь большой двоичный объект. Индексатор не пытается извлечь метаданные или содержимое. Это свойство полезно, если определенный BLOB сталкивается с повторяющимися сбоями и прерывает процесс индексирования.
  AzureSearch_SkipContent	true	Индексатор пропускает содержимое и извлекает только метаданные. Это свойство эквивалентно параметру "dataToExtract": "allMetadata" , описанному в параметрах конфигурации, но оно распространяется на определенный большой двоичный объект.

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

Индексатор обычно создает один документ поиска для каждого BLOB, где текстовое содержимое и метаданные фиксируются как поля, доступные для поиска в индексе. Если двоичные объекты являются целыми файлами, их можно разбить на несколько поисковых документов. Например, можно проанализировать строки в CSV-файле, чтобы создать один документ поиска для каждой строки.

Составной или внедренный документ (например, ZIP-архив, документ Word со встроенной электронной почтой Outlook, содержащий вложения или . MSG-файл с вложениями) также индексируется как один документ. Например, все изображения, извлеченные из вложений файла MSG, возвращаются в поле normalized_images. Если у вас есть изображения, попробуйте добавить обогащение ИИ, чтобы улучшить возможности поиска этого контента.

Индексатор извлекает текстовое содержимое документа в строковое поле с именем content. Можно также извлечь стандартные и пользовательские метаданные.

Индексация метаданных BLOB-объектов

Можно также индексировать метаданные объектов blob. Эта функция полезна, если вы считаете, что какие-либо стандартные или настраиваемые свойства метаданных полезны в фильтрах и запросах.

Индексатор извлекает свойства метаданных, указанные пользователем, подробно. Чтобы получить значения, необходимо определить поле в индексе поиска типа Edm.String с тем же именем, что и ключ метаданных BLOB. Например, если большой двоичный объект имеет ключ метаданных Sensitivity со значением High, определите поле с именем Sensitivity в индексе поиска. Поле индекса заполняется значением High.

Вы можете извлечь стандартные свойства метаданных BLOB-объектов в аналогичные именованные и типизированные поля, как показано ниже. Индексатор BLOB-объектов автоматически создает внутренние сопоставления полей для этих свойств метаданных BLOB-объектов, преобразовав исходное дефисированное имя (metadata-storage-name) в символично эквивалентное имя (metadata_storage_name).

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

• metadata_storage_name (Edm.String) — это имя файла BLOB. Например, если у вас есть blob /my-container/my-folder/subfolder/resume.pdf, значение этого поля равно resume.pdf.

• metadata_storage_path (Edm.String) — это полный унифицированный указатель ресурса (URI) blob-объекта, включая учетную запись хранения. Например: https://myaccount.blob.core.windows.net/my-container/my-folder/subfolder/resume.pdf.

• metadata_storage_content_type (Edm.String) — это тип контента, указанный кодом, используемым для загрузки BLOB (большого двоичного объекта). Например: application/octet-stream.

• metadata_storage_last_modified (Edm.DateTimeOffset) — это метка времени последнего изменения для BLOB. Поиск ИИ Azure использует эту метку времени для идентификации измененных BLOB-объектов, чтобы избежать повторного индексирования всего после первоначального индексирования.

• metadata_storage_size (Edm.Int64) — это размер большого двоичного объекта в байтах.

• metadata_storage_content_md5 (Edm.String) — это хэш MD5 содержимого блоба, если он доступен.

• metadata_storage_sas_token (Edm.String) — это временный маркер SAS, который пользовательские навыки могут использовать для получения доступа к объекту BLOB. Не сохраняйте этот маркер для последующего использования, так как срок его действия может истекает.

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

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

В настоящее время индексирование тегов индекса BLOB-объектов не поддерживается этим индексатором.

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

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

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

   {
       "name" : "my-blob-datasource",
       "type" : "azureblob",
       "credentials" : { "connectionString" : "DefaultEndpointsProtocol=https;AccountName=<account name>;AccountKey=<account key>;" },
       "container" : { "name" : "my-container", "query" : "<optional-virtual-directory-name>" }
   }
   

2. Установите type на azureblob (обязательно).

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

4. Задайте контейнер BLOB container, и используйте query для указания вложенных папок.

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

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

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

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

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

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

   POST https://[service name].search.windows.net/indexes?api-version=2025-09-01
   {
       "name" : "my-search-index",
       "fields": [
           { "name": "ID", "type": "Edm.String", "key": true, "searchable": false },
           { "name": "content", "type": "Edm.String", "searchable": true, "filterable": false },
           { "name": "metadata_storage_name", "type": "Edm.String", "searchable": false, "filterable": true, "sortable": true  },
           { "name": "metadata_storage_size", "type": "Edm.Int64", "searchable": false, "filterable": true, "sortable": true  },
           { "name": "metadata_storage_content_type", "type": "Edm.String", "searchable": false, "filterable": true, "sortable": true },        
       ]
   }
   

2. Создайте поле ключа документа ("key": true). Для содержимого BLOB-объектов оптимальный выбор — свойства метаданных.

   • metadata_storage_path (по умолчанию) — это полный путь к объекту или файлу. Поле ключа (ID в этом примере) заполняется значениями из metadata_storage_path, так как это значение по умолчанию.

   • metadata_storage_name доступен только в том случае, если имена уникальны. Если вы хотите, чтобы это поле было ключом, перейдите "key": true к этому определению поля.

   • Настраиваемое свойство метаданных, которое добавляется в объекты BLOB. Для этого варианта требуется, чтобы процесс загрузки добавлял это свойство метаданных ко всем объектам. Так как ключ является обязательным свойством, все большие двоичные объекты, у которых отсутствует значение, не индексируются. При использовании настраиваемого свойства метаданных в качестве ключа следует избегать внесения изменений в это свойство. Индексаторы добавляют повторяющиеся документы для одного большого двоичного объекта, если свойство ключа изменяется.

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

3. content Добавьте поле для хранения извлеченного текста из каждого файла через свойство content блоба. Вам не требуется использовать это имя, но с его помощью можно воспользоваться неявными сопоставлениями полей.

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

Настройка и запуск индексатора BLOB-объектов

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

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

   POST https://[service name].search.windows.net/indexers?api-version=2025-09-01
   {
     "name" : "my-blob-indexer",
     "dataSourceName" : "my-blob-datasource",
     "targetIndexName" : "my-search-index",
     "parameters": {
         "batchSize": null,
         "maxFailedItems": null,
         "maxFailedItemsPerBatch": null,
         "configuration": {
             "indexedFileNameExtensions" : ".pdf,.docx",
             "excludedFileNameExtensions" : ".png,.jpeg",
             "dataToExtract": "contentAndMetadata",
             "parsingMode": "default"
         }
     },
     "schedule" : { },
     "fieldMappings" : [ ]
   }
   

2. Установите значение batchSize , если значение по умолчанию (10 документов) недоиспользует или перегрузит доступные ресурсы. Размеры пакетов по умолчанию зависят от источника данных. Для индексирования объектов BLOB размер партии устанавливается в 10 документов, учитывая увеличенный средний размер документа.

3. В configuration укажите, какие BLOB индексировать по типу файла, или оставьте это неуточнённым, чтобы извлечь все BLOB.

   Для indexedFileNameExtensions, укажите разделенный запятыми список расширений файлов (с точкой). Выполните то же самое для excludedFileNameExtensions, чтобы указать, какие расширения индексатору следует пропустить. Если одно и то же расширение находится в обоих списках, индексатор исключает его из индексирования.

4. Установите configuration в dataToExtract, чтобы управлять индексированием частей блобов.

   • contentAndMetadata указывает, что индексатор индексирует все метаданные и текстовое содержимое, извлеченные из Blob. Это значение по умолчанию.

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

   • allMetadata указывает, что индексатор извлекает из содержимого BLOB-объектов и индексирует стандартные свойства BLOB-объектов и все метаданные для найденных типов контента.

5. В разделе configuration, установите parsingMode. Режим парсинга по умолчанию — один документ поиска на каждый blob. Если большие двоичные объекты являются обычным текстом, можно повысить производительность, переключившись на синтаксический анализ обычного текста . Если требуется более детализированный анализ, который сопоставляет большие двоичные объекты с несколькими документами поиска, укажите другой режим. Синтаксический анализ "один ко многим" поддерживается для больших двоичных объектов, состоящих из следующих:

   • Документы JSON
   • CSV-файлы

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

   В индексировании BLOB часто можно опустить сопоставления полей, поскольку индексатор имеет встроенную возможность для сопоставления content и свойств метаданных с аналогично названными и типизированными полями в индексе. Для свойств метаданных индексатор автоматически заменяет дефисы символами - подчеркивания в индексе поиска.

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

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

Индексирование данных из нескольких контейнеров BLOB-объектов Azure в один индекс

Помните, что индексатор может индексировать только данные из одного контейнера. Если необходимо индексировать данные из нескольких контейнеров и объединить их в один индекс поиска ИИ, настройте несколько индексаторов, указывающих на один индекс. Помните о максимальном количестве индексаторов, доступных на артикул SKU.

Например, можно использовать два индексаторов для извлечения данных из двух разных источников данных с именем my-blob-datasource1 и my-blob-datasource2. Каждый источник данных указывает на отдельный контейнер BLOB-объектов Azure, но оба направляются к одному индексу с именем my-search-index.

Первый пример определения индексатора:

POST https://[service name].search.windows.net/indexers?api-version=2025-09-01
{
  "name" : "my-blob-indexer1",
  "dataSourceName" : "my-blob-datasource1",
  "targetIndexName" : "my-search-index",
  "parameters": {
      "batchSize": null,
      "maxFailedItems": null,
      "maxFailedItemsPerBatch": null,
      "configuration": {
          "indexedFileNameExtensions" : ".pdf,.docx",
          "excludedFileNameExtensions" : ".png,.jpeg",
          "dataToExtract": "contentAndMetadata",
          "parsingMode": "default"
      }
  },
  "schedule" : { },
  "fieldMappings" : [ ]
}

Второе определение индексатора, которое выполняется в параллельном примере:

POST https://[service name].search.windows.net/indexers?api-version=2025-09-01
{
  "name" : "my-blob-indexer2",
  "dataSourceName" : "my-blob-datasource2",
  "targetIndexName" : "my-search-index",
  "parameters": {
      "batchSize": null,
      "maxFailedItems": null,
      "maxFailedItemsPerBatch": null,
      "configuration": {
          "indexedFileNameExtensions" : ".pdf,.docx",
          "excludedFileNameExtensions" : ".png,.jpeg",
          "dataToExtract": "contentAndMetadata",
          "parsingMode": "default"
      }
  },
  "schedule" : { },
  "fieldMappings" : [ ]
}

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

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

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

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

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

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

Управление ошибками

Некоторые распространенные ошибки, которые возникают при индексировании: неподдерживаемые типы содержимого, отсутствующее содержимое или слишком большие двоичные объекты.

По умолчанию индексатор BLOB останавливается при обнаружении объекта BLOB с неподдерживаемым типом контента (например, звуковым файлом). Параметр можно использовать excludedFileNameExtensions для пропуска определенных типов контента. Однако индексирование может потребоваться продолжить, даже если возникают ошибки, а затем отлаживать отдельные документы позже. Дополнительные сведения об ошибках индексатора см. в разделах Руководство по устранению проблем с индексатором и Ошибки и предупреждения индексатора.

При возникновении ошибок пять параметров индексатора управляют ответом индексатора:

PUT /indexers/[indexer name]?api-version=2025-09-01
{
  "parameters" : { 
    "maxFailedItems" : 10, 
    "maxFailedItemsPerBatch" : 10,
    "configuration" : { 
        "failOnUnsupportedContentType" : false, 
        "failOnUnprocessableDocument" : false,
        "indexStorageMetadataOnlyForOversizedDocuments": false
      }
    }
}

Связанный контент

• Обнаружение изменений и обнаружение удаления
• Индексирование больших наборов данных
• Доступ индексатора к содержимому, защищенному функциями безопасности сети Azure