Configurar um serviço de pesquisa para se conectar usando uma identidade gerenciada

Note

Pesquisa de IA do Azure está disponível por meio do portal Azure, APIs REST e SDKs do Azure. Ele também sustenta o IQ do Foundry, a camada de conhecimento gerenciado que transforma o conteúdo da empresa em bases de conhecimento reutilizáveis e com reconhecimento de permissão para agentes no portal do Microsoft Foundry.

Você pode usar as atribuições de função e entidades de serviço do Microsoft Entra ID para conexões de saída da Pesquisa de IA do Azure a outros recursos do Azure, fornecendo dados, IA aplicada ou vetorização durante a indexação ou as consultas.

Para usar funções em uma conexão de saída, primeiro configure seu serviço de pesquisa para usar uma identidade gerenciada atribuída pelo sistema ou pelo usuário como a entidade de segurança para seu serviço de pesquisa em um locatário do Microsoft Entra. Depois de ter uma identidade gerenciada, você pode atribuir funções para acesso autorizado. Identidades gerenciadas e atribuições de função eliminam a necessidade de passar segredos e credenciais em 'strings de conexão' ou códigos.

Pré-requisitos

Um serviço de Pesquisa de IA do Azure em qualquer região no nível Básico ou superior.
Um recurso do Azure que aceita solicitações de entrada de uma entidade de segurança do Microsoft Entra que tem uma atribuição de função válida.
Para criar uma identidade gerenciada, você deve ser um Proprietário ou Administrador de Acesso do Usuário. Para atribuir funções, você deve ser Proprietário, Administrador de Acesso do Usuário, Administrador de Controle de Acesso baseado em Função ou membro de uma função personalizada com permissões Microsoft.Authorization/roleAssignments/write.

Cenários com suporte

Você pode usar identidades gerenciadas para os cenários a seguir.

Cenário	Sistema atribuído	Usuário atribuído
Conectar-se às fontes de dados do indexador¹	Sim	Sim
Conecte-se a modelos de conclusão de chat e modelos de incorporação no OpenAI do Azure, Microsoft Foundry e Azure Functions por meio de habilidades/vetorizadores ²	Sim	Sim
Conectar para Azure Key Vault para chaves gerenciadas pelo cliente	Sim	Sim
Conectar a sessões de depuração (hospedadas no Armazenamento do Azure)¹	Sim	Não
Conectar-se a um cache de enriquecimento, hospedado em Armazenamento do Azure (versão prévia)^1,3	Sim	Sim ⁴
Conectar para um Repositório de Conhecimento (hospedado em Armazenamento do Azure)¹	Sim	Sim

¹ Para conectividade entre pesquisa e armazenamento, a segurança de rede impõe restrições sobre qual tipo de identidade gerenciada você pode usar. Somente uma identidade gerenciada do sistema pode ser usada para uma conexão de mesma região com o Armazenamento do Azure, e essa conexão deve ser por meio da exceção de serviço confiável ou regra de instância de recurso. Consulte o Acesso a uma conta de armazenamento protegida por rede para obter detalhes.

² As conexões com o OpenAI do Azure, Foundry e Azure Functions por meio de habilidades/vetorizadores incluem: Habilidade personalizada, Vetorizador personalizado, Habilidade de incorporação do OpenAI do Azure, Vetorizador do OpenAI do Azure, Habilidade AML e Vetorizador do catálogo de modelos do Microsoft Foundry.

^{No momento} , o serviço de pesquisa de IA 3 não pode se conectar a tabelas em uma conta de armazenamento que tenha acesso de chave compartilhada desativado.

⁴ A identidade gerenciada atribuída pelo usuário para conexões de cache de enriquecimento requer uma API REST de prévia (2025-11-01-preview ou posterior) ou um pacote SDK de prévia. Todos os outros cenários de identidade gerenciada atribuídos pelo usuário nesta tabela têm suporte na API REST versão 2026-04-01 e posterior.

Criar uma identidade gerenciada pelo sistema

Uma identidade gerenciada atribuída pelo sistema é uma entidade de segurança do Microsoft Entra ID que é criada e vinculada automaticamente a um recurso do Azure, como um serviço de Pesquisa de IA do Azure.

Você pode ter uma identidade gerenciada atribuída pelo sistema para cada serviço de pesquisa. Ele é exclusivo para seu serviço de pesquisa e associado ao serviço pelo seu tempo de vida.

Quando você habilita uma identidade gerenciada atribuída pelo sistema, o Microsoft Entra ID cria uma entidade de segurança para o serviço de pesquisa que é usada para autenticar outros recursos do Azure. Em seguida, você pode usar essa identidade em atribuições de função para acesso autorizado a dados e operações.

Acesse o serviço de pesquisa no Azure portal.
No painel esquerdo, selecione Configurações>Identidade.
Na guia Sistema atribuído , em Status, selecione Ativar.
Selecione Salvar.

