Использование индексатора ADLS 2-го поколения для приема метаданных разрешений и фильтрации результатов поиска на основе прав доступа пользователей (предварительная версия)

Azure Data Lake Storage (ADLS) Gen2 поддерживает доступ к каталогам и файлам с помощью списков управления доступом (ACLs) и управления доступом на основе ролей (Azure RBAC). Контроль доступа на основе атрибутов (Azure ABAC) не поддерживается.

Поиск с использованием ИИ Azure может получать эти метаданные разрешений (предварительная версия) вместе с содержимым документа с помощью REST API предварительной версии. Пользователи, не имеющие доступа к каталогу или файлу в хранилище, не видят соответствующие документы в результатах поиска. Это одна из нескольких стратегий для управления доступом на уровне документа в Поиск с использованием ИИ Azure.

В этой статье объясняется, как настроить индексатор ADLS 2-го поколения или источник знаний BLOB-объектов ADLS 2-го поколения для автоматического извлечения метаданных разрешений в индекс поиска. Он дополняет данные индекса из ADLS 2-го поколения и создание источника знаний BLOB-объектов для ADLS 2-го поколения с информацией, относяющейся к приему разрешений. Для ручной отправки метаданных разрешений см. индексацию ACL документов с использованием API push.

Необходимые условия

• Аутентификация и авторизация Microsoft Entra ID. Службы и приложения должны находиться в одном клиенте. Пользователи могут находиться в разных арендаторах, если все арендаторы используют Microsoft Entra ID. Назначения ролей используются для каждого аутентифицированного соединения.

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

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

• REST API версии 2025-05-01-preview или более поздней для приема разрешений индексатора. REST API версии 2025-11-01-preview или более поздней версии для поддержки источников знаний. Используйте последнюю предварительную версию REST API или пакет пакета SDK для предварительной версии, поддерживающий фильтры разрешений.

Ограничения

• Портал Azure не поддерживает эту функцию.

• Ограничения ADLS 2-го поколения для назначений ролей и записей ACL применяются.

• Категории удостоверений ACL owning users, owning groups и Other (all) не поддерживаются во время предварительного просмотра. Вместо этого используйте named users и named groups присвоения.

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

  • Навык пользовательского веб-API

  • Хранилище знаний, включая хранилище ресурсов, необходимое для обслуживания изображений (предварительная версия) в агентическом извлечении. Поэтому выдача изображений не поддерживается для источников знаний, которые используют ACL или области действия RBAC.

  • Кэш обогащения индексатора

  • Сеансы отладки

Поддержка модели разрешений

В этом разделе сравниваются функции управления доступом на уровне документа между ADLS 2-го поколения и Поиск с использованием ИИ Azure. В нем объясняется, какие механизмы управления доступом Azure Data Lake Storage (ADLS) Gen2 поддерживает или сопоставляет AI Search. Это помогает понять, как применяются разрешения на уровне документа.

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

Сведения о иерархических разрешениях ACL

Индексаторы и источники знаний могут получать назначения ACL из указанного контейнера и всех каталогов, ведущих к каждому файлу, следуя потоку оценки иерархического доступа ADLS 2-го поколения. Окончательные действующие списки доступа для каждого файла вычисляются, а различные категории доступа индексируются в соответствующие поля индекса.

Например, в ADLS 2-го поколения распространенные сценарии, связанные с разрешениями в качестве пути к файлу /Oregon/Portland/Data.txt.

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

/ assigned access vs Oregon/ assigned access
  => Oregon/ effective access vs Portland/ assigned access
    => Portland/ effective access vs Data.txt assigned access
      => Data.txt effective access

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

Индексатор или источник знаний может получить списки управления доступом (ACL) в учётной записи хранилища, если выполнены следующие критерии. Для получения дополнительной информации о назначениях ACL, см. назначения ACL для ADLS Gen2.

Авторизация

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

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

Разрешения корневого контейнера:

1. Назначьте все наборы Group и User (субъекты безопасности) в корневом контейнере / с разрешениями Read и Execute.

