Solucionar problemas comuns com recursos de link privado compartilhado

Os recursos de link privado compartilhado permitem que o Azure Cognitive Search faça conexões de saída seguras para acessar recursos do cliente. No entanto, durante o processo de gerenciamento (criar, excluir ou atualizar) desses recursos podem ocorrer alguns tipos de erros.

Há quatro etapas distintas envolvidas na criação de um recurso de link privado compartilhado:

  1. O cliente invoca a API CreateOrUpdate do plano de gerenciamento no RP (Provedor de Recursos de Pesquisa) com detalhes do recurso de link privado compartilhado a ser criado.

  2. O RP de pesquisa valida a solicitação e, se válida, inicia uma operação assíncrona do Azure Resource Manager (cujo progresso pode ser consultado pelo cliente)

  3. Faça uma pesquisa por 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 "Atualização".

  4. Depois que a operação for concluída com êxito, será criado um ponto de extremidade privado (juntamente com qualquer zona ou mapeamento DNS). Neste ponto, se o cliente consultar o estado do recurso de link privado compartilhado, ele terá um estado de provisionamento "Êxito".

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

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: os recursos de link privado compartilhado só podem ser criados para SKUs pagos, não há suporte para serviços de camada gratuita.

  • Validação de nome: os nomes de recursos de link privado compartilhado são restritos apenas a um determinado conjunto de caracteres. Se o nome do recurso contiver caracteres inválidos, a solicitação para criar o recurso não será aceita. As regras para nomear um recurso de link privado compartilhado são:

    • O comprimento deve ter entre 1 e 60 caracteres.
    • Deve conter apenas caracteres alfanuméricos ou os caracteres sublinhado (_), ponto (.) ou hífen (-)
  • Validação groupId: o groupId especificado como parte da solicitação para criar um recurso de link privado compartilhado deve corresponder (tanto na ortografia quanto em maiúsculas e minúsculas) à 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 – API do SQL 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)" só estão disponíveis nas versões de API do plano de gerenciamento de versão prévia e ainda não estão disponíveis para uso geral. Qualquer outro groupId (ou groupId usado em uma versão de API que não oferece suporte) falharia na validação.

  • Validação de tipo privateLinkResourceId: de maneira semelhante a groupId, a Azure Cognitive 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
Banco de Dados do Azure para MySQL (pré-visualização) Microsoft.DBforMySQL/servers 2020-08-01-Preview
Cofre de Chave do Azure Microsoft.KeyVault/vaults 2020-08-01
Azure Functions (pré-visualização) Microsoft.Web/sites 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 Cognitive Search.

Falhas de implantação do Azure Resource Manager

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
Provedor de recursos de rede não registrado na assinatura do recurso de destino Um ponto de extremidade privado (e os mapeamentos DNS associados) é criado para o recurso de destino (Conta de Armazenamento, CosmosDB, SQL Server etc.) 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. Os clientes precisam registrar esse RP em sua assinatura de destino. Normalmente, isso pode ser feito por meio do portal do Azure, do PowerShell ou do CLI, conforme documentado neste guia
groupId inválido para o recurso de destino Quando as contas do CosmosDB são criadas, os clientes podem especificar o tipo de API para a conta do banco de dados. Embora o CosmosDB ofereça vários tipos diferentes de API, o Azure Cognitive Search dá suporte apenas a "Sql" como o groupId para os recursos de link privado compartilhado. Quando um recurso de link privado compartilhado "Sql" é criado em um privateLinkResourceId que aponta 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 CosmosDB não é suficiente para determinar o tipo de API que está sendo usado. O Azure Cognitive Search tenta criar o ponto de extremidade privado, o que é negado pelo CosmosDb. Os clientes devem garantir que o privateLinkResourceId do recurso do CosmosDb 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á. O cliente deve garantir que o recurso de destino esteja presente na assinatura e no grupo de recursos especificados e não tenha sido movido/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.

Recurso preso no estado "Atualizando" ou "Incompleto"

Normalmente, um recurso de link privado compartilhado deve atingir um estado terminal (Succeeded ou Failed) alguns minutos após a solicitação ter sido aceita pelo RP de pesquisa.

Em circunstâncias raras, o Azure Cognitive 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 ou catastrófica no RP de pesquisa. Os recursos de link privado compartilhado serão automaticamente transicionados para um estado Failed se ele estiver "preso" em um estado não terminal por mais de 8 horas.

Se você observar que o recurso de link privado compartilhado não fez a transição para um estado terminal, aguarde 8 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. O RP de 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. O cliente solicita ao RP de pesquisa para excluir o recurso de link privado compartilhado.

  2. O RP 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.

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

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.