Faça conexões de saída por meio de um link privado compartilhado

Artigo
04/03/2024

Este artigo explica como configurar chamadas de saída privadas do Azure AI Search para um recurso PaaS do Azure executado em uma rede virtual.

A configuração de uma conexão privada permite que um serviço de pesquisa se conecte a um endereço IP de rede virtual em vez de uma porta aberta para a Internet. O objeto criado para a conexão é chamado de link privado compartilhado. Na conexão, o serviço de pesquisa usa o link privado compartilhado internamente para alcançar um recurso PaaS do Azure dentro do limite da rede.

O link privado compartilhado é um recurso premium que é cobrado pelo uso. Quando você configura um link privado compartilhado, as cobranças pelo ponto de extremidade privado são adicionadas à sua fatura do Azure. À medida que você usa o link privado compartilhado, as taxas de transferência de dados para acesso de entrada e saída também são faturadas. Para obter detalhes, consulte Preços do Link Privado do Azure.

Nota

Se você estiver configurando uma conexão de indexador privado com uma Instância Gerenciada SQL, consulte este artigo .

Quando usar um link privado compartilhado

O Azure AI Search faz chamadas de saída para outros recursos de PaaS do Azure nos seguintes cenários:

O indexador ou mecanismo de pesquisa se conecta ao Azure OpenAI para incorporações de texto em vetor
O indexador se conecta a fontes de dados suportadas
Conexões de indexador (conjunto de habilidades) com o Armazenamento do Azure para enriquecimento de cache, depuração de sessão ou gravação em um repositório de conhecimento
Solicitações de chave de criptografia para o Cofre de Chaves do Azure
Solicitações de habilidades personalizadas para o Azure Functions ou recurso semelhante

Os links privados compartilhados só funcionam para conexões Azure-to-Azure. Se você estiver se conectando ao OpenAI ou outro modelo externo, a conexão deve ser pela internet pública.

Os links privados compartilhados são para operações e dados acessados por meio de um ponto de extremidade privado para recursos ou clientes do Azure executados em uma rede virtual do Azure.

Um link privado compartilhado é:

Criado usando ferramentas, APIs ou SDKs do Azure AI Search
Aprovado pelo proprietário do recurso PaaS do Azure
Usado internamente pela Pesquisa de IA do Azure em uma conexão privada com um recurso específico do Azure

Somente seu serviço de pesquisa pode usar os links privados que ele cria, e pode haver apenas um link privado compartilhado criado em seu serviço para cada combinação de recursos e subrecursos.

Depois de configurar o link privado, ele é usado automaticamente sempre que o serviço de pesquisa se conecta a esse recurso PaaS. Você não precisa modificar a cadeia de conexão ou alterar o cliente que está usando para emitir as solicitações, embora o dispositivo usado para a conexão deva se conectar usando um IP autorizado no firewall do recurso PaaS do Azure.

Há dois cenários para usar o Azure Private Link e o Azure AI Search juntos.

Cenário um: crie um link privado compartilhado quando uma conexão de saída (indexador) com o Azure PaaS exigir uma conexão privada.
Cenário dois: configurar a pesquisa de uma conexão de entrada privada de clientes executados em uma rede virtual.

O cenário um é abordado neste artigo.

Embora ambos os cenários tenham uma dependência do Azure Private Link, eles são independentes. Você pode criar um link privado compartilhado sem ter que configurar seu próprio serviço de pesquisa para um ponto de extremidade privado.

Limitações

Ao avaliar links privados compartilhados para seu cenário, lembre-se dessas restrições.

Vários dos tipos de recursos usados em um link privado compartilhado estão em visualização. Se você estiver se conectando a um recurso de visualização (Banco de Dados do Azure para MySQL, Azure Functions ou Instância Gerenciada SQL do Azure), use uma versão de visualização da API REST de Gerenciamento para criar o link privado compartilhado. Essas versões incluem 2020-08-01-preview, 2021-04-01-preview, e 2024-03-01-preview.
A execução do indexador deve usar o ambiente de execução privado específico do seu serviço de pesquisa. As conexões de ponto de extremidade privado não são suportadas no ambiente multilocatário. A definição de configuração para este requisito é abordada neste artigo.

Pré-requisitos