2. Убедитесь, что и Read, и Execute добавляются в качестве разрешений по умолчанию, чтобы они автоматически распространялись на вновь созданные файлы и каталоги.

Распространение разрешений вниз иерархии файлов

Хотя новые каталоги и файлы наследуют разрешения, существующие каталоги и файлы не наследуют их автоматически.

Используйте средство ADLS 2-го поколения для рекурсивного применения списков управления доступом для распространения назначений на существующее содержимое. Это средство распространяет назначения ACL корневого контейнера ко всем базовым каталогам и файлам.

Удаление избыточных разрешений

После рекурсивного применения списков управления доступом просмотрите разрешения для каждого каталога и файла.

Удалите любые Group или User наборы, которые не должны иметь доступа к определенным каталогам или файлам. Например, удалите User2 из папки Portland/, а для папки Idaho удалите Group2 и User2 из ее назначений и так далее.

Пример структуры назначений ACL

Ниже приведена схема структуры назначения ACL для вымышленной иерархии каталогов в документации ADLS 2-го поколения.

Обновление назначений ACL с течением времени

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

Настройка Поиск с использованием ИИ Azure

Помните, что служба поиска должна иметь следующее:

• Включен доступ на основе ролей
• Управляемое удостоверение настроено

Авторизация

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

Если вы тестируете локально, у вас должно быть то же распределение ролей. Дополнительные сведения см. в разделе Connect to Поиск с использованием ИИ Azure using roles.

Настройка источника знаний

Если вы используете источник знаний, определения в источнике знаний используются для создания полного конвейера индексирования (индексатора, источника данных и индекса). Назначения ACL обнаруживаются и автоматически включаются в созданный индекс. Если требуется наследование разрешений в индексируемом содержимом, не нужно изменять какие-либо созданные объекты.

Ключевые моменты конфигурации, которые делают это работоспособным для этого сценария:

• isADLSGen2 имеет значение true, что соответствует требованию источника данных для этого сценария.
• ingestionPermissionOptions указывает идентификаторы пользователей и групп.

# Create / Update Azure Blob Knowledge Source
###
PUT {{url}}/knowledgesources/azure-blob-ks?api-version=2026-08-01-preview
api-key: {{key}}
Content-Type: application/json
 
{
    "name": "azure-blob-ks",
    "kind": "azureBlob",
    "description": "A sample azure blob knowledge source",
    "azureBlobParameters": {
        "connectionString": "{{blob-connection-string}}",
        "containerName": "blobcontainer",
        "folderPath": null,
        "isADLSGen2": true,
        "ingestionParameters": {
            "identity": null,
            "embeddingModel": {
                "kind": "azureOpenAI",
                "azureOpenAIParameters": {
                    "deploymentId": "text-embedding-3-large",
                    "modelName": "text-embedding-3-large",
                    "resourceUri": "{{aoai-endpoint}}",
                    "apiKey": "{{aoai-key}}"
                }
            },
            "chatCompletionModel": null,
            "disableImageVerbalization": true,
            "ingestionSchedule": null,
             "ingestionPermissionOptions": [
                "userIds","groupIds"
                           ],
            "contentExtractionMode": "minimal",
            "aiServices": {
                "uri": "{{ai-endpoint}}",
                "apiKey": "{{ai-key}}"
            }
        }
    }
}
###

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

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

Создание источника данных

Этот раздел дополняет данные Index из ADLS 2-го поколения сведениями, которые относятся к приему разрешений вместе с содержимым документа в индекс Поиск с использованием ИИ Azure.

• Тип источника данных должен быть adlsgen2.

• Источник данных должен иметь indexerPermissionOptions, userIds, groupIds и/или rbacScope.

  • Для rbacScope настройте строку подключения в формате управляемого удостоверения.

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

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

{
    "name" : "my-adlsgen2-acl-datasource",
    "type": "adlsgen2",
    "indexerPermissionOptions": ["userIds", "groupIds", "rbacScope"],
    "credentials": {
    "connectionString": "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.Storage/storageAccounts/<your storage account name>/;"
    },
    "container": {
    "name": "<your container name>",
    "query": "<optional-virtual-directory-name>"
    }
}

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

