Indexação de ACLs (listas de controle de acesso de documentos) usando as APIs REST por push (versão prévia)

A ingestão de permissões em nível de documento por meio das APIs REST de push (versão prévia) permite indexar documentos juntamente com suas ACLs (listas de controle de acesso) associadas e as funções de controle de acesso baseado em função (RBAC) do contêiner. Quando você envia conteúdo para um índice do Pesquisa de IA do Azure  por meio das APIs REST de envio, o serviço preserva essas permissões no conteúdo indexado e as aplica no momento da consulta.

Os principais recursos incluem:

• Controle flexível nos 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 REST de push para indexar metadados de permissão em nível de documento no Pesquisa de IA do Azure . Esse processo prepara seu índice para consultar e impor permissões do usuário final nos resultados da pesquisa.

Pré-requisitos

• Conteúdo com metadados de ACL de Microsoft Entra ID ou outro sistema ACL no estilo POSIX. Para os campos ACL userIds e groupIds, use GUIDs (IDs de objeto) do Microsoft Entra, não UPNs ou endereços de email. As IDs de objeto estáveis garantem a correspondência de identidade confiável no momento da consulta, mesmo se os atributos de diretório forem alterados.

• A API REST versão prévia mais recente ou um pacote SDK do Azure de versão prévia que fornece recursos equivalentes.

• Um esquema de índice com permissionFilterOption habilitado, junto com atributos de campo de permissionFilter que armazenam as permissões de documento.

Limitações

• Um campo ACL com tipo userIds de 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 de 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 de permissionFilter para a filtragem de metadados incorporados de ACL ou RBAC. Para habilitar a filtragem em um índice existente, adicione novos campos ou atualize os campos existentes para incluir um permissionFilter valor.

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

• Cada permissionFilter campo deve ter filterable definido como true.

• A aplicação de permissões no momento da consulta reflete os valores de ACL gravados mais recentemente no índice. Se as permissões de origem forem alteradas, essas atualizações não serão refletidas até que você reingesque ou atualize os documentos afetados. Agende a reingestão incremental ou atualizações parciais para manter as ACLs atualizadas.

• No momento, não há suporte para essa funcionalidade no portal Azure.

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

Indexar ACLs de documento e metadados RBAC com a API REST requer a configuração de um esquema de índice que habilita filtros de permissão e tem 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. Você pode alterá-la para disabled se quiser desativar a funcionalidade de filtro de permissão no nível do índice.

Em segundo lugar, crie campos de cadeia de caracteres para os 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"
}

Para repositórios corporativos, como o SharePoint Online, converta as permissões em nível de documento ou de pasta em IDs de objeto de usuários e grupos do Microsoft Entra durante a ingestão, antes de chamar a API de push. Em seguida, você deve armazenar essas IDs nos campos de permissão correspondentes.

Exemplo de indexação da API REST

Depois de ter um índice com campos de filtro de permissão, você poderá preencher esses valores usando a API de indexação por push, assim como qualquer outro campo de documento. Aqui está um exemplo usando o esquema de índice especificado, em que cada documento especifica a ação de indexação, o campo de chave (DocumentId) e os campos de permissão. Os documentos também devem incluir conteúdo, mas esse campo é omitido neste exemplo para fins de 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 à ACL

Esta seção explica como o sistema determina o acesso a documentos de um usuário com base nos campos de permissão em cada documento. Esses campos são ACLs (userIds e groupIds, em que groupIds inclui grupos de segurança e Grupos do Microsoft 365) ou um escopo de RBAC (rbacScope). Azure avalia o escopo do RBAC e as ACLs em uma ordem definida, consistente com o modelo de permissão do ADLS Gen2.

Um usuário obtém acesso ao atender a um dos seguintes campos: uma entrada correspondente em userIds ou groupIds, ou uma atribuição de função do Azure qualificada para o rbacScope. Para obter informações sobre como as identidades do chamador são fornecidas em tempo de consulta, consulte Aplicação de ACL e RBAC em tempo de consulta.

Valores especiais de ACL "todos" e "nenhum"

Os campos ACL, como userIds e groupIds, normalmente, contêm listas de GUIDs (Identificadores Globalmente Exclusivos) que identificam usuários e grupos com acesso ao documento. Há suporte para dois valores de cadeia de caracteres especiais, "todos" e "nenhum", para esses tipos de campo de ACL. Esses valores atuam como filtros amplos para controlar o acesso no nível global, conforme mostrado na tabela a seguir.

Como um usuário precisa corresponder apenas a um tipo de campo, o valor especial "todos" concede acesso público, independentemente de quaisquer outros valores de campo ACL. Por outro lado, a configuração userIds como "nenhum" ou uma matriz vazia significa que nenhum usuário recebe acesso ao documento com base na ID do usuário. Eles ainda podem receber acesso ao corresponderem à ID do grupo ou aos metadados RBAC.

Exemplo de controle de acesso

Este exemplo ilustra como as regras de acesso a documentos são resolvidas com base nos valores de campo de permissão em userIds, groupIdse rbacScope. Para facilitar a leitura, este cenário usa aliases como "user1" e "group1" em vez de GUIDs; em produção, use IDs de objeto do Microsoft Entra (GUIDs).

Conteúdo relacionado

• Conectar a Pesquisa de IA do Azure  usando perfis de acesso
• Aplicação de ACL e RBAC em Tempo de Consulta
• azure-search-python-samples/Quickstart-Document-Permissions-Push-API