Uma Pesquisa de IA do Azure na camada Básica ou superior. Se você estiver usando o enriquecimento de IA e conjuntos de habilidades, a camada deve ser Padrão 2 (S2) ou superior. Consulte Limites de serviço para obter detalhes.
Um recurso PaaS do Azure da seguinte lista de tipos de recursos suportados, configurado para ser executado em uma rede virtual.
Permissões na Pesquisa de IA do Azure e na fonte de dados:
- No recurso PaaS do Azure, você deve ter a permissão para aprovar conexões de ponto de extremidade privadas. Por exemplo, se você estiver usando uma conta de Armazenamento do Azure como sua fonte de dados (como contêiner de Blob, compartilhamento de Arquivos do Azure, tabela do Azure), precisará do Microsoft.Storage/storageAccounts/privateEndpointConnectionsApproval/action.
- No serviço de pesquisa, você deve ter permissões de leitura e gravação em recursos de link privado compartilhado e status de operação de leitura:
  - Microsoft.Search/searchServices/sharedPrivateLinkResources/write
  - Microsoft.Search/searchServices/sharedPrivateLinkResources/read
  - Microsoft.Search/searchServices/sharedPrivateLinkResources/operationStatuses/read

Tipos de recursos suportados

Você pode criar um link privado compartilhado para os seguintes recursos.

Tipo de recurso	Subrecurso (ou ID de Grupo)
Microsoft.Storage/storageContas ¹	`blob`, `table`, `dfs`, `file`
Microsoft.DocumentDB/databaseAccounts ²	`Sql`
Microsoft.Sql/servers	`sqlServer`
Microsoft.KeyVault/cofres	`vault`
Microsoft.DBforMySQL/servers (visualização)	`mysqlServer`
Microsoft.Web/sites (pré-visualização) ³	`sites`
Microsoft.Sql/managedInstances (visualização) ⁴	`managedInstance`
Microsoft.CognitiveServices/accounts (visualização) ⁵	`openai_account`

1 Se o Armazenamento do Azure e a Pesquisa de IA do Azure estiverem na mesma região, a conexão com o armazenamento será feita pela rede de backbone da Microsoft, o que significa que um link privado compartilhado será redundante para essa configuração. No entanto, se você já configurou um ponto de extremidade privado para o Armazenamento do Azure, também deve configurar um link privado compartilhado ou a conexão é recusada no lado do armazenamento. Além disso, se você estiver usando vários formatos de armazenamento para vários cenários na pesquisa, crie um link privado compartilhado separado para cada subrecurso.

2 O Microsoft.DocumentDB/databaseAccounts tipo de recurso é usado para conexões de indexador com o Azure Cosmos DB para NoSQL. O nome do provedor e a ID do grupo diferenciam maiúsculas de minúsculas.

3 O Microsoft.Web/sites tipo de recurso é usado para o Serviço de Aplicativo e as funções do Azure. No contexto do Azure AI Search, uma função do Azure é o cenário mais provável. Uma função do Azure é comumente usada para hospedar a lógica de uma habilidade personalizada. O Azure Function tem planos de hospedagem de Consumo, Premium e Serviço de Aplicativo Dedicado. O Ambiente do Serviço de Aplicativo (ASE) e o Serviço Kubernetes do Azure (AKS) não são suportados no momento.

4 Consulte Criar um link privado compartilhado para uma instância gerenciada do SQL para obter instruções.

5 O Microsoft.CognitiveServices/accounts tipo de recurso é usado para conexões de indexador com o Azure OpenAI ao implementar vetorização integrada.

1 - Crie um link privado compartilhado

Use o portal do Azure, a API REST de gerenciamento, a CLI do Azure ou o Azure PowerShell para criar um link privado compartilhado.

Aqui estão algumas dicas:

Dê ao link privado um nome significativo. No recurso PaaS do Azure, um 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.

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

Entre no portal do Azure e encontre seu serviço de pesquisa.
Em Configurações no painel de navegação esquerdo, selecione Rede.
Na página Acesso Privado Partilhado, selecione + Adicionar Acesso Privado Partilhado.
Selecione Conectar a um recurso do Azure em meu diretório ou Conectar a um recurso do Azure por ID de recurso.
Se você selecionar a primeira opção (recomendada), o portal ajudará você a escolher o recurso apropriado do Azure e preencherá outras propriedades, como a ID de grupo do recurso e o tipo de recurso.
Se você selecionar a segunda opção, insira a ID de recurso do Azure manualmente e escolha a ID de grupo apropriada na lista no início deste artigo.
Confirme se o status de provisionamento é "Atualização".
Quando o recurso é criado com êxito, o estado de provisionamento do recurso muda para "Êxito".

Nota

As versões de API de visualização, ou 2020-08-01-preview2021-04-01-preview, são necessárias para IDs de grupo que estão em visualização. Os seguintes tipos de recursos estão em visualização: managedInstance, mySqlServer, sites.

Embora ferramentas como o portal do Azure, o Azure PowerShell ou a CLI do Azure tenham mecanismos internos para entrada na conta, um cliente REST precisa fornecer um token de portador que permita que sua solicitação seja atendida.

