Criar um link privado compartilhado para uma Instância Gerenciada de SQL do Azure AI Search

Artigo
11/15/2023

Este artigo explica como configurar um indexador no Azure AI Search para uma conexão privada com uma instância gerenciada de SQL que é executada em uma rede virtual.

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 Gerenciamento do Azure AI Search fornece um parâmetro resourceRegion para aceitar a especificação de zona DNS.

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

Observação

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

Pré-requisitos

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

Observação

O Link Privado do Azure é usado internamente, sem custo, para configurar o link privado compartilhado.

1 – Recuperar informações de conexão

Recupere o FQDN da instância gerenciada, incluindo a zona DNS. A zona DNS faz parte do nome de domínio da Instância Gerenciada de SQL. Por exemplo, se o FQDN da Instância Gerenciada de SQL for my-sql-managed-instance.00000000000.database.windows.net, a zona DNS será 00000000000.

No portal do Azure, localize o objeto da instância gerenciada de SQL.
Na guia Visão Geral, localize a propriedade Host. Copie a parte da zona DNS do FQDN para a próxima etapa.
Na guia Cadeias de conexão, copie a cadeia de conexão ADO.NET para uma etapa posterior. Ele é necessário para a conexão da fonte de dados ao testar a conexão privada.

Para obter mais informações sobre os tipos de conexão, confira Criar uma Instância Gerenciada de SQL do Azure.

2 – Criar o corpo da solicitação

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}}",
        "resourceRegion": "a1b22c333d44",
        "groupId": "managedInstance",
        "requestMessage": "please approve",
    }
}

Forneça um nome significativo para o link privado compartilhado. O link privado compartilhado é exibido junto com outros pontos de extremidade privados. Um nome como "shared-private-link-for-search" pode lembrar você de como ele é usado.
Cole o nome da zona DNS em "resourceRegion" que você recuperou em uma etapa anterior.
Edite o "privateLinkResourceId" para refletir o ponto de extremidade privado da instância gerenciada. Forneça a ID da assinatura, o nome do grupo de recursos e o nome do objeto da instância gerenciada.
Salve o arquivo localmente como create-pe.json (ou use outro nome, lembrando de atualizar a sintaxe da CLI do Azure na próxima etapa).
Na CLI do Azure, digite dir para observar o local atual do arquivo.

3 – Criar um link privado compartilhado

Na linha de comando, entre no Azure usando o comando az login.
Se você tiver várias assinaturas, verifique se está usando a que pretende usar: az account show.

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

Como o suporte de link privado compartilhado para instâncias gerenciadas de SQL ainda está em versão prévia, você precisa de uma versão prévia da API REST. Use 2021-04-01-preview para esta etapa.
```
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=2021-04-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 recurso do Azure AI Search.

Forneça o mesmo nome de link privado compartilhado especificado no corpo JSON.

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

Ao concluir essas etapas, você deverá ter um link privado compartilhado provisionado em um estado pendente. São necessários vários minutos para criar o link. Depois de criado, o proprietário do recurso precisa aprovar a solicitação, antes de entrar em operação.

4 – Aprovar a conexão de ponto de extremidade privado

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

No portal do Azure, abra a guia Conexões de ponto de extremidade privado da instância gerenciada.
Localize a seção que lista as conexões de ponto de extremidade privados.
Selecione a conexão e selecione Aprovar. Pode levar alguns minutos para que o status seja atualizado no portal.

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

5 – Verificar o status de link privado compartilhado

No lado do Azure AI Search, você pode confirmar a aprovação da solicitação acessando novamente a guia Acesso privado compartilhado da página Rede do serviço de pesquisa. O estado da conexão deve ser aprovado.

6 - Configurar 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.

Você pode usar o assistente Importar dados para esta etapa, mas o indexador gerado não será válido para esse cenário. Você precisará modificar a propriedade JSON do indexador conforme descrito nesta etapa para torná-la compatível com esse cenário. Em seguida, você precisará redefinir e executar novamente o indexador para testar totalmente o pipeline usando o indexador atualizado.

Este artigo pressupõe um cliente REST e usa as APIs REST para facilitar a visualização de todas as propriedades. Lembre-se de que as chamadas à API REST para indexadores e fontes de dados usam as APIs REST de pesquisa, não as APIs REST de gerenciamento usadas para criar o link privado compartilhado. A sintaxe e as versões da API são diferentes entre as duas APIs REST.

Criar a definição da fonte de dados como você faria normalmente para o SQL do Azure. O formato da cadeia de conexão é ligeiramente diferente para uma instância gerenciada, mas outras propriedades são as mesmas que se você estivesse configurando uma conexão de fonte de dados com o Banco de Dados SQL do Azure.

Forneça a cadeia de conexão copiada anteriormente.

POST https://myservice.search.windows.net/datasources?api-version=2020-06-30
 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.public.0000000000.database.windows.net,1433; Persist Security Info=false; User ID=<your user name>; Password=<your password>;MultipleActiveResultsSets=False; Encrypt=True;Connection Timeout=30;" 
        },
     "container" : { 
         "name" : "Name of table or view to index",
         "query" : null (not supported in the Azure SQL indexer)
         },
     "dataChangeDetectionPolicy": null,
     "dataDeletionDetectionPolicy": null,
     "encryptionKey": null,
     "identity": null
 }

Criar a configuração do indexador, definindo o ambiente de execução do indexador como "privado".

A execução do indexador ocorre em um ambiente privado específico para o serviço de pesquisa ou em um ambiente multilocatário usado internamente para descarregar o processamento de alto custo do conjunto de habilidades para vários clientes. Ao se conectar em um ponto de extremidade privado, a execução do indexador deve ser privada.
```
 POST https://myservice.search.windows.net/indexers?api-version=2020-06-30
  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 – Testar 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 experimentar um cliente REST e as 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 Search pode ser pela Internet pública.

Aqui estão alguns lembretes para teste:

Se você usar um cliente REST, use a API REST de Gerenciamento e a versão prévia da API 01-04-2021 para criar o link privado compartilhado. Use a API REST de Pesquisa e uma versão de API estável para criar e invocar indexadores e fontes de dados.
Você pode usar o assistente de importação de dados para criar um indexador, uma fonte de dados e um í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 as 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 Gerenciador de Pesquisa para verificar o conteúdo do índice.