カスタムエラーレスポンスを構成する

このドキュメントでは、カスタムエラーレスポンスの構成例について説明します。カスタムエラーレスポンスを構成する前に、カスタムエラーレスポンスの概要をご覧ください。

このページで説明する構成例では、URL マップリソースの 3 つのレベル（ロードバランサレベル、URL ドメインレベル、URL パスレベル）でカスタムエラーレスポンスポリシーを構成します。

この構成例は、次のドキュメントで説明しているコンセプトと設定に基づいて構成されています。

例 1: すべてのホストに共通するすべての `4xx` エラーのエラーページを構成する

この例では、VM インスタンスグループのバックエンドを使用してグローバル外部アプリケーションロードバランサを設定するの説明に従ってロードバランサを設定していることを前提としています。

この例では、ロードバランサへのリクエストが web-backend-service という名前のバックエンドサービスに転送されます。リクエストに 4xx レスポンスが返されると、カスタムエラーレスポンスポリシーによりエラーサービスにリクエストが送信され、エラーオブジェクト（not-found.html）がクライアントに返されます。

カスタムエラーレスポンスポリシーを作成する手順は次のとおりです。

HTML エラーページ（not-found.html）を Cloud Storage バケットにアップロードします。
```
gsutil cp Desktop/not-found.html gs://GCS_BUCKET_NAME/
```

URL マップ（web-map-http）を web-map-http.yaml という名前のファイルにエクスポートします。

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

カスタムエラーレスポンスポリシーを追加する前の URL マップ（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

次の YAML 構成でハイライト表示されているように、web-map-http.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 バケットを使用すると、エラーオブジェクトを簡単に保存し、ロードバランサを介してクライアントに返すことができます。ただし、バックエンドバケットを使用せずにエラーページと関連アセットを提供することもできます。たとえば、VM インスタンスグループバックエンドを参照し、カスタムエラーレスポンスページを提供するように Apache サーバーが構成されているバックエンドサービスを使用することもできます。
web-map-http.yaml から最新の構成をインポートして、URL マップを更新します。
```
gcloud beta compute url-maps import web-map-http --source web-map-http.yaml
```
URL マップを更新したら、ロードバランサの 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 で指定された同じバックエンドバケットに保存し、アセット URL（/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 レスポンスコードが保持されます。

次の表に示すように、この例では 2 つのカスタムエラーレスポンスポリシーが構成されています。これらのポリシーは、ロードバランサレベルと URL ドメインレベルで作成されます。

ポリシーレベル	API フィールド	一致する HTTP レスポンスコード	エラーサービス	返されるエラーオブジェクト
URL ドメイン	`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/
```
URL マップ（web-map-http）を web-map-http.yaml という名前のファイルにエクスポートします。
```
gcloud beta compute url-maps export web-map-http --destination web-map-http.yaml
```

次の YAML 構成でハイライト表示されているように、web-map-http.yaml を編集してカスタムエラーレスポンスポリシーを追加します。この例では、カスタムエラーレスポンスポリシーはロードバランサレベル（urlMaps.defaultCustomErrorResponsePolicy）と URL ドメインレベル（pathMatchers[].defaultCustomErrorResponsePolicy）で構成されています。

エラーサービスは URL ドメインレベルで定義されていないため、URL ドメインレベルのエラーサービスは、デフォルトで上位レベル（つまりロードバランサレベル）で定義されたエラーサービスになります。

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 から最新の構成をインポートして、URL マップを更新します。
```
gcloud beta compute url-maps import web-map-http --source web-map-http.yaml
```
URL マップを更新したら、ロードバランサの IP アドレスへのトラフィックの送信が始まるまでしばらく待つ必要があります。

認証が必要な URL のリクエストをホストに送信します。
```
curl -I http://video.example.com/a-page-that-needs-authorization
```
video-obtain-authorization.html からのエラーコンテンツが提供され、HTTP 200 ステータスコードが返されます。

