Configure um serviço de pesquisa para se ligar usando uma identidade gerida

Note

O Pesquisa de IA do Azure está disponível através do portal Azure, APIs REST e SDKs do Azure. Também sustenta o Foundry IQ, a camada de conhecimento gerida que transforma conteúdos empresariais em bases de conhecimento reutilizáveis e conscientes de permissões para agentes no portal Microsoft Foundry.

Pode usar princípios de segurança e atribuições de funções do Microsoft Entra ID para ligações de saída do Pesquisa de IA do Azure para outros recursos do Azure que fornecem dados, IA aplicada ou vetorização durante indexação ou consultas.

Para usar funções numa ligação de saída, configure primeiro o seu serviço de pesquisa para usar uma identidade gerida atribuída pelo sistema ou pelo utilizador como principal de segurança para o seu serviço de pesquisa num locatário Microsoft Entra. Depois de ter uma identidade gerida, pode atribuir funções para acesso autorizado. As identidades geridas e as atribuições de funções eliminam a necessidade de passar segredos e credenciais numa cadeia de conexão ou em código.

Pré-requisitos

Um serviço Pesquisa de IA do Azure em qualquer região no nível Básico ou superior.
Um recurso Azure que aceita pedidos recebidos de um principal de segurança Microsoft Entra que tenha uma atribuição de função válida.
Para criar uma identidade gerida, deve ser Proprietário ou Administrador de Acesso ao Utilizador. Para atribuir funções, deve ser Proprietário, Administrador de Acesso ao Utilizador, Administrador de Controlo de Acesso Baseado em Funções, ou membro de uma função personalizada com permissões Microsoft.Authorization/roleAssignments/write.

Cenários suportados

Pode usar identidades geridas para os seguintes cenários.

Cenário	Sistema atribuído	Utilizador atribuído
Conectar-se às fontes de dados do indexador¹	Sim	Sim
Conecta-te a modelos de embedding e de conclusão de chat em Azure OpenAI, Microsoft Foundry e Funções do Azure através de skills/vetorizadores ²	Sim	Sim
Conectar-se ao Azure Key Vault para chaves geridas pelo cliente	Sim	Sim
Conectar-se a sessões de Depuração (alojadas em Armazenamento do Azure)¹	Sim	Não
Liga-se a uma cache de enriquecimento (alojada em Armazenamento do Azure)^1.³	Sim	Sim, ⁴
Liga-te a uma Loja de Conhecimento (alojada em Armazenamento do Azure)¹	Sim	Sim

¹ Para a conectividade entre pesquisa e armazenamento, a segurança da rede impõe restrições sobre que tipo de identidade gerida pode utilizar. Apenas uma identidade gerida pelo sistema pode ser usada para uma ligação à mesma região do Armazenamento do Azure, e essa ligação deve ser feita através da exceção de serviço confiável ou regra de instância de recursos. Consulte Acesso a uma conta de armazenamento protegida por rede para mais detalhes.

² As ligações ao Azure OpenAI, ao Foundry e ao Funções do Azure através de competências/vetorizadores incluem: Habilidade personalizada, Vetorizador personalizado, Habilidade de inserção do Azure OpenAI, Vetorizador do Azure OpenAI, Habilidade AML e Vetorizador do catálogo de modelos Microsoft Foundry.

^{O serviço de pesquisa de IA 3} atualmente não consegue ligar-se a tabelas numa conta de armazenamento que tenha o acesso à chave partilhada desligado.

⁴ A identidade gerida atribuída pelo utilizador para ligações de cache de enriquecimento requer uma API REST de pré-visualização (2025-11-01-preview ou posterior) ou um pacote SDK de pré-visualização. Todos os outros cenários de identidade gerida atribuídos pelo utilizador nesta tabela são suportados na versão da API REST 2026-04-01 e posteriores.

Criar uma identidade gerida por sistema

Uma identidade gerida atribuída pelo sistema é um princípio de segurança do Microsoft Entra ID que é criado automaticamente e ligado a um recurso Azure, como um serviço Pesquisa de IA do Azure.

Pode ter uma identidade gerida atribuída pelo sistema para cada serviço de pesquisa. É único para o seu serviço de pesquisa e está ligado ao serviço durante toda a sua vida.

Quando ativa uma identidade gerida atribuída ao sistema, o Microsoft Entra ID cria um princípio de segurança para o seu serviço de pesquisa que é usado para autenticar com outros recursos do Azure. Pode então usar esta identidade nas atribuições de funções para acesso autorizado a dados e operações.

Vá ao seu serviço de pesquisa no portal Azure.
No painel esquerdo, selecione Definições>Identidade.
No separador Sistema Atribuído , em Estado, selecione Ligado.
Selecione Guardar.

