配置自定义错误响应

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

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

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

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

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

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

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

将 HTML 错误页面 (not-found.html) 上传到 Cloud Storage 存储桶。
```
gsutil cp Desktop/not-found.html gs://GCS_BUCKET_NAME/
```

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

gcloud beta 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

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

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

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

更新网址映射后，您需要等待一段时间，然后才能开始将流量发送到负载均衡器的 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 错误代码创建自定义错误响应政策，请按照以下步骤操作：

将 HTML 错误页面 (video-obtain-authorization.html) 和相关资产 (logo.svg) 上传到 Cloud Storage 存储桶。

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

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

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

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

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

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

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

向您的主机发送请求，以获取需要授权的网址。
```
curl -I http://video.example.com/a-page-that-needs-authorization
```
系统将传送 video-obtain-authorization.html 中的错误内容，并返回 HTTP 200 状态代码。

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

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

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

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

后端服务设置示例（点击放大）
您已配置两个名为 BUCKET_1 和 BUCKET_2 的后端存储桶以返回自定义错误页面。

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

网址路径 (pathMatchers[].pathRules[].customErrorResponsePolicy)
网址网域 (pathMatchers[].defaultCustomErrorResponsePolicy)
负载均衡器 (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。

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

将错误对象上传到 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/

将网址映射 (video-org-url-map) 导出到名为 video-org-url-map.yaml. 的文件中

gcloud beta 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

修改 video-org-url-map.yaml 以添加自定义错误响应政策，如以下 YAML 配置所示。