Como é fácil e rápido, esta seção usa as etapas da CLI do Azure para obter um token de portador. Para abordagens mais duráveis, consulte Gerenciar com REST.

Abra uma linha de comando e execute az login para entrar no Azure.
Mostrar a conta ativa e a subscrição. Verifique se esta assinatura é a mesma que tem o recurso PaaS do Azure para o qual você está criando o link privado compartilhado.
```
az account show
```
Altere a subscrição se não for a correta:
```
az account set --subscription {{Azure PaaS subscription ID}}
```
Crie um token ao portador e, em seguida, copie o token inteiro (tudo entre aspas).
```
az account get-access-token
```

Mude para um cliente REST e configure um recurso de link privado compartilhado GET. Analise os links privados compartilhados existentes para garantir que você não está duplicando um link. Pode haver apenas um link privado compartilhado para cada combinação de recursos e subrecursos.

@subscriptionId = PASTE-HERE
@rg-name = PASTE-HERE
@service-name = PASTE-HERE
@token = PASTE-TOKEN-HERE

GET https://https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{rg-name}}/providers/Microsoft.Search/searchServices/{{service-name}}/sharedPrivateLinkResources?api-version=2023-11-01 HTTP/1.1
  Content-type: application/json
  Authorization: Bearer {{token}}

Envie o pedido. Você deve obter uma lista de todos os recursos de link privado compartilhado que existem para seu serviço de pesquisa. Verifique se não existe um link privado compartilhado para a combinação de recursos e subrecursos.

Formule uma solicitação PUT para Criar ou Atualizar Link Privado Compartilhado para o recurso PaaS do Azure.

PUT https://https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{rg-name}}/providers/Microsoft.Search/searchServices/{{service-name}}/sharedPrivateLinkResources/{{shared-private-link-name}}?api-version=2023-11-01 HTTP/1.1
  Content-type: application/json
  Authorization: Bearer {{token}}

{
    "properties":
     {
        "groupID": "blob",
        "privateLinkResourceId": "/subscriptions/{{subscriptionId}}/resourceGroups/{{rg-name}}/providers/Microsoft.Storage/storageAccounts/{{storage-account-name}}",
        "provisioningState": "",
        "requestMessage": "Please approve this request.",
        "resourceRegion": "",
        "status": ""
     }
}

Se o recurso PaaS do Azure estiver em uma assinatura diferente, use a CLI do Azure para alterar a assinatura e obtenha um token de portador válido para essa assinatura:

az account set --subscription {{Azure PaaS subscription ID}}

az account get-access-token

Envie o pedido. Para verificar o status, execute novamente a primeira solicitação de Link Privado Compartilhado GET para monitorar o estado de provisionamento à medida que ele transita da atualização para a bem-sucedida.

Consulte Gerenciar com o PowerShell para obter instruções sobre como começar.

Primeiro, use Get-AzSearchSharedPrivateLinkResource para revisar quaisquer links privados compartilhados existentes para garantir que você não esteja duplicando um link. Pode haver apenas um link privado compartilhado para cada combinação de recursos e subrecursos.

Get-AzSearchSharedPrivateLinkResource -ResourceGroupName <search-service-resource-group-name> -ServiceName <search-service-name>

Use New-AzSearchSharedPrivateLinkResource para criar um link privado compartilhado, substituindo valores válidos para os espaços reservados. Este exemplo é para armazenamento de blob.

New-AzSearchSharedPrivateLinkResource -ResourceGroupName <search-service-resource-group-name> -ServiceName <search-service-name> -Name <spl-name> -PrivateLinkResourceId /subscriptions/<alphanumeric-subscription-ID>/resourceGroups/<storage-resource-group-name>/providers/Microsoft.Storage/storageAccounts/myBlobStorage -GroupId blob -RequestMessage "Please approve"

Execute novamente a primeira solicitação para monitorar o estado de provisionamento à medida que ele transita da atualização para a bem-sucedida.

Consulte Gerenciar com a CLI do Azure para obter instruções sobre como começar.

Primeiro, use az-search-shared-private-link-resource list para revisar quaisquer links privados compartilhados existentes para garantir que você não esteja duplicando um link. Pode haver apenas um link privado compartilhado para cada combinação de recursos e subrecursos.

az search shared-private-link-resource list --service-name {{your-search-service-name}} --resource-group {{your-search-service-resource-group}}

Use az-search-shared-private-link-resource create para a próxima etapa. Este exemplo é para o Azure Cosmos DB para NoSQL.

