Руководство: индексирование метаданных разрешений из ADLS Gen2 и выполнение запроса с результатами, отфильтрованными по разрешениям (предварительная версия)

В этом руководстве демонстрируется приём метаданных разрешений Azure Data Lake Storage (ADLS) Gen2 (предварительная версия), при котором индексатор Поиск с использованием ИИ Azure добавляет в поисковый индекс списки управления доступом (ACL) и сведения об области действия управления доступом на основе ролей (RBAC).

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

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

В этом руководстве описано, как:

Используйте клиент REST для выполнения этого руководства и последней предварительной версии REST API. В настоящее время на портале Azure нет поддержки индексирования ACL.

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

• Учетная запись Azure с активной подпиской. Создайте учетную запись бесплатно.

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

• ADLS 2-го поколения с иерархическим пространством имен.

• Файлы в иерархической структуре папок. В этом руководстве предполагается демонстрация структуры папок ADLS 2-го поколения для файла /Oregon/Portland/Data.txt. В этом руководстве описано назначение ACL для папок и файлов, чтобы выполнить упражнение успешно.

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

• Visual Studio Code с расширением клиента REST.

Подготовка примеров данных

Загрузите примеры данных государственных парков в контейнер в ADLS Gen2. Имя контейнера должно быть "парки", и в нём должно быть две папки: "Орегон" и "Вашингтон".

Проверка конфигурации службы поиска

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

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

• Настройте управляемое удостоверение, назначаемое системой.

Получить токен личных данных для локального тестирования

В этом руководстве предполагается, что клиент REST в локальной системе подключается к Azure через общедоступное подключение к Интернету.

Follow эти действия для получения маркера личного удостоверения и настройки Visual Studio Code для локальных подключений к ресурсам Azure.

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

Рекомендуется использовать Group наборы, а не назначать User наборы напрямую.

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

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

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

4. Добавьте новые субъекты безопасности для пользователей и групп.

5. Удалите существующие субъекты для групп владения, владельцев пользователей и других пользователей. Эти принципы не поддерживаются для индексирования ACL во время режима предварительного просмотра.

Создание индекса поиска для метаданных разрешений

Создайте индекс , содержащий поля для метаданных содержимого и разрешений.

Обязательно используйте последнюю предварительную версию REST API или пакет предварительной версии Azure SDK, предоставляющий эквивалентную функциональность. Свойства фильтра разрешений доступны только в API предварительной версии.

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

{
  "name" : "my-adlsgen2-acl-index",
  "fields": [
    {
      "name": "name", "type": "Edm.String",
      "searchable": true, "filterable": false, "retrievable": true
    },
    {
      "name": "description", "type": "Edm.String",
      "searchable": true, "filterable": false, "retrievable": true    
    },
    {
      "name": "location", "type": "Edm.String",
      "searchable": true, "filterable": false, "retrievable": true
    },
    {
      "name": "state", "type": "Edm.String",
      "searchable": true, "filterable": false, "retrievable": true
    },
    {
      "name": "AzureSearch_DocumentKey", "type": "Edm.String",
      "searchable": true, "filterable": false, "retrievable": true, "stored": true,
      "key": true
    },
    { 
      "name": "UserIds", "type": "Collection(Edm.String)", 
      "permissionFilter": "userIds", 
      "searchable": true, "filterable": false, "retrievable": true
    },
    { 
      "name": "GroupIds", "type": "Collection(Edm.String)", 
      "permissionFilter": "groupIds", 
      "searchable": true, "filterable": false, "retrievable": true
    },
    { 
      "name": "RbacScope", "type": "Edm.String", 
      "permissionFilter": "rbacScope", 
      "searchable": true, "filterable": false, "retrievable": true
    }
  ],
  "permissionFilterOption": "enabled"
}

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

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

Требуется indexerPermissionOptionsисточник данных.

В этом руководстве используйте управляемое удостоверение, назначаемое системой, для аутентифицированного подключения.

{
    "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": "parks",
    "query": null
    }
}

Создание и запуск индексатора

Конфигурация индексатора для приема разрешений в основном связана с определением fieldMappingsиз метаданных разрешений.

{
  "name" : "my-adlsgen2-acl-indexer",
  "dataSourceName" : "my-adlsgen2-acl-datasource",
  "targetIndexName" : "my-adlsgen2-acl-index",
  "parameters": {
    "batchSize": null,
    "maxFailedItems": 0,
    "maxFailedItemsPerBatch": 0,
    "configuration": {
      "dataToExtract": "contentAndMetadata",
      "parsingMode": "delimitedText",
      "firstLineContainsHeaders": true,
      "delimitedTextDelimiter": ",",
      "delimitedTextHeaders": ""
      },
  "fieldMappings": [
    { "sourceFieldName": "metadata_user_ids", "targetFieldName": "UserIds" },
    { "sourceFieldName": "metadata_group_ids", "targetFieldName": "GroupIds" },
    { "sourceFieldName": "metadata_rbac_scope", "targetFieldName": "RbacScope" }
    ]
  }
}

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

Выполнение запроса для проверки результатов

Теперь, когда документы загружены, вы можете выполнять запросы к ним с помощью Documents - Search Post (REST).

Универсальный код ресурса (URI) расширен для включения запроса, который указан с использованием оператора /docs/search. Маркер запроса передается в заголовке запроса. Дополнительные сведения см. в статье ACL во время запроса и принудительное применение RBAC.

POST  {{endpoint}}/indexes/stateparks/docs/search?api-version=2026-08-01-preview
Authorization: Bearer {{search-token}}
x-ms-query-source-authorization: {{search-token}}
Content-Type: application/json

{
    "search": "*",
    "select": "name,description,location,GroupIds",
    "orderby": "name asc"
}

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

• https://github.com/Azure-Samples/azure-search-rest-samples/tree/main/acl