{
    "name" : "my-adlsgen2-acl-datasource",
    "type": "adlsgen2",
    "indexerPermissionOptions": ["userIds", "groupIds", "rbacScope"],
    "credentials": {
    "connectionString": "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.Storage/storageAccounts/<your storage account name>/;"
    },
    "container": {
    "name": "<your container name>",
    "query": "<optional-virtual-directory-name>"
    },
    "identity": {
    "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
    "userAssignedIdentity": "/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{user-assigned-managed-identity-name}"
    }
}

Создание полей разрешений в индексе

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

Рекомендуемые атрибуты схемы для ACL (UserIds, GroupIds) и области RBAC:

• Поле идентификатора пользователя (ID) со userIds значением permissionFilter.
• Поле идентификаторов групп с groupIds значением permissionFilter.
• Поле области RBAC со значением permissionFilter rbacScope.
• Свойство permissionFilterOption для включения фильтрации во время запроса.
• Использование строковых полей для метаданных разрешений
• Задайте filterable значение true для всех полей.

Обратите внимание, что retrievable имеет значение «ложь». Вы можете задать значение true во время разработки, чтобы проверить наличие разрешений, но не забудьте вернуть значение false перед развертыванием в рабочей среде.

Пример схемы JSON:

{
  ...
  "fields": [
    ...
    { "name": "UserIds", "type": "Collection(Edm.String)", "permissionFilter": "userIds", "filterable": true, "retrievable": false },
    { "name": "GroupIds", "type": "Collection(Edm.String)", "permissionFilter": "groupIds", "filterable": true, "retrievable": false },
    { "name": "RbacScope", "type": "Edm.String", "permissionFilter": "rbacScope", "filterable": true, "retrievable": false }
  ],
  "permissionFilterOption": "enabled"
}

Настройка индексатора

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

• metadata_user_ids (Collection(Edm.String)) — список идентификаторов пользователей ACL.
• metadata_group_ids (Collection(Edm.String)) — список идентификаторов групп ACL.
• metadata_rbac_scope (Edm.String) — область контейнера RBAC.

Укажите fieldMappings в индексаторе, чтобы перенаправить метаданные разрешений в целевые поля во время индексирования.

Пример схемы JSON:

{
  ...
  "fieldMappings": [
    { "sourceFieldName": "metadata_user_ids", "targetFieldName": "UserIds" },
    { "sourceFieldName": "metadata_group_ids", "targetFieldName": "GroupIds" },
    { "sourceFieldName": "metadata_rbac_scope", "targetFieldName": "RbacScope" }
  ]
}

Рекомендации и передовой опыт

• Тщательно спланируйте структуру папок ADLS 2-го поколения перед созданием папок.

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

Синхронизируйте разрешения между индексированным и исходным содержимым.

Включение обогащения ACL или RBAC на индексаторе работает автоматически только в двух ситуациях:

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

• Совершенно новые документы, добавленные после включения поддержки ACL/RBAC: их информация ACL/RBAC интегрируется вместе с их содержимым.

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

Выберите один из следующих механизмов в зависимости от количества измененных элементов:

Пример API Resetdocs (предварительная версия):

POST https://{service}.search.windows.net/indexers/{indexer}/resetdocs?api-version=2026-08-01-preview
{ 
  "documentKeys": [ 
    "1001", 
    "4452" 
  ]
}

Пример API повторной синхронизации (предварительная версия):

POST https://{service}.search.windows.net/indexers/{indexer}/resync?api-version=2026-08-01-preview
{ 
  "options": [ 
    "permissions" 
  ] 
} 

Отслеживание удаления

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

Связанное содержимое

• Подключение к Поиск с использованием ИИ Azure с использованием ролей
• Применение ACL и RBAC в момент выполнения запроса
• azure-search-python-samples/Quickstart-Document-Permissions-Push-API