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

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

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

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

Предпосылки

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

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

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

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

• Поддерживаемая конфигурация сети и доступ к данным. Как минимум, в службе хранилища 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-объектов можно индексировать вместе с содержимым. Индексатор извлекает свойства метаданных и сохраняет их в полях индекса, что полезно для создания фильтров и запросов.

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

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

Стандартные свойства метаданных BLOB-объектов

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

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

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

• 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. Используйте это свойство для включения URL-адресов blob в результаты поиска для навигации или атрибуции источника.

• 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-объекта определите поле с именем, в точности совпадающим с ключом метаданных BLOB-объекта. Например, если у ваших BLOB-объектов есть ключ метаданных Sensitivity со значением High, определите в индексе поле с именем Sensitivity типа Edm.String.

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

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

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

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. В следующем разделе описаны поддерживаемые форматы.

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

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

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

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

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

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

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

   POST https://[service name].search.windows.net/indexes?api-version=2026-04-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=2026-04-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=2026-04-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=2026-04-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=2026-04-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 наиболее недавно завершенных заданий. Записи сортируются в обратном хронологическом порядке, поэтому последнее выполнение выполняется в первую очередь.

Troubleshooting

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

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

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

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

2. Используйте правильное имя поля: Для стандартных свойств BLOB-объектов используйте символ подчеркивания, например metadata_storage_path вместо metadata-storage-path. Для пользовательских метаданных имя поля должно точно совпадать с ключом метаданных BLOB-объекта.

3. Убедитесь, что индексатор dataToExtract правильно задан:

   • contentAndMetadata (по умолчанию) извлекает содержимое и стандартные или пользовательские метаданные.
   • storageMetadata извлекает только стандартные свойства BLOB-объектов и пользовательские метаданные.
   • allMetadata извлекает стандартные свойства, а также метаданные, относящиеся к типу контента.

   Проверьте конфигурацию индексатора, чтобы убедиться, что параметр соответствует вашему намерению.

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

5. Проверьте журнал выполнения индексатора: Перейдите на страницу индексатора на портале Azure или используйте Get Indexer Status (REST API), чтобы просмотреть сведения о выполнении и все сообщения об ошибках.

Сбои индексатора и неподдерживаемые типы контента

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

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

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

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

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

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