Индексирование списков управления доступом к документам (ACL) с помощью push API REST (предварительная версия)

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

К ключевым функциям относятся:

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

В этой статье объясняется, как использовать REST API push для индексирования метаданных разрешений на уровне документа в Поиск с использованием ИИ Azure. Этот процесс подготавливает индекс к запросу и принудительно применяет разрешения конечных пользователей к результатам поиска.

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

• Содержимое с метаданными ACL из Microsoft Entra ID или другой системы ACL в стиле POSIX. Для полей ACL userIds и groupIds используйте идентификаторы объектов Microsoft Entra (GUID), а не UPN или адреса электронной почты. Стабильные идентификаторы объектов обеспечивают надежное сопоставление объектов при выполнении запроса, даже если атрибуты каталога меняются.

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

• Схема индекса с включенной поддержкой permissionFilterOption, а также атрибутами полей permissionFilter, которые хранят разрешения документов.

Ограничения

• Поле ACL с типом userIds фильтра разрешений или groupIds может содержать не более 1000 значений.

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

• Существующее поле можно обновить, чтобы включить назначение для встроенной permissionFilter фильтрации метаданных ACL или RBAC. Чтобы включить фильтрацию по существующему индексу, добавьте новые поля или обновите существующие поля, чтобы включить permissionFilter значение.

• В индексе может существовать только одно поле каждого типа permissionFilter: одно поле groupIds, одно поле userIds, и одно поле rbacScope.

• Каждое permissionFilter поле должно иметь filterable значение true.

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

• Эта функция в настоящее время не поддерживается на портале Azure.

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

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

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

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

Ниже приведен базовый пример схемы, включающей все permissionFilter типы:

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

Для корпоративных репозиториев, таких как SharePoint Online, при приеме данных сопоставляйте разрешения на уровне документа или папки с идентификаторами объектов пользователей и групп Microsoft Entra перед вызовом push API. Затем эти идентификаторы следует хранить в соответствующих полях разрешений.

Пример индексирования REST API

Получив индекс с полями фильтрации разрешений, вы можете заполнить эти значения с помощью API принудительного индексирования, как и любые другие поля документа. Ниже приведен пример с использованием указанной схемы индекса, в которой каждый документ задает действие индексирования, поле ключа (DocumentId) и поля разрешений. Документы также должны содержать содержимое, но это поле опущено в этом примере для краткости.

POST https://exampleservice.search.windows.net/indexes('indexdocumentsexample')/docs/search.index?api-version=2026-08-01-preview
{
  "value": [
    {
      "@search.action": "upload",
      "DocumentId": "1",
      "UserIds": ["00aa00aa-bb11-cc22-dd33-44ee44ee44ee", "11bb11bb-cc22-dd33-ee44-55ff55ff55ff", "22cc22cc-dd33-ee44-ff55-66aa66aa66aa"],
      "GroupIds": ["none"],
      "RbacScope": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/Example-Storage-rg/providers/Microsoft.Storage/storageAccounts/azurestorage12345/blobServices/default/containers/blob-container-01"
    },
    {
      "@search.action": "merge",
      "DocumentId": "2",
      "UserIds": ["all"],
      "GroupIds": ["33dd33dd-ee44-ff55-aa66-77bb77bb77bb", "44ee44ee-ff55-aa66-bb77-88cc88cc88cc"]
    },
    {
      "@search.action": "mergeOrUpload",
      "DocumentId": "3",
      "UserIds": ["1cdd8521-38cf-49ab-b483-17ddaa48f68f"],
      "RbacScope": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/Example-Storage-rg/providers/Microsoft.Storage/storageAccounts/azurestorage12345/blobServices/default/containers/blob-container-03"
    }
  ]
}

Правила разрешения доступа ACL

В этом разделе объясняется, как система определяет доступ к документам пользователя на основе полей разрешений для каждого документа. Эти поля представляют собой либо списки управления доступом (userIds и groupIds, где groupIds включает группы безопасности и группы Microsoft 365), либо область действия RBAC (rbacScope). Azure оценивает область RBAC и списки управления доступом в определенном порядке в соответствии с моделью разрешений ADLS 2-го поколения.

Пользователь получает доступ при выполнении одного из следующих условий: наличия соответствующей записи userIds или groupIds, либо подходящего назначения роли Azure для rbacScope. Сведения о том, как идентификационные данные вызывающей стороны передаются при выполнении запроса, см. в разделе Применение ACL при выполнении запроса и контроль доступа на основе ролей (RBAC).

Специальные значения ACL "all" и "none"

Поля ACL, такие как userIds и groupIds, как правило, содержат списки идентификаторов GUID (глобальные уникальные идентификаторы), которые определяют пользователей и группы с доступом к документу. Для этих типов полей ACL поддерживаются два специальных строковых значения "all" и "none". Эти значения служат широкими фильтрами для управления доступом на глобальном уровне, как показано в следующей таблице.

Так как пользователь должен соответствовать только одному типу поля, специальное значение "all" предоставляет общедоступный доступ независимо от любых других значений полей ACL. В отличие от этого, параметр userIds "none" или пустой массив означает, что пользователям не предоставляется доступ к документу на основе идентификатора пользователя. Им все еще может быть предоставлен доступ путем сопоставления идентификатора группы или метаданных RBAC.

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

В этом примере показано, как определяются правила доступа к документам на основе значений полей разрешений в userIds, groupIds, а также rbacScope. Для удобства чтения в этом сценарии используются псевдонимы, такие как user1 и group1, а не идентификаторы GUID; в рабочей среде используйте идентификаторы объектов Microsoft Entra (GUID).

Связанные материалы

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