Configurar respostas de erro personalizadas

Neste documento, apresentamos exemplos de configuração de respostas de erro personalizadas. Antes de configurar uma resposta de erro personalizada, leia a Visão geral sobre respostas de erro personalizadas.

Os exemplos de configuração descritos nesta página definem uma política de resposta de erro personalizada em três níveis do recurso de mapa de URL: o nível do balanceador de carga, o nível do domínio do URL e o nível do caminho do URL.

Os exemplos de configuração são baseados em conceitos e configurações descritos nos documentos a seguir:

Exemplo 1: configurar uma página de erro para todos os erros `4xx` comuns a todos os hosts

Neste exemplo, consideramos que você já configurou um balanceador de carga conforme descrito em Configurar um balanceador de carga de aplicativo externo global com back-ends de grupos de instâncias de VM.

Neste exemplo, as solicitações ao balanceador de carga são roteadas para o serviço de back-end chamado web-backend-service. Se a solicitação encontrar uma resposta 4xx, a política de resposta de erro personalizada será configurada para que envie a solicitação ao serviço de erro e um objeto de erro (not-found.html) será retornado ao cliente.

Para criar uma política de resposta de erro personalizada, siga estas etapas:

Faça upload da página de erro HTML (not-found.html) para o bucket do Cloud Storage.
```
gsutil cp Desktop/not-found.html gs://GCS_BUCKET_NAME/
```

Exporte o mapa de URL (web-map-http) para um arquivo chamado web-map-http.yaml.

gcloud beta compute url-maps export web-map-http --destination web-map-http.yaml

Antes de adicionar a política de resposta de erro personalizada, o mapa de URL (web-map-http) tem uma configuração semelhante a esta.

creationTimestamp: '2020-01-14T19:12:44.680-08:00'
defaultService: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendServices/web-backend-service
fingerprint: d0eJJpCBpHg=
kind: compute#urlMap
name: web-map-http
selfLink: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/urlMaps/web-map-http

Edite web-map-http.yaml para adicionar uma política de resposta de erro personalizada, conforme destacado na configuração YAML a seguir. Neste exemplo, uma política de resposta de erro é configurada no nível do balanceador de carga (urlMaps.defaultCustomErrorResponsePolicy).
```
creationTimestamp: '2020-01-14T19:12:44.680-08:00'
defaultService: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendServices/web-backend-service
defaultCustomErrorResponsePolicy:
  errorResponseRules:
    - matchResponseCodes:
      - 4xx
      path: '/not-found.html'
  errorService: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendBuckets/CUSTOM_ERRORS_BUCKET
fingerprint: d0eJJpCBpHg=
kind: compute#urlMap
name: web-map-http
selfLink: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/urlMaps/web-map-http
```
Recomendamos que você armazene todos os objetos de erro em um bucket do Cloud Storage e defina referências a eles por um bucket de back-end anexado ao balanceador de carga. Com os buckets do Cloud Storage, você tem uma maneira simples de armazenar objetos de erro e fazer com que sejam retornados aos clientes usando o balanceador de carga. No entanto, também é possível exibir páginas de erro e recursos relacionados sem usar um bucket de back-end. Por exemplo, é possível usar um serviço de back-end com referência a um back-end de grupos de instâncias de VM que tem um servidor Apache configurado para disponibilizar uma página de resposta de erro personalizada.
Importe a configuração mais recente de web-map-http.yaml para atualizar o mapa de URL.
```
gcloud beta compute url-maps import web-map-http --source web-map-http.yaml
```
Depois de atualizar o mapa de URL, aguarde alguns instantes antes de começar a enviar tráfego para o endereço IP do balanceador de carga.

Envie uma solicitação de uma página que não existe.
```
curl -I http://IP_ADDRESS/a-page-that-does-not-exist
```
O conteúdo do erro de not-found.html é exibido, e um código de status HTTP 404 é retornado.

Exemplo 2: configurar uma página de erro para um código de erro específico de um determinado host

