Solução de problemas com os Links Privados Compartilhados no Azure AI Search

  • 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 podem ocorrer.

A criação de um link privado compartilhado é uma operação do painel 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 é "Atualizando". Depois que a operação for concluída com êxito, o status será "Êxito". Um ponto de extremidade privado para o recurso, juntamente com qualquer zona DNS e mapeamentos, é criado. Esse ponto de extremidade é usado exclusivamente pela instância do serviço de pesquisa e é gerenciado pelo Azure AI Search.

Steps involved in creating shared private link resources

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

Falhas na validação da solicitação

  • SKU sem suporte: há suporte para links privados compartilhados na camada Básica e superior. Para indexadores com conjuntos de habilidades, a camada mínima é Standard 2 (S2).

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

    • O comprimento deve ter 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 do grupo inválida: as IDs do grupo diferenciam maiúsculas de minúsculas e devem ter um dos valores da tabela abaixo:

    Recursos do Azure ID do Grupo Última versão de 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
    Banco de Dados SQL do Azure sqlServer 2020-08-01
    Banco de Dados do Azure para MySQL (pré-visualização) mysqlServer 2020-08-01-Preview
    Cofre de Chave do Azure vault 2020-08-01
    Azure Functions (pré-visualização) sites 2020-08-01-Preview

    Os recursos marcados com "(versão prévia)" devem ser criados usando uma versão prévia das versões da API REST de Gerenciamento.

  • Validação de tipo privateLinkResourceId: de maneira semelhante a groupId, o Azure AI Search valida que o tipo de recurso "correto" está especificado no privateLinkResourceId. Os tipos de recurso a seguir são válidos:

    Recursos do Azure Tipo de recurso Última versão de API disponível
    Armazenamento do Azure Microsoft.Storage/storageAccounts 2020-08-01
    Azure Cosmos DB Microsoft.DocumentDb/databaseAccounts 2020-08-01
    Banco de Dados SQL do Azure Microsoft.Sql/servers 2020-08-01
    Cofre de Chave do Azure Microsoft.KeyVault/vaults 2020-08-01
    Banco de Dados do Azure para MySQL (pré-visualização) Microsoft.DBforMySQL/servers 2020-08-01-Preview
    Azure Functions (pré-visualização) Microsoft.Web/sites 2020-08-01-Preview
    Instância Gerenciada de SQL do Azure (versão prévia) Microsoft.Sql/managedInstance 2020-08-01-Preview

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

  • Imposição de limite de cota: os serviços de pesquisa têm cotas impostas com base no número distinto de recursos de link privado compartilhado que podem ser criados e no número de vários tipos de recursos de destino em uso (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 do Azure AI Search.

Falhas de implantaçã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 qualquer erro que possa ocorrer.

Os recursos de link privado compartilhado que falharam a implantação do Azure Resource Manager aparecerão em Listar e Obter chamadas à API, mas terão um "Estado de Provisionamento" de Failed. Após determinar o motivo da falha na implantação do Azure Resource Manager, exclua o recurso Failed e recrie-o depois de aplicar a resolução apropriada com base na tabela abaixo.

Motivo da falha na implantação Descrição Resolução
"LinkedAuthorizationFailed" A mensagem de erro afirma 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 a ID do link privado na solicitação para verificar se não há erros ou omissões no URI. Se o Azure AI Search e o recurso de PaaS do Azure estiverem em assinaturas diferentes e se você estiver usando REST ou uma interface de linha de comando, verifique se a conta do Azure ativa é para o recurso de 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 de DNS associados) é criado para o recurso de destino (conta de armazenamento, Azure Cosmos DB, SQL do Azure) por meio do provedor de recursos (RP) Microsoft.Network. Se a assinatura que hospeda o recurso de destino ("assinatura de destino") não estiver registrada com RP Microsoft.Network, a implantação do Azure Resource Manager poderá falhar. Você precisa registrar esse RP em sua assinatura de destino. Você pode registrar o provedor de recursos usando o portal do Azure, o PowerShell ou a CLI.
groupId inválido 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 do banco de dados. Embora o Azure Cosmos DB ofereça vários tipos de API diferentes, o Azure AI Search dá suporte apenas a "Sql" como groupId para recursos de link privado compartilhados. Quando um link privado compartilhado do tipo "Sql" é criado em um privateLinkResourceId apontando para uma conta de banco de dados não Sql, a implantação do Azure Resource Manager falhará devido à incompatibilidade groupId. 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 Azure AI Search tenta criar o ponto de extremidade privado, o que é negado pelo Azure Cosmos DB. Você deve garantir que o privateLinkResourceId do recurso do Azure Cosmos DB especificado seja para uma conta de banco de dados do tipo de 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 tenha sido movido ou excluído.
Erros transitórios/outros A implantação do Azure Resource Manager poderá falhar se houver uma interrupção na infraestrutura ou por outros motivos inesperados. Isso deve ser raro e geralmente indica um estado transitório. Tente criar esse recurso novamente 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. Essa é 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. Depois que esse link for concluído, o provisioningState do recurso de link privado compartilhado vai para um estado de êxito do terminal Succeeded. 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 estado Failed.

