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:

  1. 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/
    
  2. 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
    
  3. Edite web-map-http.yaml para adicionar uma política personalizada de resposta de erro, conforme destacado na seguinte configuração YAML, na seção defaultCustomErrorResponsePolicy. 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.

  4. 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
    
  5. 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:

  1. 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/
    
  2. 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
    
  3. Edite web-map-http.yaml para adicionar uma política personalizada de resposta de erro, conforme destacado na seguinte configuração YAML, na seção defaultCustomErrorResponsePolicy. 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
    
  4. 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
    
  5. 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:

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:

  1. Caminho do URL (pathMatchers[].pathRules[].customErrorResponsePolicy)
  2. Domínio do URL (pathMatchers[].defaultCustomErrorResponsePolicy)
  3. 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:

  1. 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/
    
  2. 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
    
  3. Edite video-org-url-map.yaml para adicionar políticas personalizadas de resposta de erro, conforme destacado na seguinte configuração YAML, na seção 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: '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. 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
    
  5. 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.