Configurar uma ligação indexadora ao SQL do Azure usando uma identidade gerida

Este artigo explica como configurar uma ligação indexadora ao Base de Dados SQL do Azure usando uma identidade gerida em vez de fornecer credenciais na cadeia de ligação.

Pode usar uma identidade gerida atribuída pelo sistema ou uma identidade gerida atribuída pelo utilizador. Identidades geridas são logins Microsoft Entra e requerem atribuições de funções no Azure para aceder a dados no SQL do Azure.

Pré-requisitos

• Crie uma identidade gerida para o seu serviço de pesquisa.

• Atribui um papel de administrador Azure em SQL. A identidade usada na ligação ao indexador necessita de permissões de leitura. Deve ser administrador Microsoft Entra com um servidor em SQL Database ou SQL Managed Instance para conceder permissões de leitura numa base de dados.

• Deves estar familiarizado com os conceitos e configurações dos indexadores.

1 - Atribuir permissões para ler a base de dados

Siga os passos abaixo para atribuir ao serviço de pesquisa ou à identidade gerida atribuída pelo utilizador permissão para ler a base de dados.

1. Liga-te ao Visual Studio.

   

2. Autentique com a sua conta Microsoft Entra.

   

3. Execute os seguintes comandos:

   Inclua os parênteses em torno do seu nome do serviço de pesquisa ou do nome de identidade gerida atribuído pelo utilizador.

   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 mais tarde alterar a identidade do serviço de pesquisa ou a identidade atribuída pelo utilizador após atribuir permissões, deve remover a pertença ao papel e remover o utilizador na base de dados SQL, repetindo depois a atribuição de permissões. A remoção da associação a funções e do utilizador pode ser feita 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 secção, vais dar permissão ao teu serviço Pesquisa de IA do Azure para ler dados do teu SQL Server. Para passos detalhados, consulte Atribuir Azure funções usando o portal Azure.

1. No portal Azure, navegue até à sua página Azure SQL Server.

2. Selecionar controlo de acesso (IAM).

3. Selecionar Adicionar > atribuir funções.

   

4. No separador Função , selecione o papel Leitor apropriado.

5. No separador Membros , selecione Identidade Gerida e depois selecione Selecionar membros.

6. Selecione a sua subscrição do Azure.

7. Se estiveres a usar uma identidade gerida atribuída pelo sistema, seleciona identidade gerida atribuída ao sistema, procura o teu serviço de pesquisa e depois seleciona-o.

8. Caso contrário, se estiver a usar uma identidade gerida atribuída pelo utilizador, selecione Identidade gerida atribuída pelo utilizador, procure o nome da identidade gerida atribuída pelo utilizador e depois selecione-a.

9. No separador Rever + atribuir, selecione Rever + atribuir para atribuir a função.

3 - Criar a fonte de dados

Crie a fonte de dados e forneça uma identidade gerida atribuída pelo sistema ou uma identidade gerida atribuída pelo utilizador.

Identidade gerida atribuída pelo sistema

A API REST, o portal Azure e a identidade gerida atribuída ao sistema de suporte SDKs do Azure.

Quando se conecta a uma identidade gerida atribuída pelo sistema, a única alteração na definição da fonte de dados é o formato da propriedade "credenciais". Fornecerá um nome de Catálogo Inicial ou Base de Dados e um ResourceID que não tem chave de conta nem palavra-passe. O ResourceId deve incluir o ID de subscrição do Base de Dados SQL do Azure, o grupo de recursos do SQL Database e o nome da base de dados SQL.

Aqui está um exemplo de como criar uma fonte de dados para indexar dados de uma conta de armazenamento usando a API REST Create Data Source e uma cadeia de ligação de identidade gerida. O formato da string de conexão de identidade gerida é o mesmo para a API REST, o SDK .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 gerida atribuída pelo utilizador

API REST versão 2026-04-01 e posteriores suportam ligações baseadas numa identidade gerida atribuída pelo utilizador. Quando se liga a uma identidade gerida atribuída pelo utilizador, há duas alterações na definição da fonte de dados:

• Primeiro, o formato da propriedade "credenciais" é um nome de Catálogo Inicial ou Base de Dados e um ResourceId que não tem chave de conta nem palavra-passe. O ResourceId deve incluir o ID de subscrição do Base de Dados SQL do Azure, o grupo de recursos do SQL Database e o nome da base de dados SQL. Este é o mesmo formato da identidade gerida atribuída pelo sistema.

• Em segundo lugar, adicionar uma propriedade de "identidade" que contenha a coleção de identidades geridas atribuídas pelo utilizador. Apenas uma identidade gerida atribuída pelo utilizador deve ser fornecida na criação da fonte de dados. Defina para o tipo "userAssignedIdentities".

Aqui está um exemplo de como criar um objeto fonte de dados 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 num documento, atributos e outros construtos que moldam a experiência de pesquisa.

Aqui está uma chamada API REST Create Index com campo booktitle pesquisável:

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 liga uma fonte de dados a um índice de pesquisa alvo e fornece um calendário para automatizar a atualização dos dados. Depois de criados o índice e a fonte de dados, está pronto para criar o indexador. Se o indexador for bem-sucedido, a sintaxe de ligação e as atribuições de papéis são válidas.

Aqui está uma chamada à API REST Create Indexer com uma definição de indexador SQL do Azure. O indexador executa assim que você submete o pedido.

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 aparecer um erro quando o indexador tenta ligar-se à fonte de dados que diz que o cliente não pode aceder ao servidor, veja os erros comuns do indexador.

Ver também

Indexador do SQL do Azure