Indexação de listas de controlo de acesso a documentos (ACLs) usando as APIs REST push

Indexar documentos, juntamente com as suas listas de controlo de acesso (ACLs) associadas e funções de controlo de acesso baseadas em funções de contentores (RBAC), num índice Pesquisa de IA do Azure através das APIs REST de push preserva a permissão ao nível do documento sobre conteúdos indexados no momento da consulta.

As principais funcionalidades incluem:

• Controlo flexível sobre os pipelines de ingestão.
• Esquema padronizado para metadados de permissões.
• Suporte para permissões hierárquicas, como ACLs no nível da pasta.

Este artigo explica como usar a API push REST para indexar metadados de permissões ao nível do documento no Pesquisa de IA do Azure. Esse processo prepara seu índice para consultar e impor permissões de usuário final nos resultados da pesquisa.

Pré-requisitos

• Conteúdo com metadados ACL de Microsoft Entra ID ou outro sistema ACL do estilo POSIX.

• A mais recente REST API ou um pacote SDK Azure preview que oferece funcionalidades equivalentes.

• Um esquema de índice com permissionFilterOption ativado, e os atributos de campo permissionFilter que armazenam permissões de documentos.

Limitações

• Um campo ACL com tipo userIds filtro de permissão ou groupIds pode conter no máximo 1000 valores.

• Um índice pode conter no máximo cinco valores exclusivos entre campos do tipo rbacScope em todos os documentos. Não há limite para o número de documentos que compartilham o mesmo valor de rbacScope.

• Um campo existente pode ser atualizado para incluir uma atribuição permissionFilter para filtragem incorporada de metadados ACL ou RBAC. Para permitir a filtragem num índice existente, adicione novos campos ou atualize os campos existentes para incluir um permissionFilter valor.

• Apenas um campo de cada permissionFilter tipo (um de groupIds, userIdse rbacScope) pode existir em um índice.

• Cada permissionFilter campo deveria ter filterable definido para true.

• Esta funcionalidade atualmente não é suportada no Azure portal.

Criar um índice com campos de filtro de permissão

A indexação de ACLs de documentos e metadados RBAC com a API REST requer a configuração de um esquema de índice que permita filtros de permissão e tenha campos com atribuições de filtro de permissão.

Primeiro, adicione permissionFilterOption. Os valores válidos são enabled ou disabled, e você deve defini-lo como enabled. Podes mudar para disabled se desejas desligar a funcionalidade de filtragem de permissões ao nível do índice.

Em segundo lugar, crie campos de cadeia de caracteres para seus metadados de permissão e inclua permissionFilter. Lembre-se de que você pode ter um de cada tipo de filtro de permissão.

Aqui está um esquema de exemplo básico que inclui todos os permissionFilter tipos:

{  
  "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"
}

Exemplo de indexação da API REST

Depois de ter um índice com campos de filtro de permissões, pode preencher esses valores usando a API de indexação push, tal como qualquer outro campo de documento. Aqui está um exemplo usando o esquema de índice especificado, onde cada documento especifica a ação de indexação, o campo de chave (DocumentId) e os campos de permissões. Os documentos também devem incluir conteúdo, mas esse campo é omitido neste exemplo para maior brevidade.

POST https://exampleservice.search.windows.net/indexes('indexdocumentsexample')/docs/search.index?api-version=2025-11-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"
    }
  ]
}

Regras de resolução de acesso ACL

Esta secção explica como o acesso ao documento é determinado para um utilizador com base nos valores ACL atribuídos a cada documento. A regra chave é que um utilizador só precisa de corresponder a um tipo de ACL para ganhar access ao documento. Por exemplo, se um documento tiver campos para userIds, groupIds e rbacScope, o utilizador pode aceder ao documento correspondendo a qualquer um destes campos ACL.

Valores especiais de ACL "todos" e "nenhum"

Campos ACL, como userIds e groupIds, normalmente contêm listas de GUIDs (Identificadores Globalmente Únicos) que identificam utilizadores e grupos com access ao documento. Dois valores de cadeia de caracteres especiais, "all" e "none", são suportados para esses tipos de campo ACL. Estes valores atuam como filtros amplos para controlar o acesso a nível global, como mostrado na tabela seguinte.

Como um utilizador precisa de corresponder apenas a um tipo de campo, o valor especial "todos" concede acesso público independentemente de quaisquer outros valores de campo ACL. Em contraste, definir userIds como "nenhum" ou um array vazio significa que nenhum utilizador tem acesso ao documento com base no ID do utilizador. Ainda assim, podem obter acesso ao corresponderem ao ID do grupo ou aos metadados RBAC.

Exemplo de controlo de acesso

Este exemplo ilustra como as regras de acesso ao documento são resolvidas com base nos valores específicos dos campos ACL do documento. Para facilitar a leitura, esse cenário usa aliases de ACL como "user1", "group1" em vez de GUIDs.

Consulte também

• Liga-te a Pesquisa de IA do Azure usando roles
• A aplicação de ACL e RBAC em tempo de consulta
• azure-search-python-samples/Quickstart-Document-Permissions-Push-API