Solucionar problemas com links privados compartilhados no Pesquisa de IA do Azure

Note

O Pesquisa de IA do Azure está disponível através do portal Azure, APIs REST e SDKs do Azure. Também sustenta o Foundry IQ, a camada de conhecimento gerida que transforma conteúdos empresariais em bases de conhecimento reutilizáveis e conscientes de permissões para agentes no portal Microsoft Foundry.

Um link privado compartilhado permite que o Pesquisa de IA do Azure faça conexões de saída seguras em um ponto de extremidade privado ao acessar recursos do cliente em uma rede virtual. Este artigo pode ajudá-lo a resolver erros que possam ocorrer.

A criação de um link privado partilhado é uma operação no plano de controlo do serviço de pesquisa. Você pode criar um link privado compartilhado usando o portal do Azure ou uma API REST de gerenciamento. Durante o provisionamento, o estado da solicitação é Updating. Depois que a operação for concluída com êxito, o status é Succeeded. Um ponto final privado para o recurso, juntamente com quaisquer zonas DNS e mapeamentos, é criado. Este ponto de extremidade é usado exclusivamente pela sua instância de serviço de pesquisa e é gerenciado por meio do Pesquisa de IA do Azure.

Etapas envolvidas na criação de recursos de link privado compartilhado

A seguir estão erros comuns que ocorrem durante a fase de criação.

Falhas de validação de solicitação

  • SKU sem suporte: links privados compartilhados são suportados na camada Básica e superior. Para indexadores com conjuntos de habilidades, a camada mínima é Padrão 1 (S1). Para obter mais informações, consulte Limites de recursos de link privado compartilhado.

  • Nome inválido: as regras de nomenclatura para um link privado compartilhado são:

    • O comprimento deve estar entre 1 e 60 caracteres
    • Caracteres alfanuméricos
    • Os nomes podem incluir sublinhado _, ponto . e hífen -, desde que não seja o primeiro caractere no nome

  • ID de grupo inválido: os IDs de grupo são sensíveis a maiúsculas e minúsculas e devem ser um dos seguintes valores.

    Recurso do Azure ID do Grupo Primeira versão da API disponível
    Armazenamento Azure - Blob (ou) ADLS Gen 2 blob 2020-08-01
    Armazenamento do Azure - Tabelas table 2020-08-01
    Azure Cosmos DB for NoSQL Sql 2020-08-01
    Base de Dados SQL do Azure sqlServer 2020-08-01
    Base de Dados do Azure para MySQL(pré-visualização) mysqlServer 2020-08-01-Preview
    Azure Key Vault vault 2020-08-01
    Funções do Azure (visualização) sites 2020-08-01-Preview

    Os recursos marcados com "(visualização)" devem ser criados usando uma versão de visualização das versões da API REST de gerenciamento.

  • privateLinkResourceId validação de tipo: semelhante ao groupId, o Pesquisa de IA do Azure valida que o tipo de recurso "correto" está especificado no privateLinkResourceId. A seguir estão os tipos de recursos válidos:

    Recurso do Azure Tipo de recurso Primeira versão da API disponível
    Armazenamento do Azure Microsoft.Storage/storageAccounts 2020-08-01
    Azure Cosmos DB Microsoft.DocumentDb/databaseAccounts 2020-08-01
    Base de Dados SQL do Azure Microsoft.Sql/servers 2020-08-01
    Azure Key Vault Microsoft.KeyVault/vaults 2020-08-01
    Base de Dados do Azure para MySQL(pré-visualização) Microsoft.DBforMySQL/servers 2020-08-01-Preview
    Funções do Azure (visualização) Microsoft.Web/sites 2020-08-01-Preview
    Instância Gerida do Azure SQL (pré-visualização) Microsoft.Sql/managedInstance 2020-08-01-Preview

    Além disso, o especificado groupId precisa ser válido para o tipo de recurso especificado. Por exemplo, groupId "blob" é válido para o tipo Microsoft.Storage/storageAccounts, ele não pode ser usado com nenhum outro tipo de recurso. Para uma determinada versão da API de gestão de pesquisa, os clientes podem descobrir os detalhes suportados de groupId e do tipo de recurso utilizando a List API suportada.

  • Aplicação de limite de cota: os serviços de pesquisa têm cotas impostas ao número distinto de recursos de link privado compartilhado que podem ser criados e ao número de vários tipos de recursos de destino que estão sendo usados (com base em groupId). Para obter mais informações, consulte Limites de recursos de link privado compartilhado.

Falhas da implementação

Um serviço de pesquisa inicia a solicitação para criar um link privado compartilhado, mas o Azure Resource Manager executa o trabalho real. Você pode verificar o status da implantação no portal do Azure ou por consulta e corrigir quaisquer erros que possam ocorrer.

Recursos de ligações privadas partilhadas que falham durante a implementação pelo Azure Resource Manager aparecem nas chamadas de API List e Get, mas apresentam um "Estado de Provisionamento" de Failed. Depois que o motivo da falha de implantação do Azure Resource Manager for determinado, exclua o Failed recurso e recrie-o depois de aplicar a resolução apropriada da tabela a seguir.

