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

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

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

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

Prerequisites

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

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

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

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

Limitations

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

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

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

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

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

  • Навык запроса GenAI

  • Хранилище знаний

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

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

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

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

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

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

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

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

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

/ 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 в ADLS Gen2.

Authorization

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

Если вы тестируете локально, у вас также должно быть назначение роли читателя данных 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

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

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

Authorization

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

Если вы тестируете локально, то у вас должны быть такие же распределения ролей. Дополнительные сведения см. в статье "Подключение к поиску ИИ Azure" с помощью ролей.

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

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

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

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

# Create / Update Azure Blob Knowledge Source
###
PUT {{url}}/knowledgesources/azure-blob-ks?api-version=2025-11-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-го поколения.

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

Этот раздел дополняет данные индекса из ADLS 2-го поколения информацией, касающейся включения разрешений и содержимого документа в поисковый индекс Azure AI.

• Тип источника данных должен быть 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 со значением rbacScope permissionFilter.
• Свойство 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 Gen2 может потребоваться сопоставление полей.

• 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=2025-11-01-preview 
{ 
  "documentKeys": [ 
    "1001", 
    "4452" 
  ]
}

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

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

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

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

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

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