Depois de guardares as definições, a página atualiza para mostrar um identificador de objeto atribuído ao teu serviço de pesquisa.

Set-AzSearchService `
  -Name YOUR-SEARCH-SERVICE-NAME `
  -ResourceGroupName YOUR-RESOURCE-GROUP-NAME `
  -IdentityType SystemAssigned

Para mais informações, consulte Criar um serviço de pesquisa com uma identidade gerida atribuída pelo sistema (Azure PowerShell.

az search service update `
  --name YOUR-SEARCH-SERVICE-NAME `
  --resource-group YOUR-RESOURCE-GROUP-NAME `
  --identity-type SystemAssigned

Para mais informações, consulte Criar um serviço de pesquisa com uma identidade gerida (CLI do Azure) atribuída pelo sistema.

Use Serviços - Criar ou Atualizar (API REST) para formular o pedido.

PUT https://management.azure.com/subscriptions/subid/resourceGroups/rg1/providers/Microsoft.Search/searchServices/mysearchservice?api-version=2025-05-01  HTTP/1.1
{
  "location": "[region]",
  "sku": {
    "name": "[sku]"
  },
  "properties": {
    "replicaCount": [replica count],
    "partitionCount": [partition count],
    "hostingMode": "default"
  },
  "identity": {
    "type": "SystemAssigned"
  }
}

A resposta inclui uma confirmação e um identificador de objeto para a identidade gerida atribuída pelo sistema.

Crie uma identidade gerida atribuída pelo utilizador

Uma identidade gerida atribuída pelo utilizador é um recurso Azure que pode ser encaminhado para subscrições, grupos de recursos ou tipos de recursos.

Pode criar múltiplas identidades geridas atribuídas pelo utilizador para maior granularidade nas atribuições de funções. Por exemplo, pode querer identidades separadas para diferentes aplicações e cenários. Como recurso criado e gerido de forma independente, não está vinculado ao serviço em si.

Os passos para configurar uma identidade gerida atribuída pelo utilizador são os seguintes:

Na sua subscrição do Azure, crie uma identidade gerida atribuída pelo utilizador.
No seu serviço de pesquisa, associe a identidade gerida atribuída pelo utilizador ao seu serviço de pesquisa.
Noutros serviços do Azure a que queres ligar-te, cria uma atribuição de papel para a identidade.

A associação de uma identidade gerida atribuída pelo utilizador a um serviço Pesquisa de IA do Azure é suportada no portal Azure, nas APIs REST de Gestão de Pesquisa e nos pacotes SDK que fornecem esta funcionalidade.

Portal do Azure
API REST

Inicie sessão no portal Azure.
No canto superior esquerdo do seu painel, selecione Criar um recurso.
Utilize a caixa de pesquisa para encontrar Identidade Gerida Atribuída pelo Utilizador e depois selecione Criar.
Selecione a subscrição, grupo de recursos e região. Dê à identidade um nome descritivo.
Selecione Criar e espere que o recurso termine de ser implementado.

Demora vários minutos até conseguires usar a identidade.
Na sua página de serviço de pesquisa, selecione Definições>Identificação.
No separador Atribuído ao Utilizador, selecione Adicionar.
Selecione a subscrição e a identidade gerida atribuída a utilizador que criou anteriormente.

Em vez do portal Azure, pode usar as APIs REST de Gestão de Pesquisa para atribuir uma identidade gerida atribuída pelo utilizador.

Use Services - Update (API REST) para formular o pedido.

PUT https://management.azure.com/subscriptions/subid/resourceGroups/rg1/providers/Microsoft.Search/searchServices/mysearchservice?api-version=2025-05-01  HTTP/1.1
{
  "location": "[region]",
  "sku": {
    "name": "[sku]"
  },
  "properties": {
    "replicaCount": [replica count],
    "partitionCount": [partition count],
    "hostingMode": "default"
  },
  "identity": {
    "type": "UserAssigned",
    "userAssignedIdentities": {
      "/subscriptions/[subscription ID]/resourcegroups/[name of resource group]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[name of managed identity]": {}
    }
  }
}

Defina identity.type como o tipo de identidade.
- Os valores válidos são SystemAssigned, UserAssigned, ou SystemAssigned, UserAssigned para ambos.
- Um valor de None elimina quaisquer identidades previamente atribuídas do serviço de pesquisa.
Atualize identity.userAssignedIdentities para incluir os detalhes da sua identidade gerida atribuída pelo utilizador. Esta identidade deve já existir antes de a poderes especificar no pedido.

Atribuir um papel

Depois de ter uma identidade gerida, atribua papéis que determinam as permissões do serviço de pesquisa no recurso Azure.