Depois de salvar as configurações, a página é atualizada para mostrar um identificador de objeto atribuído ao serviço de pesquisa.

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

Para obter mais informações, consulte Criar um serviço de pesquisa com uma identidade gerenciada 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 obter mais informações, consulte Criar um serviço de pesquisa com uma identidade gerenciada atribuída pelo sistema (CLI do Azure).

Use serviços – Criar ou atualizar (API REST) para formular a solicitação.

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 gerenciada atribuída pelo sistema.

Criar uma identidade gerenciada atribuída pelo usuário

Uma identidade gerenciada atribuída pelo usuário é um recurso Azure que pode ser definido como escopo para assinaturas, grupos de recursos ou tipos de recursos.

Você pode criar várias identidades gerenciadas atribuídas pelo usuário para obter mais granularidade em atribuições de função. Por exemplo, talvez você queira identidades separadas para diferentes aplicativos e cenários. Como um recurso criado e gerenciado de forma independente, ele não está associado ao próprio serviço.

As etapas para configurar uma identidade gerenciada atribuída pelo usuário são as seguintes:

Em sua assinatura Azure, crie uma identidade gerenciada atribuída pelo usuário.
No serviço de pesquisa, associe a identidade gerenciada atribuída pelo usuário ao serviço de pesquisa.
Nos outros serviços Azure aos quais você deseja se conectar, crie uma atribuição de função para a identidade especificada.

Há suporte para associar uma identidade gerenciada atribuída pelo usuário a um serviço Pesquisa de IA do Azure no portal do Azure, nas APIs REST do Gerenciamento de Pesquisa e nos pacotes do SDK que fornecem o recurso.

Portal do Azure
REST API

Entre no portal Azure.
No canto superior esquerdo do painel, selecione Criar um recurso.
Use a caixa de pesquisa para localizar a Identidade Gerenciada Atribuída pelo Usuário e selecione Criar.
Selecione a assinatura, o grupo de recursos e a região. Dê à identidade um nome descritivo.
Selecione Criar e aguarde a conclusão da implantação do recurso.

Leva vários minutos até que você possa usar a identidade.
Na página do serviço de pesquisa, selecione Configurações>Identidade.
Na guia Atribuições do usuário, selecione Adicionar.
Selecione a assinatura e a identidade gerenciada atribuída pelo usuário que você criou anteriormente.

Em vez do portal Azure, você pode usar as APIs REST do Gerenciamento de Pesquisa para atribuir uma identidade gerenciada atribuída pelo usuário.

Use Serviços – Atualização (API REST) para formular a solicitação.

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, UserAssignedou SystemAssigned, UserAssigned para ambos.
- Um valor de None remove todas as identidades atribuídas anteriormente do serviço de pesquisa.
Atualize identity.userAssignedIdentities para incluir os detalhes da identidade gerenciada atribuída pelo usuário. Essa identidade já deve existir antes que você possa especificá-la na solicitação.

Atribuir uma função

Depois de ter uma identidade gerenciada, atribua funções que determinam permissões de serviço de pesquisa no recurso Azure.

As permissões de leitura são necessárias para conexões de dados do indexador e para acessar uma chave gerenciada pelo cliente em Azure Key Vault.
As permissões de gravação são necessárias para recursos de enriquecimento de IA que usam o Armazenamento do Azure para hospedar dados da sessão de depuração, cache de enriquecimento e armazenamento de conteúdo de longo prazo em um repositório de conhecimento.

As etapas a seguir ilustram o fluxo de trabalho de atribuição de função. Este exemplo é para Azure OpenAI. Para obter outros recursos Azure, consulte Conectar para Armazenamento do Azure, Connect to Azure Cosmos DB ou Connect to SQL do Azure.

Acesse o recurso Azure OpenAI no Azure portal.
Selecione o controle de acesso no menu à esquerda.
Selecione Adicionar e, em seguida, selecione Adicionar atribuição de função.
Em Funções de trabalho, selecione Usuário dos Serviços Cognitivos OpenAI e selecione Avançar.
Em Membros, selecione Identidade gerenciada e, em seguida, selecione Membros.
Filtre por assinatura e tipo de recurso (serviços de pesquisa) e selecione a identidade gerenciada do serviço de pesquisa.
Selecione Examinar + atribuir.

Exemplos de cadeia de conexão

Lembre-se da descrição dos cenários de que você pode usar identidades gerenciadas em cadeias de conexão para outros recursos do Azure. Esta seção fornece exemplos.

As conexões de identidade gerenciada atribuídas pelo sistema usam versões de API REST geralmente disponíveis. As conexões de identidade gerenciada atribuídas pelo usuário usam a API REST versão 2026-04-01 ou posterior, exceto para conexões de cache de enriquecimento, que ainda exigem uma versão prévia da API.

Dica