Este exemplo é baseado no anterior: configurar uma página de erro para todos os erros 4xx comuns a todos os hosts. Consideramos que um balanceador de carga já esteja configurado de modo que as solicitações ao host video.example.com sejam roteadas para o serviço de back-end chamado video-backend-service. Se a autorização do serviço de back-end falhar em uma solicitação, o serviço retornará uma resposta 401 (Unauthorized). A política de resposta de erro personalizada é configurada para que envie a solicitação ao serviço de erro, e um objeto de erro (video-obtain-authorization.html) é retornado ao cliente.

Na maioria dos casos, é provável que o conteúdo do erro contenha links para recursos, como uma imagem de logotipo. O cliente faz solicitações de recursos referenciados na página de erro, e outras solicitações são enviadas ao balanceador de carga para buscá-los. Em seguida, o balanceador de carga responde à solicitação e retorna os recursos vinculados. Para que isso aconteça, esses recursos são armazenados no mesmo bucket de back-end especificado em defaultCustomErrorResponsePolicy, e uma regra é adicionada para rotear solicitações de URLs de recursos (por exemplo, /assets/logo.svg) para o bucket de back-end. A resposta do balanceador de carga à solicitação de recursos vinculados não é uma resposta de erro, mas uma resposta normal, conforme mostrado na configuração a seguir.

pathMatchers:
...
  pathRules:
  - service: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendBuckets/CUSTOM_ERRORS_BUCKET
    paths:
    - /assets

A política também permite definir qual será o código de resposta final da solicitação. Neste exemplo, o código de resposta mudou de 401 para 200 especificando o valor de overrideResponseCode para 200. Para todos os outros erros 4xx, o conteúdo do erro em not-found.html é retornado ao cliente e o código de resposta HTTP original do serviço de back-end é preservado.

Conforme mostrado na tabela a seguir, duas políticas personalizadas de resposta de erro estão configuradas neste exemplo. Essas políticas são criadas no nível do balanceador de carga e no nível do domínio do URL.

Nível da política	Campo da API	Corresponder ao código de resposta HTTP	Serviço de erro	Objeto de erro retornado
Domínio do URL	`pathMatchers[].defaultCustomErrorResponsePolicy`	401	`CUSTOM_ERRORS_BUCKET`	`video-obtain-authorization.html`
Balanceador de carga	`urlMaps.defaultCustomErrorResponsePolicy`	Todos os 4xx	`CUSTOM_ERRORS_BUCKET`	`not-found.html`

Para criar uma política de resposta de erro personalizada para um código de erro 401 do host video.example.com, siga estas etapas:

Faça upload da página de erro HTML (video-obtain-authorization.html) e dos recursos relacionados (logo.svg) para o bucket do Cloud Storage.
```
gsutil cp Desktop/video-obtain-authorization.html gs://GCS_BUCKET_NAME/
gsutil cp Desktop/logo.svg gs://GCS_BUCKET_NAME/assets/
```

Exporte o mapa de URL (web-map-http) para um arquivo chamado web-map-http.yaml.

gcloud beta compute url-maps export web-map-http --destination web-map-http.yaml

Edite web-map-http.yaml para adicionar uma política de resposta de erro personalizada, conforme destacado na configuração YAML a seguir. Neste exemplo, uma política de resposta de erro personalizada é configurada no nível do balanceador de carga (urlMaps.defaultCustomErrorResponsePolicy) e no nível do domínio do URL (pathMatchers[].defaultCustomErrorResponsePolicy).

Como o serviço de erro não está definido no nível do domínio do URL, o serviço de erro nesse nível recebe como padrão o serviço de erro definido no nível superior. Isto é, no nível do balanceador de carga.

creationTimestamp: '2020-01-14T19:12:44.680-08:00'
defaultService: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendServices/web-backend-service
defaultCustomErrorResponsePolicy:
  errorResponseRules:
    - matchResponseCodes:
      - 4xx
      path: '/not-found.html'
  errorService: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendBuckets/CUSTOM_ERRORS_BUCKET
fingerprint: d0eJJpCBpHg=
hostRules:
- hosts:
  - video.example.com
  pathMatcher: path-matcher-1
