Configurar uma conexão de indexador com o SQL do Azure usando uma identidade gerenciada

Artigo
09/03/2024

Este artigo explica como configurar uma conexão de indexador com o Banco de Dados SQL do Azure usando uma identidade gerenciada em vez de colocar as credenciais na cadeia de conexão.

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

Pré-requisitos

Criar uma identidade gerenciada para o serviço Pesquisa.
Atribua uma função de administrador do Azure no SQL. A identidade usada na conexão do indexador precisa de permissões de leitura. Você deve ser um administrador do Microsoft Entra com um servidor no Banco de Dados SQL ou na 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 ao serviço de pesquisa ou à identidade gerenciada atribuída pelo usuário a permissão para ler o banco de dados.

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

Execute os seguintes comandos:

Inclua os colchetes em volta do nome do serviço de pesquisa ou do nome de identidade gerenciada atribuída 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 você alterar a identidade do serviço de pesquisa ou a identidade atribuída pelo usuário depois de atribuir permissões, deverá remover a associação de função e remover o usuário no banco de dados SQL e 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 sessão, você dará permissão ao seu serviço do Azure AI Search para ler dados do seu SQL Server. Para ver as etapas detalhadas, confira Atribuir funções do Azure usando o portal do Azure.

No portal do Azure, navegue até sua página do Azure SQL Server.
Selecione IAM (Controle de acesso) .
Selecione Adicionar > Adicionar atribuição de função.
Na guia Função, selecione a função de Leitor apropriada.
Na guia Membros, selecione Identidade gerenciadae selecione Selecionar membros.
Selecione sua assinatura do Azure.
Se você estiver usando uma identidade gerenciada atribuída pelo sistema, selecione a identidade gerenciada atribuída pelo sistema, procure o serviço de pesquisa e selecione-o.
Ou se você estiver usando uma identidade gerenciada atribuída pelo usuário, selecione identidade gerenciada atribuída pelo usuário, procure o nome da identidade gerenciada atribuída pelo usuário e selecione-o.
Na guia Examinar + atribuir, 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 (versão prévia).

Identidade gerenciada atribuída pelo sistema

A API REST, o portal do Azure e o SDK .NET dão suporte à identidade gerenciada atribuída pelo sistema.

Quando você está se conectando com uma identidade gerenciada atribuída pelo sistema, a única alteração na definição da fonte de dados é o formato da propriedade "credentials". Você fornecerá nome de Banco de Dados ou Catálogo Inicial e um ResourceId sem chave de conta ou senha. O ResourceId deve incluir a ID da assinatura do 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 fonte de dados para indexar dados de uma conta de armazenamento usando a API REST Criar fonte de dados 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=2024-07-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 (versão prévia)

As APIs REST de versão prévia 2021-04-30 e posteriores dão suporte a conexões com base em uma identidade gerenciada atribuída pelo usuário. Quando você está se conectando com uma identidade gerenciada atribuída pelo usuário, há duas alterações na definição da fonte de dados:

Primeiro, o formato da propriedade "credentials" é o nome do Banco de Dados ou Catálogo Inicial e uma ResourceId que não tenha uma chave de conta ou senha. O ResourceId deve incluir a ID da assinatura do Banco de Dados SQL do Azure, o grupo de recursos do Banco de Dados SQL e o nome do banco de dados SQL. Esse formato é o mesmo que o da identidade gerenciada atribuída pelo sistema.
Em segundo lugar, adicione uma propriedade “identity” que contenha 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 indexador usando a versão mais recente da API de versão prévia para Criar ou atualizar uma fonte de dados:

POST https://[service name].search.windows.net/datasources?api-version=2024-05-01-preview
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 outras construções que modelam a experiência de pesquisa.

Veja uma chamada à API REST Criar índice com um campo pesquisável booktitle:

POST https://[service name].search.windows.net/indexes?api-version=2024-07-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 a um índice de pesquisa de destino e fornece um agendamento para automatizar a atualização de dados. Uma vez que o índice e a fonte de dados forem criados, será possível 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.

Veja uma chamada à API REST Criar indexador com uma definição de indexador do SQL do Azure. O indexador é executado quando você enviar a solicitação.

POST https://[service name].search.windows.net/indexers?api-version=2024-07-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, indicando que o cliente não tem permissão para acessar o servidor, confira erros comuns do indexador.

Confira também

Indexador do SQL do Azure

Compartilhar via