Você pode criar a maioria desses objetos no portal Azure, especificando um sistema ou uma identidade gerenciada atribuída pelo usuário e, em seguida, exibir a definição JSON para obter o cadeia de conexão.

Fonte de dados de blob (identidade gerenciada pelo sistema):

Uma fonte de dados do indexador inclui uma credentials propriedade que determina como a conexão é feita com a fonte de dados. O exemplo a seguir mostra um cadeia de conexão especificando a ID de recurso exclusiva de uma conta de armazenamento.

Uma identidade gerenciada pelo sistema é indicada quando uma cadeia de conexão é a ID do recurso exclusiva de um serviço ou aplicativo com reconhecimento do Microsoft Entra ID. Uma identidade gerenciada atribuída pelo usuário é especificada por meio de uma identity propriedade.

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

Fonte de dados de blob (identidade gerenciada pelo usuário):

Há suporte para uma identidade gerenciada atribuída pelo usuário por meio da identity propriedade em SearchIndexerDataSource com a API REST versão 2026-04-01 ou posterior.

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

Repositório de conhecimento (identidade gerenciada pelo sistema):

Uma definição de repositório de conhecimento inclui um cadeia de conexão para Armazenamento do Azure. A cadeia de conexão é a ID de recurso exclusiva da sua conta de armazenamento. Observe que a cadeia de caracteres não inclui contêineres ou tabelas no caminho. Elas são definidas na definição de projeção inserida, não no cadeia de conexão.

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

Repositório de conhecimento (identidade gerenciada pelo usuário):

É suportada uma identidade gerenciada atribuída pelo usuário através da propriedade identity em SearchIndexerKnowledgeStore com a API REST versão 2026-04-01 ou posterior.

"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 (versão prévia):

Um indexador cria, usa e lembra o contêiner usado para os enriquecimentos armazenados em cache. Não é necessário incluir o contêiner no cache cadeia de conexão. Você pode encontrar a ID do objeto na página Identity do serviço de pesquisa no portal do 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 é executada no portal do Azure e usa um cadeia de conexão quando você inicia a sessão. Você pode colar uma cadeia de caracteres semelhante ao exemplo a seguir.

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

Habilidade personalizada:

Uma habilidade personalizada tem como destino o ponto de extremidade de uma função do Azure ou de um aplicativo que hospeda código personalizado.

uri é o ponto de extremidade da função ou aplicativo.
authResourceId instrui o serviço de pesquisa a se conectar usando uma identidade gerenciada, passando a ID do aplicativo da função ou do aplicativo de destino 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 conexão para modelos

Para conexões feitas usando identidades gerenciadas, esta seção mostra exemplos de informações de conexão usadas por um serviço de pesquisa para se conectar a um modelo em outro recurso. Uma conexão por meio de uma identidade gerenciada pelo sistema é transparente; a identidade e as funções estão em vigor e a conexão é bem-sucedida se elas estiverem configuradas corretamente. Por outro lado, uma identidade gerenciada pelo usuário requer propriedades de conexão extras.

Azure OpenAI embedding skill e Azure OpenAI vetorizador:

Uma habilidade de incorporação e vetorização do OpenAI do Azure na Pesquisa de IA tem como alvo o ponto de extremidade de um OpenAI do Azure que hospeda um modelo de incorporação. O ponto de extremidade é especificado na definição de habilidade de incorporação do OpenAI do Azure e/ou na definição do vetorizador OpenAI do Azure.

A identidade gerenciada pelo sistema é usada automaticamente se "apikey" e "authIdentity" estiver vazia, conforme demonstrado no exemplo a seguir. A "authIdentity" propriedade é usada somente para identidade gerenciada atribuída pelo usuário.

Exemplo de identidade gerenciada pelo 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 gerenciada atribuída pelo sistema. Um vetorizador é especificado em um í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 gerenciada atribuída pelo usuário:

Uma identidade gerenciada atribuída pelo usuário é usada se "apiKey" estiver vazio e um "authIdentity" válido for fornecido.

{
  "@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 gerenciada atribuída pelo usuário. Um vetorizador é especificado em um í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>"
          }
      }
    }
  ]

Verificar o acesso ao firewall

Se o recurso Azure estiver por trás de um firewall, verifique se há uma regra de entrada que admite solicitações do serviço de pesquisa e do portal do Azure.

Para conexões de mesma região com o Armazenamento de Blobs do Azure ou Azure Data Lake Storage Gen2, use uma identidade gerenciada pelo sistema e a exceção de serviço confiável. Opcionalmente, você pode configurar uma regra de instância de recurso para admitir solicitações.
Para todos os outros recursos e conexões, configure uma regra de firewall de IP que admite solicitações de Pesquisa de IA do Azure . Consulte o acesso Indexer ao conteúdo protegido por recursos de segurança de rede Azure para obter detalhes.

Consulte também

Comentários

Esta página foi útil?

Última atualização em 2026-07-03