Faça conexões de saída por meio de um link privado compartilhado
Este artigo explica como configurar chamadas privadas de saída da Pesquisa de IA do Azure para um recurso do Azure executado em uma rede virtual do Azure.
Configurar 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 do Azure dentro do limite de rede.
O link privado compartilhado é um recurso premium cobrado por uso. Quando você configura um link privado compartilhado, os preços do ponto de extremidade privado são adicionados à 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, confira Preço do Link Privado do Azure.
Observação
Se você estiver configurando uma conexão de indexador privado com uma Instância Gerenciada de SQL, confira este artigo para obter etapas específicas para esse tipo de recurso.
Quando usar um link privado compartilhado
A Pesquisa de IA do Azure faz chamadas de saída para outros recursos do Azure nos seguintes cenários:
- Conexões de indexador ou consulta com o Azure OpenAI, o Azure AI Vision ou o catálogo de modelos do Azure AI Foundry para vetorização
- Conexões do indexador com fontes de dados com suporte
- Conexões do indexador (conjunto de habilidades) com o Armazenamento do Microsoft Azure para enriquecimentos em cache, estado de sessão de depuração ou gravação em um repositório de conhecimento
- Conexões do indexador (conjunto de habilidades) com os Serviços de IA do Azure para fins de cobrança
- Solicitações da chave de criptografia para o Azure Key Vault
- Solicitações de habilidade personalizadas para o Azure Functions ou recurso semelhante
Os links privados compartilhados funcionam apenas para conexões de Azure para Azure. Se você estiver se conectando ao OpenAI ou a outro modelo externo, a conexão deverá ser feita 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 do Azure ou clientes 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 do Azure
- Usado internamente pela Pesquisa de IA do Azure em uma conexão privada com um recurso específico do Azure
Somente o serviço de pesquisa pode usar os links privados que ele cria, e pode haver apenas um link privado compartilhado, o qual foi criado no serviço para cada combinação de recursos e sub-recursos.
Depois de configurar o link privado, ele será usado automaticamente sempre que o serviço de pesquisa se conectar a esse recurso. 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 precise se conectar usando um IP autorizado no firewall do recurso do Azure.
Há dois cenários para usar o Link Privado do Azure e o Azure AI Search em conjunto.
Cenário um: criar um link privado compartilhado quando uma conexão de saída (indexador) com o Azure requer uma conexão privada.
Cenário dois: configurar a pesquisa para uma conexão de entrada privada de clientes que são executados em uma rede virtual.
O primeiro cenário é abordado neste artigo.
Embora os dois cenários dependam do Link Privado do Azure, eles são independentes. Você pode criar um link privado compartilhado sem precisar configurar seu próprio serviço de pesquisa para um ponto de extremidade privado.
Limitações
Ao avaliar os 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 versão prévia. Se você estiver se conectando a um recurso de versão prévia (Banco de Dados do Azure para MySQL ou Instância Gerenciada de SQL do Azure), use uma versão prévia da API REST de Gerenciamento para criar o link privado compartilhado. Essas versões incluem
2020-08-01-preview,2021-04-01-preview,2024-03-01-preview, e2024-06-01-preview. Recomendamos a API de visualização mais recente.A execução do indexador deve usar o ambiente de execução privado específico do serviço de pesquisa. Não há suporte para conexões de ponto de extremidade privado no ambiente de processamento de conteúdo multilocatário. A configuração desse requisito é abordada neste artigo.
Examine os limites de recursos do link privado compartilhado para cada camada.
Pré-requisitos
Um recurso do Azure com suporte, configurado para ser executado em uma rede virtual.
Um serviço de Pesquisa de IA do Azure com requisitos de nível e região, por carga de trabalho:
Carga de trabalho Requisitos de nível Requisitos de região Requisitos de criação de serviço Indexadores sem conjuntos de habilidades Básico e superior Nenhum Nenhum Conjuntos de habilidades com habilidades inseridas (vetorização integrada) Básico e superior Regiões de alta capacidade Após 3 de abril de 2024 Conjuntos de habilidades usando outras habilidades internas ou personalizadas Standard 2 (S2) e superior Nenhum Após 3 de abril de 2024 Permissões na Pesquisa de IA do Azure e no recurso do Azure:
Recurso Permissões IA do Azure Search Microsoft.Search/searchServices/sharedPrivateLinkResources/write
Microsoft.Search/searchServices/sharedPrivateLinkResources/read
Microsoft.Search/searchServices/sharedPrivateLinkResources/operationStatuses/readOutros recursos do Azure Permissão para aprovar conexões de ponto de extremidade privado. Por exemplo, no Armazenamento do Microsoft Azure, você precisa de Microsoft.Storage/storageAccounts/privateEndpointConnectionsApproval/action.
Tipos de recurso compatíveis
Você pode criar um link privado compartilhado para os recursos a seguir.
| Tipo de recurso | Sub-recurso (ou ID do Grupo) |
|---|---|
| Microsoft.Storage/storageAccounts 1 |
blob, table, dfs, file |
| Microsoft.DocumentDB/databaseAccounts 2 | Sql |
| Microsoft.Sql/servers 3 | sqlServer |
| Microsoft.KeyVault/vaults | vault |
| Microsoft.DBforMySQL/servers (versão prévia) | mysqlServer |
| Microsoft.Web/sites 4 | sites |
| Microsoft.Sql/managedInstances (versão prévia) 5 | managedInstance |
| Microsoft.CognitiveServices/accounts 67 | openai_account |
| Microsoft.CognitiveServices/accounts 8 | cognitiveservices_account |
1 Se o Armazenamento do Azure e o Azure AI Search 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 deverá configurar um link privado compartilhado ou a conexão será 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 sub-recurso.
2 O tipo de recurso Microsoft.DocumentDB/databaseAccounts é usado para conexões de indexador com o Azure Cosmos DB for NoSQL. O nome do provedor e a ID do grupo diferenciam maiúsculas de minúsculas.
3 O tipo de recurso Microsoft.Sql/servers é usado para conexões com o Banco de Dados SQL do Azure. No momento, não há suporte para um link privado compartilhado para o SQL do Azure Synapse.
4 O tipo de recurso Microsoft.Web/sites é usado para o Serviço de Aplicativo e Azure Functions. 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. A função do Azure tem planos de hospedagem do Serviço de Aplicativo de Consumo, Premium e Dedicado. No momento, não há suporte para o ASE (Ambiente do Serviço de Aplicativo), o AKS (Serviço de Kubernetes do Azure) e o Gerenciamento de API do Azure.
5 Confira Criar um link privado compartilhado para uma Instância Gerenciada de SQL para obter instruções.
6 O tipo de recurso Microsoft.CognitiveServices/accounts é usado para conexões de vetorizador e indexador para modelos de inserção do OpenAI do Azure ao implementar vetorização integrada. A partir de 19 de novembro de 2024, começamos a oferecer suporte a links privados compartilhados para modelos de incorporação no catálogo de modelos do Azure AI Foundry ou à API da Visão de IA do Azure multimodal.
7 O link privado compartilhado para OpenAI do Azure tem suporte apenas na nuvem pública e no Microsoft Azure Government. Outras ofertas de nuvem não têm suporte para links privados compartilhados para openai_account ID do grupo.
8 Os links privados compartilhados agora contam com suporte (desde novembro de 2024) para conexões de vários serviços de IA do Azure. A Pesquisa de IA do Azure se conecta aos vários serviços de IA do Azure para fins de cobrança. Essas conexões agora podem ser privadas por meio de um link privado compartilhado. O link privado compartilhado só é suportado ao configurar uma identidade gerenciada (configuração sem chave) na definição do conjunto de habilidades.
1 - Criar 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.
Veja a seguir algumas dicas:
- Dê ao link privado um nome significativo. No recurso de PaaS do Azure, um link privado compartilhado aparece junto com outros pontos de extremidade privados. Um nome como "shared-private-link-for-search" pode lembrar você de como ele é usado.
Ao concluir as etapas nesta seção, você 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 deve aprovar a solicitação antes de entrar em operação.
Em Configurações no painel de navegação à esquerda, selecione Rede.
Na página Acesso Privado Compartilhado, selecione + Adicionar Acesso Privado Compartilhado.
Selecione Conectar-se a um recurso do Azure em meu diretório ou Conectar-se a um recurso do Azure por ID de recurso.
Se você selecionar a primeira opção (recomendada), o portal do Azure ajudará você a escolher o recurso apropriado do Azure e preencherá outras propriedades, como a ID do grupo do recurso e o tipo de recurso.
Se você selecionar a segunda opção, insira a ID do recurso do Azure manualmente e escolha a ID do grupo apropriada na lista no início deste artigo.
Confirme se o status de provisionamento é "Atualizando".
Depois que o recurso for criado, o estado de provisionamento do recurso será alterado para "Bem-sucedido".
Fluxo de trabalho de criação do link privado compartilhado
Uma resposta 202 Accepted é retornada em caso de êxito. O processo de criação de um ponto de extremidade privado de saída é uma operação de execução longa (assíncrona). Ele envolve a implantação dos seguintes recursos:
Um ponto de extremidade privado, alocado com um endereço IP privado em um estado
"Pending". O endereço IP privado é obtido do espaço de endereço alocado na rede virtual do ambiente de execução para o indexador particular específico do serviço de pesquisa. Após a aprovação do ponto de extremidade privado, qualquer comunicação do Azure AI Search com o recurso do Azure é originada no endereço IP privado e em um canal de link privado seguro.Uma zona DNS privada para o tipo de recurso, com base na ID do grupo. Ao implantar esse recurso, você garante que qualquer pesquisa de DNS para o recurso particular utiliza o endereço IP associado ao ponto de extremidade privado.
2 - Aprovar a conexão de ponto de extremidade privado
A aprovação da conexão de ponto de extremidade privado é concedida no PaaS do Azure. A aprovação explícita pelo proprietário do recurso é obrigatória. As etapas a seguir abrangem a aprovação usando o portal do Azure, mas aqui estão alguns links para aprovar a conexão de forma programática do lado do PaaS do Azure:
- No Armazenamento do Microsoft Azure, use Conexões de Ponto de Extremidade Privado – PUT
- No Azure Cosmos DB, use Conexões de Ponto de Extremidade Privado – Criar ou atualizar
- No OpenAI do Azure, use Conexões de Ponto de Extremidade Privado – Criar ou atualizar
Usando o portal do Azure, execute as etapas a seguir:
Abra a página Rede do recurso PaaS do Azure. Texto
Localize a seção que lista as conexões de ponto de extremidade privados. O exemplo a seguir cria 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 do Azure.
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.
Embora o link do ponto de extremidade privado na página de Rede esteja ativo, ele não será resolvido.
Selecionar o link produz um erro. Uma mensagem de status de "The access token is from the wrong issuer" e must match the tenant associated with this subscription aparece porque o recurso de ponto de extremidade privado do back-end é provisionado pela Microsoft em um locatário gerenciado pela Microsoft, enquanto o recurso vinculado (Pesquisa de IA do Azure) está em seu locatário. Por design, não é possível acessar o recurso do ponto de extremidade privado ao selecionar o link de conexão do ponto de extremidade privado.
Siga as instruções na próxima seção para verificar o status do seu link privado compartilhado.
3 - Verificar status de link privado compartilhado
Na Pesquisa de IA do Azure, você pode confirmar a aprovação da solicitação ao rever a página Acesso Privado Compartilhado da página Rede do serviço de pesquisa. O estado da conexão deve ser aprovado.
Alternativamente, você também pode obter o estado da conexão usando Recurso do Link Privado Compartilhado - Obter.
az rest --method get --uri https://management.azure.com/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/contoso/providers/Microsoft.Search/searchServices/contoso-search/sharedPrivateLinkResources/blob-pe?api-version=2024-07-01
Isso retornará um JSON, em que o estado da conexão aparece como "status" na seção "propriedades". Veja a seguir um exemplo de uma conta de armazenamento.
{
"name": "blob-pe",
"properties": {
"privateLinkResourceId": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/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 de conexão (properties.status) for "Aprovado", isso significa que o recurso de link privado compartilhado é 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, que é 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.
O ambiente de execução é transparente, mas depois que você começar a criar regras de firewall ou estabelecer conexões privadas, deverá levar em conta a execução do indexador. Para uma conexão privada, configure a execução do indexador para ser sempre executada no ambiente privado.
Essa 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 do Azure.
Observação
Você pode executar essa 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, todo indexador existente que tentar se comunicar com um recurso seguro (como a conta de armazenamento) terminará em um estado de falha transitória e a criação de indexadores falhará.
Crie a definição, o índice e o conjunto de habilidades (se estiver usando um) da fonte de dados, como feito 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 você criou na etapa anterior. Além disso, force a execução do indexador no ambiente de execução particular definindo a propriedade de configuração do indexador
executionEnvironmentcomoprivate.{ "name": "indexer", "dataSourceName": "blob-datasource", "targetIndexName": "index", "parameters": { "configuration": { "executionEnvironment": "private" } }, "fieldMappings": [] }
Depois que o indexador for criado com sucesso, ele deve se conectar ao recurso do Azure pela conexão do ponto de extremidade privado. Você pode monitorar o status do indexador usando a API de status do indexador.
Observação
Se você já tiver indexadores existentes, poderá atualizá-los por meio da API PUT definindo executionEnvironment como private ou usando o editor JSON no portal do Azure.
5 - Testar o link privado compartilhado
Se você ainda não fez isso, verifique se o recurso de PaaS do Azure recusa as conexões da Internet pública. Se as conexões forem aceitas, examine as configurações de DNS na página Rede do recurso de 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 escolha 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 o seu serviço de pesquisa também não esteja configurado para uma conexão privada, a conexão do cliente REST para pesquisa pode ser feita pela Internet pública.
Defina a cadeia de conexão como o recurso privado de PaaS do Azure. O formato da cadeia de conexão não é alterado para o link privado compartilhado. O serviço de pesquisa invoca internamente o link privado compartilhado.
Para cargas de trabalho do indexador, a cadeia de conexão está na definição da fonte de dados. Um exemplo de uma fonte de dados pode ser assim:
{ "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 determinar o ambiente de execução na definição do indexador. Um exemplo de uma definição de indexador pode ser assim:
"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.
Solução de problemas
Se a criação do indexador falhar indicando "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 propriedadeproperties.provisioningState. Se forIncomplete, pode haver um problema com as dependências subjacentes. Nesse caso, emita novamente a solicitaçãoPUTpara recriar o link privado compartilhado. Talvez seja necessário repetir a etapa de aprovação também.Se os indexadores falharem consistente ou intermitentemente, verifique a propriedade
executionEnvironmentno indexador. O valor deve ser definido comoprivate. Se você não definiu essa propriedade e o indexador foi executado com êxito no passado, é porque o serviço de pesquisa usava um ambiente privado por conta própria. Um serviço de pesquisa moverá o processamento para fora do ambiente multilocatário se o sistema estiver sob carga.Se você receber um erro ao criar um link privado compartilhado, verifique os limites de serviço para ver se você está abaixo da cota da camada.
Próximas etapas
Saiba mais sobre pontos de extremidade privados e outros métodos de conexão segura: