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

  • Artigo

Um link privado compartilhado permite que o Azure AI Search 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 compartilhado é uma operação do plano de controle do serviço de pesquisa. Você pode criar um link privado compartilhado usando o portal ou uma API REST de gerenciamento. Durante o provisionamento, o estado da solicitação é "Atualização". Depois que a operação for concluída com êxito, o status será "Bem-sucedido". Um ponto de extremidade 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 Azure AI Search.

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

Alguns erros comuns que ocorrem durante a fase de criação estão listados abaixo.

Falhas de validação de solicitação

  • SKU sem suporte: links privados compartilhados são suportados na camada Básica e acima. Para indexadores com conjuntos de habilidades, a camada mínima é Padrão 2 (S2).

  • 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 .final e hífen - , desde que não seja o primeiro caractere no nome

  • ID de grupo inválido: os IDs de grupo diferenciam maiúsculas de minúsculas e devem ser um dos valores da tabela abaixo:

    Recurso do Azure ID do Grupo Primeira versão da API disponível
    Armazenamento do Azure - Blob (ou) ADLS Gen 2 blob 2020-08-01
    Armazenamento do Azure - Tabelas table 2020-08-01
    Azure Cosmos DB para 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
    Azure Functions (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 Azure AI Search 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
    Azure Functions (visualização) Microsoft.Web/sites 2020-08-01-Preview
    Instância Gerenciada SQL do Azure (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", não pode ser usado com nenhum outro tipo de recurso. Para uma determinada versão da API de gerenciamento de pesquisa, os clientes podem descobrir os detalhes suportados groupId e do tipo de recurso utilizando a API suportada pela List.

  • 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). Eles estão documentados na seção Limites de recursos de link privado compartilhado da página Limites do serviço Azure AI Search.

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 ou por consulta e corrigir quaisquer erros que possam ocorrer.

Os recursos de link privado compartilhado que falharam na implantação do Azure Resource Manager aparecerão em chamadas de API List e Get , mas terão um "Estado de provisionamento" de Failed. Depois que o motivo da falha de implantação do Azure Resource Manager tiver sido 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 Description Resolução
"LinkedAuthorizationFailed" 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 Azure AI Search 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 é para 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, Azure SQL) 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 Azure AI Search suporta apenas "Sql" como o para recursos de groupId link privado compartilhado. Quando um link privado compartilhado do tipo "Sql" é criado para apontar privateLinkResourceId para uma conta de banco de dados não-SQL, a implantação do Azure Resource Manager falhará devido à 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. A Pesquisa de IA do Azure tenta criar o ponto de extremidade privado, que é 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 ponto de extremidade privado de suporte

Um ponto de extremidade privado é criado para o recurso do Azure de destino, conforme especificado na solicitação de criação de link privado compartilhado. Esta é uma das etapas finais na operação de implantação assíncrona do Azure Resource Manager, mas o Azure AI Search precisa vincular o endereço IP privado do ponto de extremidade privado como parte de sua configuração de rede. Uma vez feito esse link, o provisioningState recurso de link privado compartilhado irá 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 suporte) depois que o estado tiver feito a transição para Succeeded. Modificar o ponto de extremidade privado de qualquer forma antes disso pode resultar em uma operação de implantação incompleta e pode fazer com que o recurso de link privado compartilhado acabe (imediatamente ou geralmente dentro de algumas horas) em um Failed estado.

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

Links privados compartilhados 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 ter sido aceita. Em algumas circunstâncias, o Azure AI Search 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 ir para um estado terminal (Succeeded ou Failed) em alguns minutos após a solicitação ter sido 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 compartilhado são automaticamente transferidos para um Failed estado se ele estiver "preso" em um estado não terminal por mais de algumas horas.

Se você observar que o recurso de link privado compartilhado não transitou 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 tentativa de atualizar a mensagem de solicitação de um recurso de link privado compartilhado só é possível se ele tiver atingido o estado de provisionamento de 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 para 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 "Excluindo".

  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 aparecerá como parte da operação List e tentar uma operação Get neste recurso resultará em um 404 Not Found.

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

Alguns erros comuns que ocorrem durante a fase de exclusão estão listados abaixo.

Tipo de falha Description 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 tenha atingido 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 excluir um recurso de link privado compartilhado alcança o provedor de recursos do recurso de destino especificado em privateLinkResourceId ("RP de destino") antes que ele possa remover o ponto de extremidade 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 essa operação falhar, consultar o estado da operação assíncrona apresentará aos clientes 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 "Excluindo" Em casos raros, um recurso de link privado compartilhado pode ficar preso no estado "Excluindo" por até 8 horas, provavelmente devido a alguma falha catastrófica no RP de pesquisa. Aguarde 8 horas, após as quais o recurso transitará para Failed o estado e, em seguida, reemitirá 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.