Configure respostas de erro personalizadas

Este documento fornece exemplos de configurações de respostas de erro personalizadas. Antes de configurar uma resposta de erro personalizada, leia a vista geral da resposta de erro personalizada.

As configurações de exemplo descritas nesta página configuram uma política de resposta de erro personalizada em três níveis do recurso de mapa de URLs: o nível do balanceador de carga, o nível do domínio do URL e o nível do caminho do URL.

As configurações de exemplo baseiam-se em conceitos e em configurações descritas nos seguintes documentos:

Exemplo 1: configure uma página de erro para todos os erros 4xx comuns a todos os anfitriões

Este exemplo pressupõe que configurou um balanceador de carga conforme descrito no artigo Configure um Application Load Balancer externo global com back-ends do grupo de instâncias de VM.

Neste exemplo, os pedidos ao balanceador de carga são encaminhados para o serviço de back-end denominado web-backend-service. Se o pedido encontrar uma resposta 4xx, a política de resposta de erro personalizada é configurada para enviar o pedido para o serviço de erros e um objeto de erro (not-found.html) é devolvido ao cliente.

Para criar uma política de resposta de erro personalizada, siga estes passos:

  1. Carregue a página de erro HTML (not-found.html) para o contentor do Cloud Storage.

    gcloud storage cp Desktop/not-found.html gs://GCS_BUCKET_NAME/

  2. Exporte o mapa de URLs (web-map-http) para um ficheiro denominado web-map-http.yaml.

    gcloud 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 URLs (web-map-http) tem uma configuração semelhante à seguinte.

    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

  3. Edite web-map-http.yaml para adicionar uma política de resposta de erro personalizada, conforme realçado na seguinte configuração YAML, na secção defaultCustomErrorResponsePolicy. Neste exemplo, é configurada uma política de resposta de erro ao 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 armazene todos os objetos de erro num contentor do Cloud Storage e que os tenha referenciados por um contentor de back-end anexado ao seu equilibrador de carga. Os contentores do Cloud Storage oferecem uma forma simples de armazenar os seus objetos de erro e devolvê-los aos seus clientes através do equilibrador de carga. No entanto, também pode publicar páginas de erro e recursos relacionados sem usar um contentor de back-end. Por exemplo, pode usar um serviço de back-end que faça referência a um back-end de grupo de instâncias de VM que tenha um servidor Apache configurado para publicar uma página de resposta de erro personalizada.

  4. Atualize o mapa de URLs importando a configuração mais recente de web-map-http.yaml.

    gcloud compute url-maps import web-map-http --source web-map-http.yaml

  5. Depois de atualizar o mapa de URLs, tem de aguardar algum tempo antes de poder começar a enviar tráfego para o endereço IP do equilibrador de carga.

    Enviar um pedido de uma página que não existe.

    curl -I http://IP_ADDRESS/a-page-that-does-not-exist

    O conteúdo de erro de not-found.html é publicado e é devolvido um código de estado HTTP 404.

Exemplo 2: configure uma página de erro para um código de erro específico para um anfitrião específico

Este exemplo baseia-se no exemplo anterior: configure uma página de erro para todos os erros 4xx comuns a todos os anfitriões. Assume que já está configurado um balanceador de carga de forma que os pedidos ao anfitrião video.example.com sejam encaminhados para o serviço de back-end denominado video-backend-service. Se um pedido não for autorizado pelo serviço de back-end, o serviço devolve uma resposta 401 (Unauthorized). A política de resposta de erro personalizada está configurada para enviar o pedido para o serviço de erros e é devolvido um objeto de erro (video-obtain-authorization.html) ao cliente.

Na maioria dos casos, o conteúdo do erro contém provavelmente links para recursos, por exemplo, uma imagem de um logótipo. O cliente faz pedidos de recursos referenciados na página de erro e são enviados pedidos adicionais para o balanceador de carga para os obter. Em seguida, o balanceador de carga responde ao pedido e devolve os recursos associados. Isto é conseguido armazenando estes recursos no mesmo contentor de back-end especificado em defaultCustomErrorResponsePolicy e adicionando uma regra para encaminhar pedidos de URLs de recursos (por exemplo, /assets/logo.svg) para o contentor de back-end. A resposta do balanceador de carga ao pedido de recursos associados não é uma resposta de erro, mas uma resposta normal, conforme mostrado na configuração seguinte.

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 deve ser o código de resposta final para o pedido. Neste exemplo, o código de resposta foi alterado de 401 para 200 especificando o valor de overrideResponseCode como 200. Para todos os outros erros 4xx , o conteúdo do erro em not-found.html é devolvido ao cliente e o código de resposta HTTP original do serviço de back-end é preservado.

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

Nível da política Campo da API Corresponde ao código de resposta HTTP Serviço de erros Objeto de erro devolvido
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 para o anfitriãovideo.example.com, siga estes passos:

  1. Carregue a página de erro HTML (video-obtain-authorization.html) e os recursos relacionados (logo.svg) para o contentor do Cloud Storage.

    gcloud storage cp Desktop/video-obtain-authorization.html gs://GCS_BUCKET_NAME/