kind: compute#urlMap
name: web-map-http
selfLink: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/urlMaps/web-map-http
pathMatchers:
- defaultService: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendServices/video-backend-service
  name: path-matcher-1
  defaultCustomErrorResponsePolicy:
    errorResponseRules:
      - matchResponseCodes:
        - 401
        path: "/video-obtain-authorization.html 
        overrideResponseCode: 200
    // The `errorService` in `pathMatchers[].defaultCustomErrorResponsePolicy` references the
    // error service configured in `urlMaps.defaultCustomErrorResponsePolicy`.

  // A URL map path rule to route requests from asset URLs (for example, "/assets/logo.svg") to the backend bucket.
  pathRules:
  - service: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendBuckets/CUSTOM_ERRORS_BUCKET
    paths:
    - /assets

Importe a configuração mais recente de web-map-http.yaml para atualizar o mapa de URL.
```
gcloud beta compute url-maps import web-map-http --source web-map-http.yaml
```
Depois de atualizar o mapa de URL, aguarde alguns instantes antes de começar a enviar tráfego para o endereço IP do balanceador de carga.

Envie uma solicitação ao host de um URL que precisa de autorização.
```
curl -I http://video.example.com/a-page-that-needs-authorization
```
O conteúdo do erro de video-obtain-authorization.html é exibido, e um código de status HTTP 200 é retornado.

Exemplo 3: configurar políticas granulares de resposta de erro personalizada para diferentes domínios, caminhos e códigos de resposta de erro

Neste exemplo, mostramos como é possível personalizar respostas de erro específicas para diferentes domínios de URL, caminhos de URL e códigos de resposta de erro HTTP.

Para a configuração de resposta de erro personalizada, explicada neste exemplo, consideramos que:

você configurou um mapa de URL para um balanceador de carga de aplicativo externo com um roteamento baseado em host e caminho, conforme mostrado na imagem a seguir;

Exemplo de configuração do serviço de back-end (clique para ampliar)
você configurou dois buckets de back-end chamados BUCKET_1 e BUCKET_2 para retornar as páginas de erro personalizadas.

Conforme mostrado na tabela a seguir, quatro políticas de resposta de erro personalizada estão configuradas neste exemplo. Essas políticas são criadas em três níveis na seguinte ordem de precedência:

Caminho do URL (pathMatchers[].pathRules[].customErrorResponsePolicy)
Domínio do URL (pathMatchers[].defaultCustomErrorResponsePolicy)
Balanceador de carga (urlMaps.defaultCustomErrorResponsePolicy)

Nível da política	URL da solicitação	Corresponder ao código de resposta HTTP	Serviço de erro	Objeto de erro retornado
Caminho do URL	`example.net/video/hd/*`	404	`BUCKET-2`	`not-found-hd-videos-404.html`
Caminho do URL	`example.net/video/sd/*`	404	`BUCKET-2`	`not-found-sd-videos-404.html`
Domínio do URL	`example.net/*`	Todos os 4xx	`BUCKET-1`	`example-net-4xx.html`
Balanceador de carga	`Any`	Todos os 4xx ou 5xx	`BUCKET-1`	`error-page-generic.html`

A política de resposta de erro personalizada no nível do balanceador de carga será aplicada somente se ela corresponder às condições de erro e nenhuma política correspondente estiver definida para o código do erro nos níveis inferiores. Isto é, o URL do domínio ou o caminho do URL. Da mesma forma, a política de resposta de erro personalizada no nível do domínio do URL será aplicada somente se ela corresponder às condições de erro e se nenhuma política correspondente estiver definida para o código do erro no nível inferior. Isto é, o caminho do URL. Neste exemplo, se uma solicitação ao URL www.example.net/video/hd encontrar uma resposta 404, o arquivo not-found-hd-videos-404.html será retornado. No entanto, se uma resposta 404 for encontrada para uma solicitação ao URL www.example.net/video/, o arquivo example-net-4xx.html será retornado.

Para criar políticas de resposta de erro personalizada em três níveis do mapa de URL, siga estas etapas:

Faça upload dos objetos de erro para os buckets do Cloud Storage.

