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

A ingestão de permissões ao nível dos documentos através das APIs REST push (pré-visualização) permite-lhe indexar documentos juntamente com as respetivas listas de controlo de acesso (ACLs) e funções de controlo de acesso baseado em funções (RBAC) do contentor. Quando insere conteúdo num índice do Pesquisa de IA do Azure através das APIs push REST, o serviço preserva essas permissões sobre conteúdos indexados e aplica-as no momento da consulta.

Características principais incluem:

• Controlo flexível sobre os fluxos de ingestão.
• Esquema padronizado para metadados de permissões.
• Suporte para permissões hierárquicas, como ACLs ao 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. Este processo prepara o seu índice para consultar e aplicar permissões ao utilizador final nos resultados de pesquisa.

Pré-requisitos

• Conteúdo com metadados ACL de Microsoft Entra ID ou outro sistema ACL do estilo POSIX. Para os campos ACL userIds e groupIds, utilize os IDs de objeto (GUIDs) do Microsoft Entra, não UPNs nem endereços de correio eletrónico. IDs de objeto estáveis garantem uma correspondência fiável de identidade no momento da consulta, mesmo que os atributos do diretório mudem.

• A mais recente API de pré-visualização REST ou um pacote de SDK do Azure de pré-visualização que oferece funcionalidades equivalentes.

• Um esquema de índice com permissionFilterOption ativado, e 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 únicos entre campos de tipo rbacScope em todos os documentos. Não há limite para o número de documentos que partilham o mesmo valor de rbacScope.

• Um campo existente pode ser atualizado para incluir uma permissionFilter atribuição de filtragem de metadados incorporada para 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 tipo permissionFilter (um de cada groupIds, userIds e rbacScope) pode existir num índice.

• Cada permissionFilter campo deveria ter filterable definido para true.

• A imposição de permissões no momento da consulta reflete os valores da ACL gravados mais recentemente no índice. Se as permissões de origem mudarem, essas atualizações não se refletem até que reingira ou atualize os documentos afetados. Agende a reingestão incremental ou atualizações parciais para manter as ACLs atualizadas.

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

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

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

Primeiro, adicione permissionFilterOption. Valores válidos são enabled ou disabled, e deve defini-lo para enabled. Pode alterá-lo para disabled se quiser desativar a funcionalidade de filtro de permissões ao nível do índice.

Em segundo lugar, crie campos de cadeia para os seus metadados de permissões e inclua permissionFilter. Lembre-se que pode ter um de cada tipo de filtro de permissões.

Aqui está um esquema básico de exemplo 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"
}

Para repositórios empresariais, como o SharePoint Online, resolvam permissões ao nível de documento ou de pasta para IDs de utilizadores e de objetos de grupo da Microsoft Entra durante a ingestão antes de chamar a API push. Deves então guardar esses IDs nos campos de permissões correspondentes.

Exemplo de indexação de 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=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"
    }
  ]
}

Regras de resolução de acesso da ACL

Esta secção explica como o sistema determina o acesso a documentos de um utilizador com base nos campos de permissões de cada documento. Estes campos são ACLs (userIds e groupIds, onde groupIds inclui grupos de segurança e Grupos do Microsoft 365) ou um âmbito de RBAC (rbacScope). O Azure avalia o âmbito RBAC e as ACLs numa ordem definida, consistente com o modelo de permissões ADLS Gen2.

Um utilizador obtém acesso se cumprir um dos seguintes critérios: uma entrada correspondente em userIds ou groupIds, ou uma atribuição de função do Azure elegível para o rbacScope. Para obter informações sobre como as identidades dos autores da chamada são disponibilizadas no momento da execução da consulta, consulte Aplicação de ACL e RBAC no momento da consulta.

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 acesso ao documento. São suportados dois valores especiais de cadeia, "todos" e "nenhum", para estes 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 para "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 corresponder com o ID do grupo ou metadados RBAC.

Exemplo de controlo de acesso

Este exemplo ilustra como as regras de acesso a documentos são resolvidas com base nos valores dos campos de permissões em userIds, groupIds, e rbacScope. Para legibilidade, este cenário usa pseudónimos como "user1" e "group1" em vez de GUIDs; em produção, utiliza-se os ID de objeto (GUIDs) do Microsoft Entra.

Conteúdo relacionado

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