Configurar uma conexão de indexador para SQL do Azure 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.

Este artigo explica como configurar uma conexão de indexador para Banco de Dados SQL do Azure usando uma identidade gerenciada em vez de fornecer credenciais no cadeia de conexão.

Você pode usar uma identidade gerenciada atribuída pelo sistema ou uma identidade gerenciada atribuída pelo usuário. As identidades gerenciadas são IDs de entrada do Microsoft Entra e exigem atribuições de função do Azure para acessar dados no SQL do Azure.

Pré-requisitos

Crie uma identidade gerenciada para seu serviço de pesquisa.
Atribua uma função de administrador Azure no SQL. A identidade usada na conexão do indexador precisa de permissões de leitura. Você deve ser um administrador Microsoft Entra com um servidor no Banco de Dados SQL ou Instância Gerenciada de SQL para conceder permissões de leitura em um banco de dados.
Você deve estar familiarizado com os conceitos e a configuração do indexador.

1 – Atribuir permissões para ler o banco de dados

Siga as etapas abaixo para atribuir o serviço de pesquisa ou a permissão de identidade gerenciada atribuída pelo usuário para ler o banco de dados.

Conecte-se ao Visual Studio.
Autentique-se com sua conta Microsoft Entra.

Execute os seguintes comandos:

Inclua os colchetes ao redor do nome do serviço de pesquisa ou do nome de identidade gerenciada atribuído pelo usuário.

CREATE USER [insert your search service name here or user-assigned managed identity name] FROM EXTERNAL PROVIDER;
EXEC sp_addrolemember 'db_datareader', [insert your search service name here or user-assigned managed identity name];

Se posteriormente você alterar a identidade do serviço de pesquisa ou a identidade atribuída pelo usuário após atribuir permissões, será necessário remover a associação de função e remover o usuário no banco de dados SQL e, em seguida, repetir a atribuição de permissão. A remoção da associação de função e do usuário pode ser realizada executando os seguintes comandos:

sp_droprolemember 'db_datareader', [insert your search service name or user-assigned managed identity name];

DROP USER IF EXISTS [insert your search service name or user-assigned managed identity name];

2 – Adicionar uma atribuição de função

Nesta seção, você concederá permissão para o serviço Pesquisa de IA do Azure ler dados do seu SQL Server. Para obter etapas detalhadas, consulte Atribuir funções do Azure usando o portal do Azure.

No portal Azure, navegue até a página Azure SQL Server.
Selecione controle de acesso (IAM).
Selecione Adicionar > atribuição de função.
Na guia Função , selecione a função Leitor apropriada.
Na guia Membros , selecione Identidade gerenciada e selecione Selecionar membros.
Selecione sua assinatura Azure.
Se você estiver usando uma identidade gerenciada atribuída pelo sistema, selecione a identidade gerenciada atribuída pelo sistema, pesquise seu serviço de pesquisa e selecione-a.
Caso contrário, se você estiver usando uma identidade gerenciada atribuída pelo usuário, selecione a identidade gerenciada atribuída pelo usuário, pesquise o nome da identidade gerenciada atribuída pelo usuário e selecione-a.
Na guia Revisão + atribuição , selecione Examinar + atribuir para atribuir a função.

3 – Criar a fonte de dados

Crie a fonte de dados e forneça uma identidade gerenciada atribuída pelo sistema ou uma identidade gerenciada atribuída pelo usuário.

Identidade gerenciada atribuída pelo sistema

A API REST, o portal Azure e os SDKs do Azure oferecem suporte à identidade gerenciada atribuída pelo sistema.

Quando você estiver se conectando a uma identidade gerenciada atribuída pelo sistema, a única alteração na definição da fonte de dados é o formato da propriedade "credenciais". Você fornecerá um nome de catálogo ou banco de dados inicial e um ResourceId sem chave de conta ou senha. O ResourceId deve incluir a ID da assinatura de Banco de Dados SQL do Azure, o grupo de recursos do Banco de Dados SQL e o nome do banco de dados SQL.