A sintaxe diferencia maiúsculas de minúsculas, portanto, verifique se a ID do grupo é Sql e o nome do provedor é Microsoft.DocumentDB.

az search shared-private-link-resource create --name {{your-shared-private-link-name}} --service-name {{your-search-service-name}} --resource-group {{your-search-service-resource-group}} --group-id Sql --resource-id "/subscriptions/{{your-subscription-ID}}/{{your-cosmos-db-resource-group}}/providers/Microsoft.DocumentDB/databaseAccounts/{{your-cosmos-db-account-name}}"

Execute novamente a primeira solicitação para monitorar o estado de provisionamento à medida que ele transita da atualização para a bem-sucedida.

Fluxo de trabalho de criação de links privados compartilhados

Uma 202 Accepted resposta é devolvida em caso de sucesso. O processo de criação de um ponto de extremidade privado de saída é uma operação de longa execução (assíncrona). Envolve a implantação dos seguintes recursos:

Um ponto de extremidade privado, alocado com um endereço IP privado em um "Pending" estado. O endereço IP privado é obtido a partir do espaço de endereço alocado para a rede virtual do ambiente de execução para o indexador privado específico do serviço de pesquisa. Após a aprovação do ponto de extremidade privado, qualquer comunicação da Pesquisa de IA do Azure para o recurso do Azure é originada do endereço IP privado e de um canal de link privado seguro.
Uma zona DNS privada para o tipo de recurso, com base no ID do grupo. Ao implantar esse recurso, você garante que qualquer pesquisa de DNS para o recurso privado utilize o endereço IP associado ao ponto de extremidade privado.

2 - Aprovar a conexão de ponto final privado

A aprovação da conexão de ponto de extremidade privado é concedida no lado PaaS do Azure. É necessária a aprovação explícita do proprietário do recurso. As etapas a seguir abrangem a aprovação usando o portal do Azure, mas aqui estão alguns links para aprovar a conexão programaticamente do lado do Azure PaaS:

No Armazenamento do Azure, use Private Endpoint Connections - Put
No Azure Cosmos DB, use Conexões de Ponto Final Privado - Criar ou Atualizar

Usando o portal do Azure, execute as seguintes etapas:

Abra a página Rede do recurso PaaS do Azure.Texto
Encontre a seção que lista as conexões de ponto de extremidade privadas. O exemplo a seguir é para uma conta de armazenamento.
Selecione a conexão e, em seguida, selecione Aprovar. Pode levar alguns minutos para que o status seja atualizado no portal.

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.

Embora o link do ponto de extremidade privado na página Rede esteja ativo, ele não será resolvido.

Selecionar o link produz um erro. Uma mensagem de status de e must match the tenant associated with this subscription aparece porque o recurso de ponto de extremidade privado de back-end é provisionado "The access token is from the wrong issuer" pela Microsoft em um locatário gerenciado pela Microsoft, enquanto o recurso vinculado (Azure AI Search) está em seu locatário. É por design que você não pode acessar o recurso de ponto de extremidade privado selecionando o link de conexão de ponto de extremidade privado.

Siga as instruções na próxima seção para verificar o status do seu link privado compartilhado.

3 - 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 página Acesso Privado Compartilhado da página Rede do serviço de pesquisa. O estado da conexão deve ser aprovado.

Como alternativa, você também pode obter o estado da conexão usando a API GET Shared Private Link.

az rest --method get --uri https://management.azure.com/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/contoso/providers/Microsoft.Search/searchServices/contoso-search/sharedPrivateLinkResources/blob-pe?api-version=2023-11-01

Isso retornaria um JSON, onde o estado da conexão aparece como "status" na seção "propriedades". Segue-se um exemplo de uma conta de armazenamento.

{
      "name": "blob-pe",
      "properties": {
        "privateLinkResourceId": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/contoso/providers/Microsoft.Storage/storageAccounts/contoso-storage",
        "groupId": "blob",
        "requestMessage": "please approve",
        "status": "Approved",
        "resourceRegion": null,
        "provisioningState": "Succeeded"
      }
}

Se o estado de provisionamento (properties.provisioningState) do recurso for "Bem-sucedido" e o estado da conexão(properties.status) for "Aprovado", isso significa que o recurso de link privado compartilhado está funcional e o indexador pode ser configurado para se comunicar pelo ponto de extremidade privado.

4 - Configurar o indexador para ser executado no ambiente 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 dispendioso do conjunto de habilidades para vários clientes.

O ambiente de execução é transparente, mas depois de começar a criar regras de firewall ou estabelecer conexões privadas, você deve levar em conta a execução do indexador. Para uma conexão privada, configure a execução do indexador para sempre ser executada no ambiente privado.

