Criar um link privado compartilhado para uma instância gerenciada do SQL a partir da Pesquisa de IA do Azure

Artigo
02/25/2025

Este artigo explica como configurar um indexador no Azure AI Search para uma conexão privada com uma instância gerenciada do SQL que é executada em uma rede virtual. A conexão privada é por meio de um link privado compartilhado e do Azure Private Link.

Em uma conexão privada com uma instância gerenciada, o FQDN (nome de domínio totalmente qualificado) da instância deve incluir a Zona DNS. Atualmente, apenas a API REST do Azure AI Search Management fornece um dnsZonePrefix parâmetro para aceitar a especificação da zona DNS.

Embora você possa chamar a API REST de Gerenciamento diretamente, é mais fácil usar o módulo CLI az rest do Azure para enviar chamadas da API REST de Gerenciamento de uma linha de comando. Este artigo usa a CLI do Azure com REST para configurar o link privado.

Nota

Este artigo refere-se ao portal do Azure para obter propriedades e confirmar etapas. No entanto, ao criar o link privado compartilhado para a Instância Gerenciada do SQL, verifique se você está usando a API REST. Embora a guia Rede liste Microsoft.Sql/managedInstances como uma opção, o portal do Azure atualmente não oferece suporte ao formato de URL estendido usado pela Instância Gerenciada do SQL.

Pré-requisitos

CLI do Azure
Azure AI Search, Basic ou superior. Se você estiver usando o enriquecimento de IA e conjuntos de habilidades, use o Padrão 2 (S2) ou superior. Consulte Limites de serviço para obter detalhes.
Instância Gerenciada SQL do Azure, configurada para ser executada em uma rede virtual.
Você deve ter um mínimo de permissões de Colaborador na Pesquisa de IA do Azure e na Instância Gerenciada do SQL.
Cadeia de conexão da Instância Gerenciada SQL do Azure. Atualmente, a identidade gerenciada não é suportada com o link privado compartilhado. Sua cadeia de conexão deve incluir um nome de usuário e senha.

Nota

Os links privados compartilhados são faturáveis por meio dos preços do Link Privado do Azure e os encargos são faturados com base no uso.

1 - Recuperar informações de conexão

Nesta seção, obtenha a zona DNS do nome do host e de uma cadeia de conexão.

No portal do Azure, localize o objeto de instância gerenciada SQL.
Na guia Visão Geral, localize a propriedade Host. Copie a parte da zona DNS do FQDN para a próxima etapa. A zona DNS faz parte do nome de domínio da Instância Gerenciada SQL. Por exemplo, se o FQDN da Instância Gerenciada SQL for my-sql-managed-instance.a1b22c333d44.database.windows.net, a zona DNS será a1b22c333d44.
Na guia Cadeias de conexão, copie a cadeia de conexão ADO.NET para uma etapa posterior. É necessário para a conexão da fonte de dados ao testar a conexão privada.

Para obter mais informações sobre propriedades de conexão, consulte Criar uma instância gerenciada SQL do Azure.

2 - Crie o corpo do pedido

Usando um editor de texto, crie o JSON para o link privado compartilhado.
```
{
    "name": "{{shared-private-link-name}}",
    "properties": {
        "privateLinkResourceId": "/subscriptions/{{target-resource-subscription-ID}}/resourceGroups/{{target-resource-rg}}/providers/Microsoft.Sql/managedInstances/{{target-resource-name}}",
        "dnsZonePrefix": "a1b22c333d44",
        "groupId": "managedInstance",
        "requestMessage": "please approve"
    }
}
```
Forneça um nome significativo para o link privado compartilhado. O link privado compartilhado aparece ao lado de outros pontos de extremidade privados. Um nome como "shared-private-link-for-search" pode lembrá-lo de como é usado.

Cole o nome da zona DNS em "dnsZonePrefix" que você recuperou em uma etapa anterior.

Edite o "privateLinkResourceId", substituto válido para valores para os espaços reservados. Forneça uma ID de assinatura válida, nome do grupo de recursos e nome da instância gerenciada.
Salve o arquivo localmente como create-pe.json (ou use outro nome, lembrando-se de atualizar a sintaxe da CLI do Azure na próxima etapa).
Na CLI do Azure, digite dir para anotar o local atual do arquivo.

3 - Crie um link privado compartilhado

Na linha de comando, entre no Azure usando az logino .
Se tiver várias subscrições, certifique-se de que está a utilizar a que pretende utilizar: az account show.

Para definir a assinatura, use az account set --subscription {{subscription ID}}
Chame o az rest comando para usar a API REST de Gerenciamento do Azure AI Search.

Como o suporte a links privados compartilhados para instâncias gerenciadas SQL ainda está em visualização, você precisa de uma versão de visualização da API REST de gerenciamento. Use 2021-04-01-preview ou uma versão posterior da API de visualização para esta etapa. Recomendamos o uso da versão mais recente da API de visualização.
```
az rest --method put --uri https://management.azure.com/subscriptions/{{search-service-subscription-ID}}/resourceGroups/{{search service-resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}/sharedPrivateLinkResources/{{shared-private-link-name}}?api-version=2024-06-01-preview --body @create-pe.json
```
Forneça a ID da assinatura, o nome do grupo de recursos e o nome do serviço do seu recurso Azure AI Search.

Forneça o mesmo nome de link privado compartilhado que você especificou no corpo JSON.

Forneça um caminho para o arquivo create-pe.json se você tiver navegado para fora do local do arquivo. Você pode digitar dir na linha de comando para confirmar que o arquivo está no diretório atual.
Execute o comando .

Ao concluir essas etapas, você deve ter um link privado compartilhado provisionado em um estado pendente. Leva vários minutos para criar o link. Depois de criado, o proprietário do recurso precisa aprovar a solicitação antes que ela esteja operacional.

Você pode verificar o status do link privado compartilhado no portal do Azure. Na página do serviço de pesquisa, em Propriedades de Configurações>, role para baixo para encontrar os recursos de link privado compartilhado e exibir o valor JSON. Quando o estado de provisionamento mudar de pendente para bem-sucedido, você poderá continuar para a próxima etapa.

4 - Aprovar a conexão de ponto final privado

No lado da Instância Gerenciada SQL, o proprietário do recurso deve aprovar a solicitação de conexão privada que você criou.

No portal do Azure, abra as conexões de ponto de extremidade Privado de Segurança>da instância gerenciada.
Encontre a seção que lista as conexões de ponto de extremidade privadas.
Selecione a conexão e, em seguida, selecione Aprovar. Pode levar alguns minutos para que o status seja atualizado no portal do Azure.

Depois que o ponto de extremidade privado é aprovado, o Azure AI Search cria os mapeamentos de zona DNS necessários na zona DNS criada para ele.

5 - Verifique o status do link privado compartilhado

No lado da Pesquisa de IA do Azure, você pode confirmar a aprovação da solicitação revisitando a guia Acesso Privado Compartilhado da página Rede do serviço de pesquisa. O estado da conexão deve ser aprovado.

6 - Configure o indexador para ser executado no ambiente privado

Agora você pode configurar um indexador e sua fonte de dados para usar uma conexão privada de saída com sua instância gerenciada.

Este artigo pressupõe um cliente REST e usa as APIs REST.

Crie a definição da fonte de dados como faria normalmente para o SQL do Azure. Por padrão, uma instância gerenciada escuta na porta 3342, mas em uma rede virtual escuta na 1433.

Forneça a cadeia de conexão que você copiou anteriormente com um Catálogo Inicial definido para o nome do banco de dados.

POST https://myservice.search.windows.net/datasources?api-version=2024-07-01
 Content-Type: application/json
 api-key: admin-key
 {
     "name" : "my-sql-datasource",
     "description" : "A database for testing Azure AI Search indexes.",
     "type" : "azuresql",
     "credentials" : { 
         "connectionString" : "Server=tcp:contoso.a1b22c333d44.database.windows.net,1433;Persist Security Info=false; User ID=<your user name>; Password=<your password>;MultipleActiveResultsSets=False; Encrypt=True;Connection Timeout=30;Initial Catalog=<your database name>"
        },
     "container" : { 
         "name" : "Name of table or view to index",
         "query" : null (not supported in the Azure SQL indexer)
         },
     "dataChangeDetectionPolicy": null,
     "dataDeletionDetectionPolicy": null,
     "encryptionKey": null
 }

Crie a definição do indexador, definindo o indexador executionEnvironment como "private".

A execução do indexador ocorre em um ambiente de execução privado específico para seu serviço de pesquisa ou em um ambiente multilocatário hospedado pela Microsoft e usado para descarregar o processamento dispendioso do conjunto de habilidades para vários clientes. Ao se conectar por meio de um ponto de extremidade privado, a execução do indexador deve ser privada.
```
 POST https://myservice.search.windows.net/indexers?api-version=2024-07-01
  Content-Type: application/json
  api-key: admin-key
    {
     "name": "indexer",
     "dataSourceName": "my-sql-datasource",
     "targetIndexName": "my-search-index",
     "parameters": {
         "configuration": {
             "executionEnvironment": "private"
         }
     },
     "fieldMappings": []
     }
```
Execute o indexador. Se a execução do indexador for bem-sucedida e o índice de pesquisa for preenchido, o link privado compartilhado estará funcionando.

Você pode monitorar o status do indexador no portal do Azure ou usando a API de Status do Indexador.

Você pode usar o Gerenciador de Pesquisa no portal do Azure para verificar o conteúdo do índice.

7 - Teste o link privado compartilhado

Se você executou o indexador na etapa anterior e indexou com êxito o conteúdo da instância gerenciada, o teste foi bem-sucedido. No entanto, se o indexador falhar ou não houver conteúdo no índice, você poderá modificar seus objetos e repetir o teste escolhendo qualquer cliente que possa invocar uma solicitação de saída de um indexador.

Uma opção fácil é executar um indexador no portal do Azure, mas você também pode tentar um cliente REST e APIs REST para obter mais precisão. Supondo que seu serviço de pesquisa também não esteja configurado para uma conexão privada, a conexão do cliente REST com o Azure AI Search pode ser pela Internet pública.

Aqui estão alguns lembretes para testes:

Se você usar um cliente REST, use a API REST de gerenciamento e a versão da API 2021-04-01-Preview para criar o link privado compartilhado. Use a API REST de pesquisa e uma versão estável da API para criar e invocar indexadores e fontes de dados.
Você pode usar o assistente Importar dados para criar um indexador, fonte de dados e índice. No entanto, o indexador gerado não terá a configuração correta do ambiente de execução.
Você pode editar a fonte de dados e o indexador JSON no portal do Azure para alterar propriedades, incluindo o ambiente de execução e a cadeia de conexão.
Você pode redefinir e executar novamente o indexador no portal do Azure. A redefinição é importante para esse cenário porque força um reprocessamento completo de todos os documentos.
Você pode usar o explorador de pesquisa para verificar o conteúdo do índice.

Partilhar via