Share via

Criar páginas de erro personalizadas do Gateway de Aplicativo

  • Artigo

O Gateway de Aplicativo permite que você crie páginas de erro personalizadas em vez de exibir as padrão. Você pode usar sua marca e layout para erros relacionados a diferentes códigos de resposta. Alguns cenários para definir páginas de erro personalizadas são:

  • Mostrando uma página de manutenção ou status para o código de resposta do 502 Bad Gateway. Isso é útil quando o gateway de aplicativo não tem nenhum servidor de back-end para rotear o tráfego durante a manutenção programada ou um problema imprevisto com servidores de pool de back-end.
  • Mostrando uma página personalizada de acesso não autorizado para o código de resposta 403 Forbidden que ocorre quando o WAF está no modo de prevenção e bloqueia o tráfego mal-intencionado.
  • Mostrando uma página com a marca da empresa com detalhes de contato em caso de problema.

Códigos de resposta suportados

As páginas de erro personalizadas são suportadas para os seguintes códigos de resposta:

Código de resposta Descrição
400 Solicitação incorreta (em visualização)
403 Proibido
405 Método não permitido (em visualização)
408 Tempo limite da solicitação (em visualização)
500 Erro interno do servidor (em visualização)
502 Gateway inválido
503 Serviço indisponível (em visualização)
504 Tempo limite do gateway (em visualização)

Observação

  • A API versão 2022-09-01 ou posterior deve ser usada para configurar páginas de erro para os novos códigos de resposta (em visualização).
  • O código de resposta 404 (Página não encontrada) não é suportado no momento.
  • As páginas de erro personalizadas são exibidas para códigos de resposta gerados pelo Gateway de Aplicativo. Se um erro se originar do servidor back-end, ele será transmitido sem modificações para o cliente.

Níveis de configuração

As páginas de erro personalizadas podem ser definidas em um nível Global ou Ouvinte:

  • Nível global - As páginas de erro definidas em um nível global são aplicadas a todos os ouvintes desse gateway de aplicativo. Sua configuração por meio do portal do Azure não tem suporte no momento.
  • Nível ouvinte - As páginas de erro em um nível ouvinte fornecem controle granular para definir páginas de erro para o aplicativo servido por esse ouvinte.

Observação

Ao usar uma combinação de páginas de erro no nível Global e Ouvinte para um gateway, você deve mencionar explicitamente as URLs de todos os códigos de resposta desejados para esse ouvinte. Uma configuração específica do ouvinte substitui todas as configurações globais anteriores aplicáveis a esse ouvinte.

Requisitos

Para criar uma página de erro personalizada, você deve

  • Saiba o código de resposta para o qual uma página de erro personalizada é necessária.
  • saber o local remoto correspondente (URL) para a página HTML. Este deve ser um arquivo acessível publicamente.
  • Verifique se a página de erro está acessível publicamente e retorne uma resposta 200.
  • Verifique se a página de erro deve estar no tipo de extensão *.htm ou *.html.
  • verifique se o tamanho da página é menor que 1 MB.

Você pode fazer referência a imagens/CSS internas ou externas para esse arquivo HTML. Para recursos referenciados externamente, use URLs absolutas de acesso público. Esteja ciente do tamanho do arquivo HTML ao usar imagens embutidas codificadas em base64, JavaScript ou CSS.

Observação

  • No ecossistema do Azure, você deve usar uma conta de armazenamento de Blob do Azure ou uma Máquina Virtual para hospedar uma página de erro. Observe que o armazenamento de Blob deve ser diretamente acessível, pois as contas de armazenamento lideradas pelos serviços de CDN do Azure não têm suporte no momento.
  • Você também pode optar por hospedar as páginas de erro em qualquer local remoto.
  • Não há suporte para links relativos.

Como funciona?

Depois de especificar uma página de erro na configuração do gateway de aplicativo, o gateway verifica a conectividade com a página HTML pela Internet. Em seguida, ele baixa o arquivo em seu cache local.

Quando um cliente enfrenta um erro, o gateway de aplicativo retorna um código de resposta e essa página HTML. Todos os recursos referenciados externamente (como imagens, JavaScript e arquivos CSS) são buscados diretamente pelo cliente.

O gateway de aplicativo não verifica periodicamente o local do arquivo de origem para buscar uma nova versão. Você pode executar qualquer atualização de configuração no gateway para atualizar manualmente o cache do arquivo. Por exemplo, alterando a URL de erro da página 1 para a página 2 e, em seguida, de volta para a página 1 ou ao adicionar um novo ouvinte.

Configuração do portal

Etapas para configurar páginas de erro personalizadas específicas do ouvinte:

  1. Navegue até Gateway de Aplicativo no portal e escolha o recurso necessário.

  2. Selecione Ouvintes e navegue até um ouvinte específico para o qual você deseja especificar uma página de erro.

  3. Na seção Páginas de erro personalizadas especifique URLs acessíveis publicamente para os códigos de status necessários.

  4. Selecione Salvar.

    Screenshot of Application Gateway custom error page.

Configuração do Azure PowerShell

Você também pode usar o Azure PowerShell para configurar uma página de erro personalizada. Por exemplo, uma página de erro personalizada global:

$appgw   = Get-AzApplicationGateway -Name <app-gateway-name> -ResourceGroupName <resource-group-name>

$updatedgateway = Add-AzApplicationGatewayCustomError -ApplicationGateway $appgw -StatusCode HttpStatus502 -CustomErrorPageUrl "http://<website-url>"

Set-AzApplicationGateway -ApplicationGateway $appgw

Ou uma página de erro de nível de ouvinte:

$appgw   = Get-AzApplicationGateway -Name <app-gateway-name> -ResourceGroupName <resource-group-name>

$listener01 = Get-AzApplicationGatewayHttpListener -Name <listener-name> -ApplicationGateway $appgw

$updatedlistener = Add-AzApplicationGatewayHttpListenerCustomError -HttpListener $listener01 -StatusCode HttpStatus502 -CustomErrorPageUrl "http://<website-url>"

Set-AzApplicationGateway -ApplicationGateway $appgw

Para obter mais informações, confira Add-AzApplicationGatewayCustomError e Add-AzApplicationGatewayHttpListenerCustomError.

Próximas etapas

Para obter informações sobre o diagnóstico do Gateway de Aplicativo, confira Integridade do back-end, logs de diagnóstico e métricas do Gateway de Aplicativo.