gcloud storage cp Desktop/logo.svg gs://GCS_BUCKET_NAME/assets/

  2. Exporte o mapa de URLs (web-map-http) para um ficheiro denominado web-map-http.yaml.

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

  3. Edite web-map-http.yaml para adicionar uma política de resposta de erro personalizada, conforme realçado na seguinte configuração YAML, na secção defaultCustomErrorResponsePolicy. Neste exemplo, é configurada uma política de resposta de erro personalizada ao nível do equilibrador de carga (urlMaps.defaultCustomErrorResponsePolicy) e ao nível do domínio do URL (pathMatchers[].defaultCustomErrorResponsePolicy).

    Uma vez que o serviço de erros não está definido ao nível do domínio do URL, o serviço de erros ao nível do domínio do URL é predefinido para o serviço de erros definido ao nível superior, ou seja, ao nível do equilibrador 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

  4. Atualize o mapa de URLs importando a configuração mais recente de web-map-http.yaml.

    gcloud compute url-maps import web-map-http --source web-map-http.yaml

  5. Depois de atualizar o mapa de URLs, tem de aguardar algum tempo antes de poder começar a enviar tráfego para o endereço IP do equilibrador de carga.

    Envie um pedido ao seu anfitrião para um URL que necessite de autorização.

    curl -I http://video.example.com/a-page-that-needs-authorization

    O conteúdo de erro de video-obtain-authorization.html é publicado e é devolvido um código de estado HTTP 200.

Exemplo 3: configure políticas de resposta de erro personalizadas detalhadas para diferentes domínios, caminhos e códigos de resposta de erro

Este exemplo mostra como pode personalizar respostas de erro específicas para diferentes domínios de URL, caminhos de URL e códigos de resposta de erro HTTP.

A configuração de resposta de erro personalizada, explicada neste exemplo, pressupõe o seguinte:

  • Configurou um mapa de URLs para um Application Load Balancer externo com um encaminhamento baseado no anfitrião e no caminho, conforme representado na imagem seguinte.

    Exemplo de configuração do serviço de back-end
    Exemplo de configuração do serviço de back-end (clique para aumentar)

  • Configurou dois contentores de back-end denominados BUCKET_1 e BUCKET_2 para devolver as páginas de erro personalizadas.

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

  1. Caminho de URL (pathMatchers[].pathRules[].customErrorResponsePolicy)
  2. Domínio do URL (pathMatchers[].defaultCustomErrorResponsePolicy)
  3. Balanceador de carga (urlMaps.defaultCustomErrorResponsePolicy)
Nível da política Solicitar URL Corresponde ao código de resposta HTTP Serviço de erros Objeto de erro devolvido
Caminho de URL example.net/video/hd/* 404 BUCKET-2 not-found-hd-videos-404.html
Caminho de 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 erros 4xx ou 5xx BUCKET-1 error-page-generic.html

A política de resposta de erro personalizada ao nível do equilibrador de carga só é aplicada se a política corresponder às condições de erro e não tiver sido definida nenhuma política correspondente para o código de erro nos níveis inferiores, ou seja, o domínio do URL ou o caminho do URL. Da mesma forma, a política de resposta de erro personalizada ao nível do domínio do URL é aplicada apenas se a política corresponder às condições de erro e não tiver sido definida nenhuma política correspondente para o código de erro ao nível inferior, ou seja, o caminho do URL. Neste exemplo, se um pedido ao URL www.example.net/video/hd encontrar uma resposta 404, o ficheiro not-found-hd-videos-404.html é devolvido. No entanto, se for encontrada uma resposta 404 para um pedido ao URL www.example.net/video/, é devolvido o ficheiro example-net-4xx.html.

Para criar políticas de resposta de erro personalizadas em três níveis do mapa de URLs, siga estes passos:

  1. Carregue os objetos de erro para os contentores do Cloud Storage.

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

  2. Exporte o mapa de URLs (video-org-url-map) para um ficheiro denominado video-org-url-map.yaml.

    gcloud 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 URLs (video-org-url-map) tem uma configuração semelhante à seguinte.

    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

  3. Edite video-org-url-map.yaml para adicionar políticas de resposta de erro personalizadas, conforme realçado na seguinte configuração YAML, na secção defaultCustomErrorResponsePolicy.

    Uma vez que o serviço de erros não está definido ao nível do domínio do URL, o serviço de erros ao nível do domínio do URL é predefinido para o serviço de erros definido ao nível superior, ou seja, ao nível do equilibrador de carga.

    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

  4. Atualize o mapa de URLs importando a configuração mais recente de video-org-url-map.yaml.

    gcloud compute url-maps import video-org-url-map --source video-org-url-map.yaml

  5. Depois de atualizar o mapa de URLs, tem de aguardar algum tempo antes de poder começar a enviar tráfego para o endereço IP do equilibrador de carga.

    Enviar um pedido de uma página que não existe.

    curl -I http://example.net/a-page-that-does-not-exist

    É publicado o conteúdo de erro de example-net-4xx.html.

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