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

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 usuário ou pelo sistema como o princípio de segurança do serviço de pesquisa em um locatário do Microsoft Entra. Quando você tiver uma identidade gerenciada, poderá atribuir funções para acesso autorizado. Identidades gerenciadas e atribuições de função eliminam a necessidade de passar segredos e credenciais em um código ou cadeia de conexão.

Pré-requisitos

Um serviço de pesquisa no nível Básico 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 tem uma atribuição de função válida.
Para criar uma identidade gerenciada, você deve ter as funções Proprietário ou Administrador de Acesso de 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 esses cenários.

Cenário	Sistema	Atribuído pelo usuário
Conectar-se às fontes de dados do indexador¹	Yes	Sim ²
Conectar-se a modelos de preenchimento de chat e inserção no OpenAI do Azure, na Fábrica de IA do Azure e no Azure Functions por meio de habilidades/vetorizadores ³	Yes	Yes
Conectar-se ao Azure Key Vault para chaves gerenciadas pelo cliente	Yes	Yes
Conectar-se às sessões de depuração (hospedadas no Armazenamento do Microsoft Azure)¹	Yes	Não
Conectar-se a um cache de enriquecimento (hospedado no Armazenamento do Microsoft Azure)^1,⁴	Yes	Sim ²
Conectar-se ao Repositório de conhecimento (hospedado no Armazenamento do Microsoft Azure)¹	Yes	Sim ²

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

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

³ As conexões com o OpenAI do Azure, a Fábrica de IA do Azure e o Azure Functions por meio de habilidades/vetorizadores incluem: Habilidades personalizadas, Vetorizadores personalizados, Habilidade de incorporação do OpenAI do Azure, Vetorizador do OpenAI do Azure, Habilidade do AML e Vetorizador de catálogo de modelos da Fábrica de IA do Azure.

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

Criar uma identidade gerenciada do 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.

Entre no portal do Azure e localize seu serviço de pesquisa.
No painel esquerdo, selecione Configurações>Identidade.
Na guia Atribuído pelo sistema, em Status, selecione Ativado.
Clique em Salvar.

Depois de você 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 ao 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 ao 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 ao usuário

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

Você poderá criar várias identidades gerenciadas atribuídas pelo usuário se quiser mais detalhamento 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 serviço em si.

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

Na assinatura do 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.
Em outros serviços do Azure aos quais você deseja se conectar, crie uma atribuição de função para a identidade.

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

Portal do Azure
REST API

Entre no portal do 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 assinatura, grupo de recursos e região. Dê um nome descritivo à identidade.
Selecione Criar e aguarde até que o recurso conclua a implantação.

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 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 do Gerenciamento de Pesquisa para atribuir uma identidade gerenciada atribuída pelo usuário.

Use Serviços – 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": "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 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 para 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 do Azure.

As permissões de leitura são necessárias para conexões de dados do indexador para acessar uma chave gerenciada pelo cliente no 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 da atribuição de função. Este exemplo é para o OpenAI do Azure. Para outros recursos do Azure, consulte Conectar-se ao Armazenamento do Azure, Conectar-se ao Azure Cosmos DB ou Conectar-se ao SQL do Azure.

Entre no portal do Azure com sua conta do Azure e acesse o recurso de OpenAI do Azure.
Selecione Controle de acesso no menu à esquerda.
Selecione Adicionar e selecione Adicionar atribuição de função.
Em Funções de função de trabalho, selecione Usuário de OpenAI dos Serviços Cognitivos e selecione Avançar.
Em Membros selecione Identidade gerenciada e 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 de cenários de que você pode usar identidades gerenciadas em cadeias de conexão para outros recursos do Azure. Esta seção fornece modelos. Você pode usar versões de API REST disponíveis e pacotes do SDK do Azure para conexões usando uma identidade gerenciada atribuída pelo sistema.

Dica

Você pode criar a maioria desses objetos no portal do Microsoft 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 do indexador inclui uma propriedade credentials que determina como a conexão é feita com a fonte de dados. O exemplo a seguir mostra uma 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 propriedade identity.

"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):

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

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

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

Uma definição de repositório de conhecimento inclui uma cadeia de conexão para o Armazenamento do Azure. A cadeia de conexão é a ID de recurso exclusiva de sua conta de armazenamento. Observe que a cadeia de caracteres não inclui contêineres ou tabelas no caminho. Elas são definidas na projeção inserida, 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 aprimoramentos em cache. Não é necessário incluir o contêiner na cadeia de conexão do cache. Encontre a ID de objeto na página Identidade 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 uma cadeia de conexão quando você inicia a sessão. Você pode colar uma cadeia de conexão 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 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.

Habilidade de inserção do Serviço OpenAI e Vetorizador do Serviço OpenAI:

Uma habilidade de incorporação e um vetorizador do OpenAI do Azure na Pesquisa de IA têm 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 Azure OpenAI e/ou na definição do vetorizador Azure OpenAI.

A identidade gerenciada pelo sistema é usada automaticamente se "apikey" e "authIdentity" estiverem vazios, conforme demonstrado no exemplo a seguir. A propriedade"authIdentity" é 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 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 acesso ao firewall

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

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, configure 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. Consulte Acesso do indexador ao conteúdo protegido pelos recursos de segurança de rede do Azure para obter detalhes.

Consulte também

Comentários

Esta página foi útil?

Last updated on 2025-10-31