Veja um exemplo de como criar uma origem de dados para indexar dados de uma conta de armazenamento usando a API REST Create Data Source e uma cadeia de conexão de identidade gerenciada. O formato da cadeia de conexão de identidade gerenciada é o mesmo para a API REST, o SDK do .NET e o portal do Azure.

POST https://[service name].search.windows.net/datasources?api-version=2026-04-01
Content-Type: application/json
api-key: [admin key]

{
    "name" : "sql-datasource",
    "type" : "azuresql",
    "credentials" : { 
        "connectionString" : "Database=[SQL database name];ResourceId=/subscriptions/[subscription ID]/resourceGroups/[resource group name]/providers/Microsoft.Sql/servers/[SQL Server name];Connection Timeout=30;"
    },
    "container" : { 
        "name" : "my-table" 
    }
}

Identidade gerenciada atribuída pelo usuário

A API REST versão 2026-04-01 e posterior dá suporte a conexões com base em uma identidade gerenciada atribuída pelo usuário. Quando você estiver se conectando a uma identidade gerenciada atribuída pelo usuário, há duas alterações na definição da fonte de dados:

Primeiro, o formato da propriedade "credenciais" é um nome de catálogo ou banco de dados inicial e um ResourceId que não tem chave de conta ou senha. O ResourceId deve incluir a ID da assinatura de Banco de Dados SQL do Azure, o grupo de recursos do Banco de Dados SQL e o nome do banco de dados SQL. Esse é o mesmo formato que a identidade gerenciada atribuída pelo sistema.
Em segundo lugar, adicione uma propriedade "identity" que contém a coleção de identidades gerenciadas atribuídas pelo usuário. Somente uma identidade gerenciada atribuída pelo usuário deve ser fornecida ao criar a fonte de dados. Defina-a com o tipo "userAssignedIdentities".

Aqui está um exemplo de como criar um objeto de fonte de dados do indexador usando fontes de dados – Criar ou atualizar:

POST https://[service name].search.windows.net/datasources?api-version=2026-04-01
Content-Type: application/json
api-key: [admin key]

{
    "name" : "sql-datasource",
    "type" : "azuresql",
    "credentials" : { 
        "connectionString" : "Database=[SQL database name];ResourceId=/subscriptions/[subscription ID]/resourceGroups/[resource group name]/providers/Microsoft.Sql/servers/[SQL Server name];Connection Timeout=30;"
    },
    "container" : { 
        "name" : "my-table" 
    },
    "identity" : { 
        "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
        "userAssignedIdentity" : "/subscriptions/[subscription ID]/resourcegroups/[resource group name]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[managed identity name]"
    }
}

4 – Criar o índice

O índice especifica os campos em um documento, atributos e outros constructos que moldam a experiência de pesquisa.

Aqui está uma chamada à API REST criar índice com um campo pesquisável booktitle :

POST https://[service name].search.windows.net/indexes?api-version=2026-04-01
Content-Type: application/json
api-key: [admin key]

{
    "name" : "my-target-index",
    "fields": [
        { "name": "id", "type": "Edm.String", "key": true, "searchable": false },
        { "name": "booktitle", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false }
    ]
}

5 – Criar o indexador

Um indexador conecta uma fonte de dados com um índice de pesquisa de destino e fornece um agendamento para automatizar a atualização de dados. Depois que o índice e a fonte de dados tiverem sido criados, você estará pronto para criar o indexador. Se o indexador for bem-sucedido, a sintaxe de conexão e as atribuições de função serão válidas.

Aqui está uma chamada Create Indexer API REST com uma definição de indexador SQL do Azure. O indexador é executado quando você envia a solicitação.

POST https://[service name].search.windows.net/indexers?api-version=2026-04-01
Content-Type: application/json
api-key: [admin key]

{
    "name" : "sql-indexer",
    "dataSourceName" : "sql-datasource",
    "targetIndexName" : "my-target-index"
}

Se você receber um erro quando o indexador tentar se conectar à fonte de dados que diz que o cliente não tem permissão para acessar o servidor, examine os erros comuns do indexador.

Consulte também

SQL do Azure indexador

Comentários

Esta página foi útil?

Last updated on 2026-07-03