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

2025-08-27

Você pode usar entidades de segurança do Microsoft Entra ID e atribuições de função para conexões de saída da Pesquisa de IA do Azure para outros recursos do Azure que fornecem dados, IA aplicada ou vetorização durante a indexação ou 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 uma cadeia de conexão ou código.

Pré-requisitos

Um serviço de pesquisa na camada Básica ou superior, em qualquer região.
Um recurso do Azure que aceita solicitações de entrada de uma entidade de segurança do Microsoft Entra que tenha uma atribuição de função válida.
Para criar uma identidade gerenciada, você deve ser um Proprietário ou Administrador de Acesso de Usuário. Para atribuir funções, você deve ser um Proprietário, Administrador de Acesso de 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 suportados

Você pode usar identidades gerenciadas para esses cenários.

Cenário	Sistema	Atribuída pelo utilizador
Conectar-se a fontes de dados do indexador¹	Yes	^Sim²
Conecte-se a modelos de incorporação e conclusão de bate-papo no Azure OpenAI, Azure AI Foundry e Azure Functions por meio de habilidades/vetorizadores ³	Yes	Yes
Conectar-se ao Azure Key Vault para chaves gerenciadas pelo cliente	Yes	Yes
Conectar-se a sessões de depuração (hospedadas no Armazenamento do Azure)¹	Yes	Não
Conectar-se a um cache de enriquecimento (hospedado no Armazenamento do Azure)^1,4	Yes	^Sim²
Conectar-se a um Repositório de Conhecimento (hospedado no Armazenamento do Azure)¹	Yes	^Sim²

¹ Para a conectividade entre pesquisa e armazenamento, a segurança de rede impõe restrições sobre o tipo de identidade gerenciada que você pode usar. Somente uma identidade gerenciada pelo 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 da regra de instância de recurso. Consulte Acesso a uma conta de armazenamento protegida pela rede para obter detalhes.

² As identidades gerenciadas atribuídas pelo usuário podem ser usadas em cadeias de conexão de fonte de dados. No entanto, apenas as APIs REST de visualização mais recentes e os pacotes de visualização oferecem suporte a uma identidade gerenciada atribuída pelo usuário em uma cadeia de conexão. Certifique-se de alternar para uma API de visualização se você definir SearchIndexerDataUserAssignedIdentity como o identity em uma conexão de fonte de dados.

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

⁴ O serviço de pesquisa de IA atualmente não pode se conectar a tabelas em uma conta de armazenamento que tenha o acesso à chave compartilhada desativado.

Criar uma identidade gerenciada pelo sistema

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

Você pode ter uma identidade gerenciada atribuída ao sistema para cada serviço de pesquisa. É exclusivo para o seu serviço de pesquisa e vinculado ao serviço durante toda a sua vida.

Quando você habilita uma identidade gerenciada atribuída ao sistema, a ID do Microsoft Entra cria uma entidade de segurança para seu 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.

Entre no portal do Azure e encontre seu serviço de pesquisa.
No painel esquerdo, selecione Configurações>Identidade.
Na guia Sistema atribuído, em Status, selecione Ativado.
Selecione Guardar.

Depois de salvar as configurações, a página é atualizada para mostrar um identificador de objeto atribuído ao seu 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 ao sistema.

Criar uma identidade gerenciada atribuída pelo usuário

Uma identidade gerenciada atribuída pelo usuário é um recurso do Azure que pode ter 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 nas atribuições de função. Por exemplo, você pode querer identidades separadas para diferentes aplicativos e cenários. Como um recurso criado e gerenciado independentemente, ele não está vinculado ao serviço em si.

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

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

A associação de uma identidade gerenciada atribuída pelo usuário a um serviço de Pesquisa do Azure AI é suportada no portal do Azure, nas APIs REST de Gerenciamento de Pesquisa e nos pacotes SDK que fornecem o recurso.

Portal do Azure
API REST

Inicie sessão 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 até que o recurso termine a implantação.

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