例 3: ドメイン、パス、エラーレスポンスコードごとにきめ細かいカスタムエラーレスポンスポリシーを構成する

この例では、URL ドメイン、URL パス、HTTP エラーレスポンスコードごとにエラーレスポンスをカスタマイズする方法を示します。

この例で説明するカスタムエラーレスポンス構成は次のことを前提としています。

次の図のように、ホストとパスベースのルーティングを使用して、外部アプリケーションロードバランサの URL マップを構成している。

バックエンドサービスの設定例（クリックして拡大）
カスタムエラーページを返すように、BUCKET_1 と BUCKET_2 という名前の 2 つのバックエンドバケットを構成している。

次の表に示すように、この例では 4 つのカスタムエラーレスポンスポリシーが構成されています。これらのポリシーは、次の優先順位で 3 つのレベルに作成されます。

URL パス（pathMatchers[].pathRules[].customErrorResponsePolicy）
URL ドメイン（pathMatchers[].defaultCustomErrorResponsePolicy）
ロードバランサ（urlMaps.defaultCustomErrorResponsePolicy）

ポリシーレベル	リクエスト URL	一致する HTTP レスポンスコード	エラーサービス	返されるエラーオブジェクト
URL パス	`example.net/video/hd/*`	404	`BUCKET-2`	`not-found-hd-videos-404.html`
URL パス	`example.net/video/sd/*`	404	`BUCKET-2`	`not-found-sd-videos-404.html`
URL ドメイン	`example.net/*`	4xx すべて	`BUCKET-1`	`example-net-4xx.html`
ロードバランサ	`Any`	4xx または 5xx すべて	`BUCKET-1`	`error-page-generic.html`

ロードバランサレベルのカスタムエラーレスポンスポリシーは、ポリシーがエラー条件に一致し、下位レベル（つまり、URL ドメインまたは URL パス）のエラーコードに一致するポリシーが定義されていない場合にのみ適用されます。同様に、URL ドメインレベルのカスタムエラーレスポンスポリシーは、ポリシーがエラー条件に一致し、下位レベルのエラーコードに一致するポリシーが定義されていない場合にのみ適用されます。この例では、URL www.example.net/video/hd へのリクエストに対して 404 レスポンスが返されると、ファイル not-found-hd-videos-404.html が返されます。ただし、URL www.example.net/video/ に対するリクエストで 404 レスポンスが返された場合は、ファイル example-net-4xx.html が返されます。

URL マップの 3 つのレベルにわたるカスタムエラーレスポンスポリシーを作成する手順は次のとおりです。

エラーオブジェクトを 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/

URL マップ（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

カスタムエラーレスポンスポリシーを追加する前の URL マップ（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

次の YAML 構成でハイライト表示されているように、video-org-url-map.yaml を編集してカスタムエラーレスポンスポリシーを追加します。

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

video-org-url-map.yaml から最新の構成をインポートして、URL マップを更新します。
```
gcloud beta compute url-maps import video-org-url-map --source video-org-url-map.yaml
```
URL マップを更新したら、ロードバランサの IP アドレスへのトラフィックの送信が始まるまでしばらく待つ必要があります。

存在しないページのリクエストを送信します。
```
curl -I http://example.net/a-page-that-does-not-exist
```
example-net-4xx.html のエラーコンテンツが配信されます。

同様に、URL ドメインと URL パスが異なる他の URL もテストします。

カスタム エラー レスポンスを構成する

例 1: すべてのホストに共通するすべての 4xx エラーのエラーページを構成する

例 2: 特定のホストの特定のエラーコードのエラーページを構成する

例 3: ドメイン、パス、エラー レスポンス コードごとにきめ細かいカスタム エラー レスポンス ポリシーを構成する

カスタムエラーレスポンスを構成する

例 1: すべてのホストに共通するすべての `4xx` エラーのエラーページを構成する

例 3: ドメイン、パス、エラーレスポンスコードごとにきめ細かいカスタムエラーレスポンスポリシーを構成する