Motivo da falha de implantação Descrição Resolução
"Falha na Autorização Vinculada" A mensagem de erro indica que o cliente tem permissão para criar o link privado compartilhado no serviço de pesquisa, mas não tem permissão para executar a ação 'privateEndpointConnectionApproval/action' no escopo vinculado. Verifique novamente o ID do link privado na solicitação para garantir que não haja erros ou omissões no URI. Se o Pesquisa de IA do Azure e o recurso PaaS do Azure estiverem em assinaturas diferentes, e se você estiver usando REST ou uma interface de linha de comando, verifique se a conta ativa do Azure é o recurso PaaS do Azure. Para clientes REST, verifique se você não está usando um token de portador expirado e se o token é válido para a assinatura ativa.
Provedor de recursos de rede não registrado na assinatura do recurso de destino Um ponto de extremidade privado (e mapeamentos DNS associados) é criado para o recurso de destino (Conta de Armazenamento, Azure Cosmos DB, SQL do Azure) por meio do Microsoft.Network provedor de recursos (RP). Se a assinatura que hospeda o recurso de destino ("assinatura de destino") não estiver registrada no Microsoft.Network RP, a implantação do Azure Resource Manager poderá falhar. Você precisa registrar este RP em sua assinatura de destino. Você pode registrar o provedor de recursos usando o portal do Azure, o PowerShell ou a CLI.
Inválido groupId para o recurso de destino Quando as contas do Azure Cosmos DB são criadas, você pode especificar o tipo de API para a conta de banco de dados. Enquanto o Azure Cosmos DB oferece vários tipos de API diferentes, o Pesquisa de IA do Azure suporta apenas "Sql" como o protocolo para recursos de groupId link privado partilhado. Quando um link privado partilhado do tipo "Sql" é criado para um privateLinkResourceId que aponta para uma conta de banco de dados não-Sql, a implantação do Azure Resource Manager falha em virtude da groupId incompatibilidade. A ID de recurso do Azure de uma conta do Azure Cosmos DB não é suficiente para determinar o tipo de API que está sendo usado. O Pesquisa de IA do Azure tenta criar um ponto de extremidade privado, mas este é negado pelo Azure Cosmos DB. Você deve garantir que o privateLinkResourceId recurso especificado do Azure Cosmos DB seja para uma conta de banco de dados do tipo API "Sql"
Recurso de destino não encontrado A existência do recurso de destino especificado em privateLinkResourceId é verificada somente durante o início da implantação do Azure Resource Manager. Se o recurso de destino não estiver mais disponível, a implantação falhará. Você deve garantir que o recurso de destino esteja presente na assinatura e no grupo de recursos especificados e não seja movido ou excluído.
Erros transitórios/outros erros A implantação do Azure Resource Manager pode falhar se houver uma interrupção de infraestrutura ou devido a outros motivos inesperados. Isto deve ser raro e geralmente indica um estado transitório. Tente criar novamente este recurso mais tarde. Se o problema persistir, entre em contato com o Suporte do Azure.

Problemas ao aprovar o endpoint privado de back-end

Um ponto de extremidade privado é criado para o recurso de destino do Azure, conforme especificado no pedido de criação de ligação privada partilhada. Esta é uma das etapas finais na operação de implantação assíncrona do Azure Resource Manager, mas o Pesquisa de IA do Azure precisa vincular o endereço IP privado do ponto de extremidade privado como parte de sua configuração de rede. Uma vez que esse link é feito, o provisioningState recurso de link privado compartilhado vai para um estado Succeededde sucesso do terminal. Os clientes só devem aprovar ou negar (ou, em geral, modificar a configuração do ponto de extremidade privado de apoio) após a transição do estado para Succeeded. Modificar o ponto de extremidade privado de qualquer forma antes disso pode resultar numa operação de implementação incompleta e pode fazer com que o recurso de ligação privada partilhada acabe, quer imediatamente, quer geralmente dentro de algumas horas, num Failed estado.

Alteração de conectividade de rede do serviço de pesquisa paralisada em um estado de "Atualização"

Links privados partilhados e pontos de extremidade privados são usados quando o acesso à rede pública do serviço de pesquisa está desativado. Normalmente, a alteração da conectividade de rede deve ser bem-sucedida em alguns minutos após a solicitação ser aceita. Em algumas circunstâncias, o Pesquisa de IA do Azure pode levar várias horas para concluir a operação de alteração de conectividade.

Captura de ecrã a mostrar a alteração do acesso à rede pública para desativado.

Se você observar que a operação de alteração de conectividade está levando uma quantidade significativa de tempo, aguarde algumas horas. As operações de alteração de conectividade envolvem operações como a atualização de registros DNS, que podem levar mais tempo do que o esperado.

Se o Acesso à Rede Pública for alterado, os links privados compartilhados existentes e os pontos de extremidade privados podem não funcionar corretamente. Se os links privados compartilhados e os pontos de extremidade privados existentes pararem de funcionar durante uma operação de alteração de conectividade, aguarde algumas horas até que a operação seja concluída. Se ainda não estiverem funcionando, tente excluí-los e recriá-los.