São necessárias permissões de leitura para ligações de dados do indexador e para aceder a uma chave gerida pelo cliente no Azure Key Vault.
São necessárias permissões de escrita para funcionalidades de enriquecimento de IA que utilizam o Armazenamento do Azure para alojar dados de sessões de depuração, cache de enriquecimento e armazenamento de conteúdos a longo prazo numa loja de conhecimento.

Os passos seguintes ilustram o fluxo de trabalho de atribuição de funções. Este exemplo é para o Azure OpenAI. Para outros recursos Azure, veja Liga-te a Armazenamento do Azure, Liga-te a Azure Cosmos DB, ou Liga-te a SQL do Azure.

Vai ao teu recurso Azure OpenAI no portal Azure.
Selecione controlo de acesso no menu esquerdo.
Selecione Adicionar e depois selecione Adicionar atribuição de funções.
Em funções laborais, selecione Utilizador OpenAI de Serviços Cognitivos e depois selecione Seguinte.
Em Membros, selecione Identidade Gerida e, em seguida, selecione Membros.
Filtre por subscrição e tipo de recurso (Serviços de Pesquisa) e depois selecione a identidade gerida do seu serviço de pesquisa.
Selecione Rever + atribuir.

Exemplos de cordas de ligação

Lembre-se das descrições dos cenários que pode usar identidades geridas nas cadeias de conexão para outros recursos do Azure. Esta secção fornece exemplos.

As ligações de identidade gerida atribuídas pelo sistema utilizam versões REST API geralmente disponíveis. As ligações de identidade gerida atribuídas pelo utilizador utilizam a versão REST API 2026-04-01 ou posterior, exceto as ligações de cache de enriquecimento, que ainda requerem uma versão de pré-visualização da API.

Dica

Pode criar a maioria destes objetos no portal Azure, especificando uma identidade gerida atribuída pelo sistema ou pelo utilizador, e depois visualizar a definição JSON para obter a cadeia de ligação.

Fonte de dados do blob (identidade gerida pelo sistema):

Uma fonte de dados indexadora inclui uma credentials propriedade que determina como a ligação é feita à fonte de dados. O exemplo seguinte mostra uma cadeia de ligação que especifica o ID de recurso único de uma conta de armazenamento.

Uma identidade gerida por sistema é indicada quando uma cadeia de ligação é o ID de recurso único de um serviço ou aplicação compatível com o Microsoft Entra ID. Uma identidade gerida atribuída pelo utilizador é especificada através de uma identity propriedade.

"credentials": {
    "connectionString": "ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/{storage-account-name};"
    }

Fonte de dados do blob (identidade gerida pelo utilizador):

Uma identidade gerida atribuída pelo utilizador é suportada através da propriedade identity no SearchIndexerDataSource com a versão 2026-04-01 ou posterior da API REST.

"credentials": {
    "connectionString": "ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/{storage-account-name};"
    },
  . . .
"identity": {
    "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
    "userAssignedIdentity": "/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{user-assigned-managed-identity-name}"
  }

Armazenamento de conhecimento (identidade gerida por sistema):

Uma definição de knowledge store inclui uma cadeia de ligação para o Armazenamento do Azure. A cadeia de ligação é o ID único do recurso da sua conta de armazenamento. Repara que a string não inclui containers ou tabelas no caminho. Estas são definidas na definição de projeção embutida, não na cadeia de ligação.

"knowledgeStore": {
  "storageConnectionString": "ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/{storage-account-name};"
}

Armazenamento de conhecimento (identidade gerida pelo utilizador):

Uma identidade gerida atribuída pelo utilizador é suportada pela propriedade identity na SearchIndexerKnowledgeStore com a versão 2026-04-01 ou posterior da API REST.

"knowledgeStore": {
  "storageConnectionString": "ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/{storage-account-name};",
  "identity": {
    "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
    "userAssignedIdentity": "/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{user-assigned-managed-identity-name}"
  }
}

Cache de enriquecimento:

Um indexador cria, utiliza e lembra-se do container usado para os enriquecimentos em cache. Não é necessário incluir o contentor na cadeia de ligação da cache. Pode encontrar o ID do objeto na página Identity do seu serviço de pesquisa no portal Azure.

"cache": {
  "enableReprocessing": true,
  "storageConnectionString": "ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/{storage-account-name};"
}

Sessão de depuração:

Uma sessão de depuração corre no portal do Azure e recebe uma cadeia de ligação quando inicias a sessão. Pode colar uma cadeia semelhante ao exemplo seguinte.

"ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/{storage-account-name}/{container-name};",

Competência personalizada:

Uma skill personalizada visa o endpoint de uma função ou aplicação do Azure que hospeda código personalizado.

uri é o ponto final da função ou aplicação.
authResourceId indica ao serviço de pesquisa que se conecte usando uma identidade gerida, transmitindo o ID da aplicação da função ou da aplicação alvo na propriedade.

{
  "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
  "description": "A custom skill that can identify positions of different phrases in the source text",
  "uri": "https://contoso.count-things.com",
  "authResourceId": "<Azure-AD-registered-application-ID>",
  "batchSize": 4,
  "context": "/document",
  "inputs": [ ... ],
  "outputs": [ ...]
}

Exemplos de ligação para modelos

Para ligações feitas usando identidades geridas, esta secção mostra exemplos de informação de ligação usada por um serviço de pesquisa para se ligar a um modelo noutro recurso. Uma ligação através de uma identidade gerida por sistema é transparente; A identidade e os papéis estão definidos, e a ligação tem sucesso se estiverem devidamente configurados. Em contraste, uma identidade gerida pelo utilizador requer propriedades de ligação adicionais.

Azure OpenAI embedding skill e Azure OpenAI vetorizador:

Uma habilidade de embedding do Azure OpenAI e um vetorizador em AI Search visam o endpoint de um Azure OpenAI que aloja um modelo de embedding. O endpoint está especificado na definição de capacidade de embedding Azure OpenAI e/ou na definição do vectorizador Azure OpenAI.

A identidade gerida pelo sistema é usada automaticamente se "apikey" e "authIdentity" estiverem vazios, como demonstrado no exemplo seguinte. A "authIdentity" propriedade é usada apenas para identidade gerida atribuída pelo utilizador.

Exemplo de identidade gerida por sistema:

{
  "@odata.type": "#Microsoft.Skills.Text.AzureOpenAIEmbeddingSkill",
  "description": "Connects a deployed embedding model.",
  "resourceUri": "https://url.openai.azure.com/",
  "deploymentId": "text-embedding-ada-002",
  "modelName": "text-embedding-ada-002",
  "inputs": [
    {
      "name": "text",
      "source": "/document/content"
    }
  ],
  "outputs": [
    {
      "name": "embedding"
    }
  ]
}

Aqui está um exemplo de vetorizador configurado para uma identidade gerida atribuída pelo sistema. Um vetorizador é especificado num índice de pesquisa.

 "vectorizers": [
    {
      "name": "my_azure_open_ai_vectorizer",
      "kind": "azureOpenAI",
      "azureOpenAIParameters": {
        "resourceUri": "https://url.openai.azure.com",
        "deploymentId": "text-embedding-ada-002",
        "modelName": "text-embedding-ada-002"
      }
    }
  ]

Exemplo de identidade gerida atribuída pelo utilizador:

Uma identidade gerida atribuída pelo utilizador é usada se "apiKey" estiver vazia e for fornecida uma identidade válida "authIdentity" .

{
  "@odata.type": "#Microsoft.Skills.Text.AzureOpenAIEmbeddingSkill",
  "description": "Connects a deployed embedding model.",
  "resourceUri": "https://url.openai.azure.com/",
  "deploymentId": "text-embedding-ada-002",
  "modelName": "text-embedding-ada-002",
  "inputs": [
    {
      "name": "text",
      "source": "/document/content"
    }
  ],
  "outputs": [
    {
      "name": "embedding"
    }
  ],
  "authIdentity": {
    "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
    "userAssignedIdentity": "/subscriptions/<subscription_id>/resourcegroups/<resource_group>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<user-assigned-managed-identity-name>"
   }
}

Aqui está um exemplo de vetorizador configurado para uma identidade gerida atribuída pelo utilizador. Um vetorizador é especificado num índice de pesquisa.

 "vectorizers": [
    {
      "name": "my_azure_open_ai_vectorizer",
      "kind": "azureOpenAI",
      "azureOpenAIParameters": {
        "resourceUri": "https://url.openai.azure.com",
        "deploymentId": "text-embedding-ada-002",
        "modelName": "text-embedding-ada-002"
        "authIdentity": {
            "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
            "userAssignedIdentity": "/subscriptions/<subscription_id>/resourcegroups/<resource_group>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<user-assigned-managed-identity-name>"
          }
      }
    }
  ]

Verifique o acesso ao firewall

Se o seu recurso do Azure estiver atrás de um firewall, certifique-se de que existe uma regra de entrada que admita pedidos do seu serviço de pesquisa e do portal do Azure.

Para ligações da mesma região a Armazenamento de Blobs do Azure ou Azure Data Lake Storage Gen2, utilize-se uma identidade gerida por sistema e a exceção de serviço confiável. Opcionalmente, pode configurar uma regra de instância de recurso para admitir pedidos.
Para todos os outros recursos e ligações, configure uma regra de firewall IP que admite pedidos de Pesquisa de IA do Azure. Consulte o acesso do Indexer ao conteúdo protegido pelas funcionalidades de segurança de rede da Azure para mais detalhes.

Ver também

Comentários

Esta página foi útil?

Last updated on 2026-05-12