配置自定义错误响应

本文档提供了自定义错误响应的示例配置。在配置自定义错误响应之前，请先阅读自定义错误响应概览。

本页面介绍的示例配置会在网址映射资源的三个级层（负载均衡器级层、网址网域级层和网址路径级层）配置自定义错误响应政策。

示例配置借鉴了以下文档中介绍的概念并基于其中的设置进行构建：

• 设置具有虚拟机实例组后端的全局外部应用负载均衡器。
• 创建后端存储桶
• 网址映射的工作原理
• 配置网址映射

示例 1：为所有主机共有的所有 4xx 错误配置错误页面

此示例假定您已按照设置具有虚拟机实例组后端的全球外部应用负载均衡器中的说明设置了负载均衡器。

在此示例中，对负载均衡器的请求会被路由到名为 web-backend-service 的后端服务。如果请求遇到 4xx 响应，则自定义错误响应政策会配置为随后将请求发送到错误服务，并且会向客户端返回错误对象 (not-found.html)。

如需创建自定义错误响应政策，请按照以下步骤操作：

1. 将 HTML 错误页面 (not-found.html) 上传到 Cloud Storage 存储桶。

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

2. 将网址映射 (web-map-http) 导出到名为 web-map-http.yaml 的文件中。

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

   在添加自定义错误响应政策之前，网址映射 (web-map-http) 具有类似如下的配置。

   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. 修改 web-map-http.yaml 以添加自定义错误响应政策，如以下 YAML 配置中的 defaultCustomErrorResponsePolicy 部分中突出显示的内容所示。在此示例中，在负载均衡器级层 (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
   

   我们建议您将所有错误对象存储在一个 Cloud Storage 存储桶中，并由连接到负载均衡器的后端存储桶引用这些对象。Cloud Storage 存储桶为您提供了一种简单的方式来存储错误对象，并使用负载均衡器将这些对象返回到客户端。但是，您也可以在不使用后端存储桶的情况下传送错误页面和相关资产。例如，您可以使用后端服务来引用虚拟机实例组后端，该后端配置了 Apache 服务器以提供自定义错误响应页面。

4. 通过从 web-map-http.yaml 导入最新配置来更新网址映射。

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

5. 更新网址映射后，您需要等待一段时间，然后才能开始将流量发送到负载均衡器的 IP 地址。

   向不存在的页面发送请求。

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

   系统将传送 not-found.html 中的错误内容，并返回 HTTP 404 状态代码。

示例 2：为特定主机的特定错误代码配置错误页面

本示例基于上一个示例 - 为所有主机共有的所有 4xx 错误配置错误页面。它假设已配置负载均衡器，因此对主机 video.example.com 的请求会路由到名为 video-backend-service 的后端服务。如果请求未通过后端服务授权，则服务将返回 401 (Unauthorized) 响应。自定义错误响应政策会配置为随后向错误服务发送请求，并且会向客户端返回错误对象 (video-obtain-authorization.html)。

在大多数情况下，您的错误内容可能包含资产（例如徽标图片）的链接。客户端会向错误页面中引用的资产发出请求，然后将其他请求发送到负载均衡器以提取资产。负载均衡器随后会响应该请求，并返回关联的资产。此操作的实现方式是将这些资产存储在 defaultCustomErrorResponsePolicy 中指定的同一个后端存储桶中，然后添加规则将请求从资产网址（例如 /assets/logo.svg）路由到后端存储桶。负载均衡器对关联资产请求的响应不是错误响应，而是正常响应，如以下配置所示。

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

该政策还可让您定义请求的最终响应代码。在此示例中，通过将 overrideResponseCode 的值指定为 200，响应代码已从 401 更改为 200。对于所有其他 4xx 错误，not-found.html 中的错误内容会返回给客户端，并且来自后端服务的原始 HTTP 响应代码会被保留。

如下表所示，此示例中配置了两个自定义错误响应政策。这些政策在负载均衡器级层和网址网域级层创建。

政策级层	API 字段	匹配 HTTP 响应代码	错误服务	返回的错误对象
网址网域	pathMatchers[].defaultCustomErrorResponsePolicy	401	CUSTOM_ERRORS_BUCKET	video-obtain-authorization.html
负载均衡器	urlMaps.defaultCustomErrorResponsePolicy	所有 4xx	CUSTOM_ERRORS_BUCKET	not-found.html

如需为主机 video.example.com 的 401 错误代码创建自定义错误响应政策，请按照以下步骤操作：

1. 将 HTML 错误页面 (video-obtain-authorization.html) 和相关资产 (logo.svg) 上传到 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. 将网址映射 (web-map-http) 导出到名为 web-map-http.yaml 的文件中。

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

3. 修改 web-map-http.yaml 以添加自定义错误响应政策，如以下 YAML 配置中的 defaultCustomErrorResponsePolicy 部分中突出显示的内容所示。在此示例中，在负载均衡器级层 (urlMaps.defaultCustomErrorResponsePolicy) 和网址网域级层 (pathMatchers[].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=
   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. 通过从 web-map-http.yaml 导入最新配置来更新网址映射。

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

5. 更新网址映射后，您需要等待一段时间，然后才能开始将流量发送到负载均衡器的 IP 地址。

   向您的主机发送请求，以获取需要授权的网址。

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

   系统将传送 video-obtain-authorization.html 中的错误内容，并返回 HTTP 200 状态代码。

示例 3：为不同的网域、路径和错误响应代码配置精细的自定义错误响应政策

此示例展示了如何为不同网址网域、网址路径和 HTTP 错误响应代码自定义特定错误响应。

此示例中介绍的自定义错误响应配置假定：

• 您已使用主机和基于路径的路由为外部应用负载均衡器配置了网址映射，如下图所示。

  

  后端服务设置示例（点击放大）

• 您已配置两个名为 BUCKET_1 和 BUCKET_2 的后端存储桶以返回自定义错误页面。

如下表所示，此示例中配置了四个自定义错误响应政策。这些政策按以下优先顺序在三个级层创建：

1. 网址路径 (pathMatchers[].pathRules[].customErrorResponsePolicy)
2. 网址网域 (pathMatchers[].defaultCustomErrorResponsePolicy)
3. 负载均衡器 (urlMaps.defaultCustomErrorResponsePolicy)

政策级层	请求网址	匹配 HTTP 响应代码	错误服务	返回的错误对象
网址路径	example.net/video/hd/*	404	BUCKET-2	not-found-hd-videos-404.html
网址路径	example.net/video/sd/*	404	BUCKET-2	not-found-sd-videos-404.html
网址网域	example.net/*	所有 4xx	BUCKET-1	example-net-4xx.html
负载均衡器	Any	所有 4xx 或 5xx	BUCKET-1	error-page-generic.html

只有在政策与错误条件匹配且没有在较低级层（即网址网域或网址路径）为错误代码定义任何匹配政策时，系统才会在负载均衡器级层应用自定义错误响应政策。同样，只有在政策与错误条件匹配且没有在较低级层（即网址路径）为错误代码定义任何匹配政策时，系统才会在网址网域级层应用自定义错误响应政策。在此示例中，如果对网址 www.example.net/video/hd 的请求遇到 404 响应，则返回文件 not-found-hd-videos-404.html。但是，如果对网址 www.example.net/video/ 的请求遇到 404 响应，则会返回文件 example-net-4xx.html。

如需在网址映射的三个级层创建自定义错误响应政策，请按照以下步骤操作：

1. 将错误对象上传到 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. 将网址映射 (video-org-url-map) 导出到名为 video-org-url-map.yaml. 的文件中

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

   在添加自定义错误响应政策之前，网址映射 (video-org-url-map) 具有类似如下的配置。

   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. 修改 video-org-url-map.yaml 以添加自定义错误响应政策，如以下 YAML 配置中的 defaultCustomErrorResponsePolicy 部分中突出显示的内容所示。

   由于错误服务未在网址网域级层定义，因此网址网域级层的错误服务默认为在较高级层（即负载均衡器级层）定义的错误服务。

   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. 通过从 video-org-url-map.yaml 导入最新配置来更新网址映射。

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

5. 更新网址映射后，您需要等待一段时间，然后才能开始将流量发送到负载均衡器的 IP 地址。

   向不存在的页面发送请求。

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

   系统将提供 example-net-4xx.html 中的错误内容。

   同样，请测试是否存在其他具有不同网址网域和网址路径的其他网址。