Em vez do portal do Azure, você pode usar as APIs REST de 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 para o tipo de identidade.
- Os valores válidos são SystemAssigned, UserAssignedou SystemAssigned, UserAssigned para ambos.
- Um valor de None limpa 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 as permissões do serviço de pesquisa no recurso do 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 no Cofre de Chaves do Azure.
São necessárias permissões de gravação para funcionalidades de enriquecimento de IA que utilizam o Azure Storage para hospedar dados de sessões de depuração, cache de enriquecimento e armazenamento de conteúdo a longo prazo num repositório de conhecimento.

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

Entre no portal do Azure com sua conta do Azure e vá para seu recurso do Azure OpenAI.
Selecione Controle de acesso no menu à esquerda.
Selecione Adicionar e, em seguida, selecione Adicionar atribuição de função.
Em Funções de cargos de trabalho, selecione Usuário OpenAI de Serviços Cognitivos e, em seguida, selecione Avançar.
Em Membros, selecione Identidade gerenciada e, em seguida, selecione Membros.
Filtre por subscrição e tipo de recurso (serviços de Pesquisa) e, em seguida, selecione a identidade gerida do seu serviço de pesquisa.
Selecione Verificar + atribuir.

Exemplos de cadeia de conexão

Lembre-se na descrição dos cenários de que você pode usar identidades gerenciadas em cadeias de conexão para outros recursos do Azure. Esta secção fornece exemplos. Você pode usar versões da API REST geralmente disponíveis e pacotes do SDK do Azure para conexões usando uma identidade gerenciada atribuída ao sistema.

Sugestão

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

Aqui estão alguns exemplos de cadeias de conexão para vários cenários.

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

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

Uma identidade gerida pelo sistema é indicada quando uma cadeia de ligações é a ID de recurso exclusiva de um serviço ou aplicação integrada com o 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):

As identidades gerenciadas atribuídas pelo usuário também podem ser usadas em cadeias de conexão de fonte de dados do indexador. No entanto, apenas as APIs REST de visualização mais recentes e os pacotes de visualização oferecem suporte a uma identidade gerenciada atribuída pelo usuário em uma cadeia de conexão de fonte de dados. Certifique-se de alternar para uma versão de visualização se você definir SearchIndexerDataUserAssignedIdentity como a identidade em uma conexão de fonte de dados.

Uma identidade de usuário do identity serviço de pesquisa é especificada na propriedade.

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

Loja de conhecimento:

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

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

Cache de enriquecimento:

Um indexador cria, usa e lembra o contêiner usado para os enriquecimentos em cache. Não é necessário incluir o contêiner na cadeia de conexão de cache. Você pode encontrar a ID do objeto na página Identidade do seu 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 uma 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 alvo o ponto de extremidade de uma função do Azure ou aplicativo que hospeda código personalizado.

uri é o ponto de extremidade da função ou aplicativo.
authResourceId indica ao serviço de pesquisa para se conectar usando uma identidade gerida, passando a ID do aplicativo da função ou app 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 através de uma identidade gerenciada pelo sistema é transparente; A identidade e as funções estão estabelecidas, e a conexão será bem-sucedida se estiverem configuradas corretamente. Por outro lado, uma identidade gerenciada pelo usuário requer propriedades de conexão extras.

Habilidade de incorporação do Azure OpenAI e vetorizador do Azure OpenAI:

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

A identidade gerenciada pelo sistema é usada automaticamente se "apikey" e "authIdentity" estiver vazia, como demonstrado no exemplo a seguir. A "authIdentity" propriedade é usada apenas 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 ao 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 gerida atribuída ao utilizador é 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 seu recurso do Azure estiver protegido por um firewall, verifique se há uma regra de entrada que admite solicitações do seu serviço de pesquisa e do portal do Azure.

Para ligações na mesma região com o Armazenamento de Blobs do Azure ou o Azure Data Lake Storage Gen2, utilize uma identidade gerida 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 IP que admita solicitações do Azure AI Search. Consulte Acesso do indexador ao conteúdo protegido pelos recursos de segurança de rede do Azure para obter detalhes.

Ver também

Comentários

Esta página foi útil?