Alteração de conectividade de rede do serviço Pesquisa paralisada em um estado "Atualizando"

Links privados compartilhados e pontos de extremidade privados são usados quando o serviço de pesquisa Acesso à Rede Pública está Desabilitado. Normalmente, a alteração da conectividade de rede deverá ter êxito em alguns minutos após a solicitação ser aceita. Em algumas circunstâncias, o Azure AI Search pode levar várias horas para concluir a operação de alteração da conectividade.

Screenshot of changing public network access to disabled.

Se você observar que a operação de alteração de conectividade está levando um tempo significativo, espere 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 Acesso à Rede Pública for alterado, os links privados compartilhados existentes e os pontos de extremidade privados poderão não funcionar corretamente. Se os links privados compartilhados existentes e os pontos de extremidade privados pararem de funcionar durante uma operação de alteração de conectividade, espere 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 deverá atingir um estado terminal (Succeeded ou Failed) alguns minutos após a solicitação ter sido aceita.

Em circunstâncias raras, o Azure AI Search pode falhar em marcar corretamente o estado do recurso de link privado compartilhado para um estado terminal (Succeeded ou Failed). Isso geralmente ocorre devido a uma falha inesperada. Os recursos de link privado compartilhado serão automaticamente transicionados para um estado Failed se estiverem "presos" em um estado não terminal por algumas horas.

Se você observar que o recurso de link privado compartilhado não fez a transição para um estado terminal, aguarde algumas horas para garantir que ele se torne Failed antes de 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 permite apenas atualizações limitadas 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 "básicas" de um recurso de link privado compartilhado existente (tais como privateLinkResourceId ou groupId) e essa função continuará sem suporte. Se qualquer outra propriedade além da mensagem de solicitação precisar ser alterada, recomendamos que os clientes excluam e recriem o recurso de link privado compartilhado.

  • A tentativa de atualizar a mensagem de solicitação de um recurso de link privado compartilhado só será 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 Excluir. Semelhante ao processo de criação (ou atualização), essa 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 que o recurso existe e está em um estado válido para exclusão. Em caso afirmativo, ele inicia uma operação de exclusão no Azure Resource Manager para remover o recurso.

  3. Pesquise consultas de conclusão da operação (geralmente leva alguns minutos). Neste ponto, o recurso de link privado compartilhado teria um estado de provisionamento de "Excluindo".

  4. Depois que a operação for concluída com êxito, o ponto de extremidade privado de backup e todos os mapeamentos de DNS associados serão removidos. O recurso não aparecerá como parte da operação de Lista, e a tentativa de uma operação Get nesse recurso resultará em um 404 não encontrado.

Steps involved in deleting shared private link resources

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

Tipo de Falha Descrição Resolução
O recurso está em estado não terminal Um recurso de link privado compartilhado que não está em um estado de terminal (Succeeded ou Failed) não pode ser excluído. É possível (ainda que raro) que um recurso de link privado compartilhado esteja preso em um estado não terminal por até 8 horas. Aguarde até que o recurso tenha atingido um estado terminal e repita a solicitação de exclusão.
Falha na operação de exclusão com o 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 de poder remover o ponto de extremidade privado e os mapeamentos de DNS. Os clientes podem utilizar Bloqueios de recursos do Azure para evitar qualquer alteração em seus recursos. Quando o Azure Resource Manager alcança o RP de destino, ele requer que o RP de destino modifique o estado do recurso de destino (para remover detalhes do ponto de extremidade privado de seus metadados). Quando o recurso de destino tem um bloqueio configurado (ou o 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 repetir a operação de exclusão. Observação: 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 do Azure Resource Manager assíncrona pode falhar em casos raros. Quando a operação falha, a consulta do estado da operação assíncrona apresentará aos clientes uma mensagem de erro e os detalhes apropriados. Repita 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 uma falha catastrófica no RP de pesquisa. Aguarde 8 horas. A partir daí, o recurso passará para o estado Failed. Em seguida, emita novamente a solicitação.

Próximas etapas

Saiba mais sobre os recursos de link privado compartilhado e como usá-los para tornar seguro o acesso a conteúdo protegido.