Индексирование данных из Azure Data Lake Storage 2-го поколения

Индексатор Azure Data Lake Storage 2-го поколения импортирует содержимое из Azure Data Lake Storage 2-го поколения (ADLS 2-го поколения) в индекс Поиск с использованием ИИ Azure. Входные данные для индексатора — это блобы, находящиеся в одном контейнере. Выходные данные — это индекс поиска с содержимым, доступным для поиска, и метаданными, хранящимися в отдельных полях.

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

Пример кода на C# см. в разделе Индексирование Озеро данных Gen2 с использованием Microsoft Entra ID на GitHub.

Предпосылки

• ADLS 2-го поколения с включенным иерархическим пространством имен . ADLS 2-го поколения доступен через службу хранилища Azure. При настройке учетной записи хранения у вас есть возможность включить иерархическое пространство имен, упорядочивать файлы в иерархию каталогов и вложенных подкаталогов. Включив иерархическое пространство имен, включите ADLS 2-го поколения.

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

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

  Рассматривать индексирование источника и ИИ-обогащение как отдельные этапы обработки. Навык или внешняя служба могут иметь более низкий предел ввода, чем объем содержимого, который может извлечь индексатор. Проверьте справочную статью для каждого навыка в наборе навыков.

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

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

Ограничения

• В отличие от индексаторов BLOB-объектов, индексаторы ADLS 2-го поколения не могут использовать маркеры SAS уровня контейнера для перечисления и индексирования содержимого из учетной записи хранилища. Это ограничение имеется, поскольку индексатор проверяет, включены ли для учётной записи хранения иерархические пространства имён, путём вызова API Filesystem - Get properties. Для учетных записей, в которых не включено иерархическое пространство имен, используйте вместо этого индексаторы BLOB, чтобы обеспечить высокую производительность при перечислении BLOB-объектов.

• Если свойство metadata_storage_path сопоставлено с полем ключа индекса, переиндексация BLOB не гарантируется при переименовании каталога. Если вы хотите переиндексировать BLOB, которые являются частью переименованных каталогов, обновите LastModified метки времени для всех.

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

Индексатор ADLS 2-го поколения может извлекать текст из следующих форматов документов:

• 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 нужно индексировать

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

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

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

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

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

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

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

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

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

Свойства метаданных, указанные пользователем, извлекаются подробно. Чтобы получить значения, необходимо определить поле в индексе поиска типа Edm.String с тем же именем, что и ключ метаданных BLOB. Например, если 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) — тип контента, указанный в коде, используемом для загрузки двоичного объекта. Например: application/octet-stream.

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

• metadata_storage_size (Edm.Int64) — размер объекта типа BLOB в байтах.

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

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

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

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

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

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

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

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

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

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

4. Задайте "container" для контейнера BLOB-объектов и используйте "запрос", чтобы указать любые вложенные папки.

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

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

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

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

В поисковом индексе добавьте поля для приема содержимого и метаданных объектов Azure Blob.

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

   {
       "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 к этому определению поля.

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

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

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

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

Настройка и запуск индексатора ADLS 2-го поколения

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

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

   {
     "name" : "my-adlsgen2-indexer",
     "dataSourceName" : "my-adlsgen2-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. В разделе "Конфигурация" укажите, какие объекты BLOB индексируются на основе типа файла, или не указывайте, чтобы получить все объекты BLOB.

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

4. В разделе "Конфигурация" задайте значение dataToExtract, чтобы управлять индексированием частей больших двоичных объектов:

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

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

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

5. В разделе "Конфигурация" задайте параметр "parsingMode", если большие двоичные объекты должны быть сопоставлены с несколькими документами поиска, или если они состоят из обычного текста, документов JSON или CSV-файлов.

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

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

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

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

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

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

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":"2024-02-21T00:23:24.957Z",
            "endTime":"2024-02-21T00:36:47.752Z",
            "errors":[],
            "itemsProcessed":1599501,
            "itemsFailed":0,
            "initialTrackingState":null,
            "finalTrackingState":null
        },
        "executionHistory":
        [
            {
                "status":"success",
                "errorMessage":null,
                "startTime":"2024-02-21T00:23:24.957Z",
                "endTime":"2024-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=2026-04-01
{
  "parameters" : { 
    "maxFailedItems" : 10, 
    "maxFailedItemsPerBatch" : 10,
    "configuration" : { 
        "failOnUnsupportedContentType" : false, 
        "failOnUnprocessableDocument" : false,
        "indexStorageMetadataOnlyForOversizedDocuments": false
    }
  }
}

Дальнейшие шаги

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

• Обнаружение изменений и обнаружение удаления
• Индексирование больших наборов данных
• Пример C# : Индексация озера данных Gen2 с использованием Microsoft Entra ID