Normalmente, um recurso de link privado compartilhado deve entrar em um estado terminal (Succeeded ou Failed) em alguns minutos após a solicitação ser aceita.

Em circunstâncias raras, a Pesquisa de IA do Azure pode falhar ao marcar corretamente o estado do recurso de link privado compartilhado para um estado de terminal (Succeeded ou Failed). Isso geralmente ocorre devido a uma falha inesperada. Os recursos de link privado partilhado são automaticamente transferidos para um Failed estado se estiverem "presos" num estado não terminal durante mais do que algumas horas.

Se o recurso de link privado compartilhado não fizer a transição para um estado terminal, aguarde algumas horas para garantir que ele se torne Failed antes de poder excluí-lo e recriá-lo. Como alternativa, em vez de esperar, você pode tentar criar outro recurso de link privado compartilhado com um nome diferente (mantendo todos os outros parâmetros iguais).

Um recurso de link privado compartilhado existente pode ser atualizado usando a API Criar ou Atualizar. A pesquisa só permite atualizações restritas para o recurso de link privado compartilhado - somente a mensagem de solicitação pode ser modificada por meio dessa API.

  • Não é possível atualizar nenhuma das propriedades "principais" de um recurso de link privado compartilhado existente (como privateLinkResourceId ou groupId) e isso sempre não será suportado. Se qualquer outra propriedade além da mensagem de solicitação precisar ser alterada, aconselhamos os clientes a excluir e recriar o recurso de link privado compartilhado.

  • A atualização da mensagem de solicitação de um recurso de link privado compartilhado só é possível se ela atingir o estado de provisionamento do Succeeded.

Os clientes podem excluir um recurso de link privado compartilhado existente por meio da API de exclusão. Semelhante ao processo de criação (ou atualização), esta também é uma operação assíncrona com quatro etapas:

  1. Você solicita um serviço de pesquisa para excluir o recurso de link privado compartilhado.

  2. O serviço de pesquisa valida se o recurso existe e está em um estado válido para exclusão. Em caso afirmativo, ele inicia uma operação de exclusão do Azure Resource Manager para remover o recurso.

  3. Consultas de pesquisa relacionadas com a conclusão da operação (que geralmente leva alguns minutos). Neste ponto, o recurso de link privado compartilhado teria um estado de provisionamento de Deleting.

  4. Quando a operação for concluída com êxito, o ponto de extremidade privado de backup e todos os mapeamentos DNS associados serão removidos. O recurso não aparece como parte da operação List e tentar uma operação Get neste recurso resulta em um 404 Not Found.

Etapas envolvidas na exclusão de recursos de link privado compartilhado

A seguir estão erros comuns que ocorrem durante a fase de exclusão.

Tipo de falha Descrição Resolução
O recurso está em estado não terminal Um recurso de link privado compartilhado que não esteja em um estado terminal (Succeeded ou Failed) não pode ser excluído. É possível (raro) que um recurso de link privado compartilhado fique preso em um estado não terminal por até 8 horas. Aguarde até que o recurso atinja um estado terminal e tente novamente a solicitação de exclusão.
Operação de exclusão falhou com erro "Conflito" A operação do Azure Resource Manager para eliminar um recurso de link privado compartilhado comunica-se com o provedor do recurso de destino especificado em privateLinkResourceId ("RP de destino") antes de poder remover o endpoint privado e os mapeamentos DNS. Os clientes podem utilizar bloqueios de recursos do Azure para impedir quaisquer alterações em seus recursos. Quando o Azure Resource Manager alcança o RP de destino, ele exige que o RP de destino modifique o estado do recurso de destino (para remover detalhes sobre o ponto de extremidade privado de seus metadados). Quando o recurso de destino tem um bloqueio configurado nele (ou seu grupo de recursos/assinatura), a operação do Azure Resource Manager falha com um "Conflito" (e detalhes apropriados). O recurso de link privado compartilhado não será excluído. Os clientes devem remover o bloqueio no recurso de destino antes de tentar novamente a operação de exclusão. Nota: Esse problema também pode ocorrer quando os clientes tentam excluir um serviço de pesquisa com recursos de link privado compartilhado que apontam para recursos de destino "bloqueados"
Falha na operação de exclusão A operação de exclusão assíncrona do Azure Resource Manager pode falhar em casos raros. Quando esta operação falha, consultar o estado da operação assíncrona apresenta uma mensagem de erro e detalhes apropriados. Tente novamente a operação mais tarde ou entre em contato com o Suporte do Azure se o problema persistir.
Recurso preso no estado de "Eliminar" Em casos raros, um recurso de link privado partilhado pode ficar preso no estado "A eliminar" por até 8 horas, provavelmente devido a alguma falha grave no RP de Pesquisa. Aguarde 8 horas, após as quais o recurso mudará para o estado Failed e, em seguida, voltará a emitir a solicitação.

Próximos passos

Saiba mais sobre os recursos de links privados compartilhados e como usá-los para acesso seguro a conteúdo protegido.

  • Última atualização a