Esta etapa mostra como configurar o indexador para ser executado no ambiente privado usando a API REST. Você também pode definir o ambiente de execução usando o editor JSON no portal.

Nota

Você pode executar esta etapa antes que a conexão de ponto de extremidade privado seja aprovada. No entanto, até que a conexão de ponto de extremidade privado apareça como aprovada, qualquer indexador existente que tente se comunicar com um recurso seguro (como a conta de armazenamento) acabará em um estado de falha transitória e novos indexadores não poderão ser criados.

Crie a definição, o índice e o conjunto de habilidades da fonte de dados (se estiver usando um) como faria normalmente. Não há propriedades em nenhuma dessas definições que variam ao usar um ponto de extremidade privado compartilhado.
Crie um indexador que aponte para a fonte de dados, o índice e o conjunto de habilidades que você criou na etapa anterior. Além disso, force o indexador a ser executado no ambiente de execução privada definindo a propriedade de configuração do indexador executionEnvironment como private.
```
{
    "name": "indexer",
    "dataSourceName": "blob-datasource",
    "targetIndexName": "index",
    "parameters": {
        "configuration": {
            "executionEnvironment": "private"
        }
    },
    "fieldMappings": []
}
```

Depois que o indexador for criado com êxito, ele deverá se conectar ao recurso do Azure por meio da conexão de ponto de extremidade privado. Você pode monitorar o status do indexador usando a API de Status do Indexador.

Nota

Se você já tiver indexadores existentes, poderá atualizá-los por meio da API PUT definindo o executionEnvironment para private ou usando o editor JSON no portal.

5 - Teste o link privado compartilhado

Se você ainda não tiver feito isso, verifique se seu recurso PaaS do Azure recusa conexões da Internet pública. Se as conexões forem aceitas, revise as configurações de DNS na página Rede do seu recurso PaaS do Azure.
Escolha uma ferramenta que possa invocar um cenário de solicitação de saída, como uma conexão de indexador com um ponto de extremidade privado. Uma opção fácil é usar o assistente Importar dados , 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 para pesquisar pode ser pela Internet pública.
Defina a cadeia de conexão para o recurso privado de PaaS do Azure. O formato da cadeia de conexão não muda para o link privado compartilhado. O serviço de pesquisa invoca o link privado compartilhado internamente.

Para cargas de trabalho de indexador, a cadeia de conexão está na definição da fonte de dados. Um exemplo de uma fonte de dados pode ter esta aparência:
```
 {
   "name": "my-blob-ds",
   "type": "azureblob",
   "subtype": null,
   "credentials": {
     "connectionString": "DefaultEndpointsProtocol=https;AccountName=<YOUR-STORAGE-ACCOUNT>;AccountKey=..."
   }
```

Para cargas de trabalho do indexador, lembre-se de definir o ambiente de execução na definição do indexador. Um exemplo de uma definição de indexador pode ter esta aparência:

"name": "indexer",
"dataSourceName": "my-blob-ds",
"targetIndexName": "my-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.

Resolução de Problemas

Se a criação do indexador falhar com "As credenciais da fonte de dados são inválidas", verifique o status de aprovação do link privado compartilhado antes de depurar a conexão. Se o status for Approved, verifique a properties.provisioningState propriedade. Se for , pode haver um problema com dependências Incompletesubjacentes. Nesse caso, reemita a PUT solicitação para recriar o link privado compartilhado. Também pode ser necessário repetir a etapa de aprovação.
Se os indexadores falharem de forma consistente ou intermitente, verifique a executionEnvironment propriedade no indexador. O valor deve ser definido como private. Se você não definiu essa propriedade e as execuções do indexador foram bem-sucedidas no passado, é porque o serviço de pesquisa usou um ambiente privado por conta própria. Um serviço de pesquisa move o processamento para fora do ambiente padrão se o sistema estiver sob carga.
Se você receber um erro ao criar um link privado compartilhado, verifique os limites de serviço para verificar se você está abaixo da cota para sua camada.

Próximos passos

Saiba mais sobre pontos de extremidade privados e outros métodos de conexão segura:

Faça conexões de saída por meio de um link privado compartilhado

Quando usar um link privado compartilhado

Limitações

Pré-requisitos

Tipos de recursos suportados

1 - Crie um link privado compartilhado

Fluxo de trabalho de criação de links privados compartilhados

2 - Aprovar a conexão de ponto final privado

3 - Verifique o status do link privado compartilhado

4 - Configurar o indexador para ser executado no ambiente privado

5 - Teste o link privado compartilhado

Resolução de Problemas

Próximos passos

Recursos adicionais