gsutil cp Desktop/error-page-generic.html gs://GCS_BUCKET_1_NAME/
gsutil cp Desktop/example-net-4xx.html gs://GCS_BUCKET_1_NAME/
gsutil cp Desktop/not-found-sd-videos-404.html gs://GCS_BUCKET_2_NAME/
gsutil cp Desktop/not-found-hd-videos-404.html gs://GCS_BUCKET_2_NAME/

Exporte o mapa de URL (video-org-url-map) para um arquivo chamado video-org-url-map.yaml.

gcloud beta compute url-maps export video-org-url-map --destination video-org-url-map.yaml

Antes de adicionar a política de resposta de erro personalizada, o mapa de URL (video-org-url-map) tem uma configuração semelhante a esta.

creationTimestamp: '2021-03-05T13:34:15.833-08:00'
defaultService: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendServices/org-site
fingerprint: mfyJIT7Zurs=
hostRules:
- hosts:
  - '*'
  pathMatcher: video-matcher
- hosts:
  - example.net
  pathMatcher: video-matcher
id: '8886405179645041976'
kind: compute#urlMap
name: video-org-url-map
pathMatchers:
- defaultService: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendServices/video-site
  name: video-matcher
  pathRules:
  - paths:
    - /video/hd
    - /video/hd/*
    service: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendServices/video-hd
  - paths:
    - /video/sd
    - /video/sd/*
    service: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendServices/video-sd
selfLink: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/urlMaps/video-org-url-map

Edite video-org-url-map.yaml para adicionar políticas de resposta de erro personalizada, conforme destacado na configuração YAML a seguir.

creationTimestamp: '2021-03-05T13:34:15.833-08:00'
defaultService: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendServices/org-site
fingerprint: mfyJIT7Zurs=
hostRules:
- hosts:
  - '*'
  pathMatcher: video-matcher
- hosts:
  - example.net
  pathMatcher: video-matcher
id: '8886405179645041976'
kind: compute#urlMap
name: video-org-url-map
defaultCustomErrorResponsePolicy:
  errorResponseRules:
    - matchResponseCodes:
      - 4xx
      - 5xx
      path: '/error-page-generic.html'
  errorService: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendBuckets/BUCKET-1
pathMatchers:
- defaultService: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendServices/video-site
  name: video-matcher
  defaultCustomErrorResponsePolicy:
      errorResponseRules:
        - matchResponseCodes:
          - 4xx
          path: '/example-net-4xx.html'
      // The `errorService` in `pathMatchers[].defaultCustomErrorResponsePolicy` references the
      // error service configured in `urlMaps.defaultCustomErrorResponsePolicy`.
  pathRules:
  - paths:
    - /video/hd
    - /video/hd/*
    service: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendServices/video-hd
    customErrorResponsePolicy:
          errorResponseRules:
            - matchResponseCodes:
              - 404
              path: '/not-found-hd-videos-404.html'
          errorService: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendBuckets/BUCKET-2
  - paths:
    - /video/sd
    - /video/sd/*
    service: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendServices/video-sd
    customErrorResponsePolicy:
          errorResponseRules:
            - matchResponseCodes:
              - 404
              path: '/not-found-sd-videos-404.html'
          errorService: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendBuckets/BUCKET-2
selfLink: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/urlMaps/video-org-url-map

Importe a configuração mais recente de video-org-url-map.yaml para atualizar o mapa de URL.
```
gcloud beta compute url-maps import video-org-url-map --source video-org-url-map.yaml
```
Depois de atualizar o mapa de URL, aguarde alguns instantes antes de começar a enviar tráfego para o endereço IP do balanceador de carga.

Envie uma solicitação de uma página que não existe.
```
curl -I http://example.net/a-page-that-does-not-exist
```
O conteúdo do erro de example-net-4xx.html é exibido.

Da mesma forma, teste outros URLs com diferentes domínios e caminhos de URL.

Configurar respostas de erro personalizadas

Exemplo 1: configurar uma página de erro para todos os erros 4xx comuns a todos os hosts

Exemplo 2: configurar uma página de erro para um código de erro específico de um determinado host

Exemplo 3: configurar políticas granulares de resposta de erro personalizada para diferentes domínios, caminhos e códigos de resposta de erro

Exemplo 1: configurar uma página de erro para todos os erros `4xx` comuns a todos os hosts