Lambda@Edge 事件結構說明頁面 - Amazon CloudFront
動態原始伺服器選擇請求事件回應事件

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

Lambda@Edge 事件結構說明頁面

下列主題說明觸發時 CloudFront 傳遞至 Lambda @Edge 函數的請求和回應事件物件。

動態原始伺服器選擇

您可以根據路徑和請求物件名稱 (例如 images/*.jpg)，使用快取行為中的路徑模式將請求路由傳送到原始伺服器。使用 Lambda@Edge，您也可以根據其他特性路由傳送請求到原始伺服器，例如請求標頭中的值。

此動態原始伺服器選擇在很多方面是非常有用的。例如，您可以將請求分佈到各個在不同地理區域的原始伺服器，以協助全域負載平衡。或者，您可以選擇性地路由傳送請求到服務特定函數之不同的原始伺服器：機器人處理、SEO 最佳化、驗證，以此類推。如需示範如何使用此功能的程式碼範例，請參閱以內容為基礎的動態原始伺服器選擇 - 範例。

在 CloudFront 原始要求事origin件中，事件結構中的物件會根據路徑模式，包含要求將路由到的來源相關資訊。您可以更新 origin 物件的值，將請求路由傳送到不同的原始伺服器。更新 origin 物件時，您不需要定義分佈中的原始伺服器。您也可以使用自訂原始伺服器物件來取代 Amazon S3 原始伺服器物件，反之亦然。不過，您只能為每個請求指定單一原始伺服器；也就是指定自訂原始伺服器或 Amazon S3 原始伺服器，但不能兩者同時指定。

請求事件

下列主題顯示 CloudFront 傳遞至 Lambda 函數以供檢視器和原始請求事件使用的物件結構。這些範例顯示不含任何主體的 GET 請求。在範例之後，會提供檢視器和原始伺服器請求事件中的所有可能欄位清單。

檢視者請求範例

下列範例顯示檢視器請求事件物件。

{
  "Records": [
    {
      "cf": {
        "config": {
          "distributionDomainName": "d111111abcdef8.cloudfront.net",
          "distributionId": "EDFDVBD6EXAMPLE",
          "eventType": "viewer-request",
          "requestId": "4TyzHTaYWb1GX1qTfsHhEqV6HUDd_BzoBZnwfnvQc_1oF26ClkoUSEQ=="
        },
        "request": {
          "clientIp": "203.0.113.178",
          "headers": {
            "host": [
              {
                "key": "Host",
                "value": "d111111abcdef8.cloudfront.net"
              }
            ],
            "user-agent": [
              {
                "key": "User-Agent",
                "value": "curl/7.66.0"
              }
            ],
            "accept": [
              {
                "key": "accept",
                "value": "*/*"
              }
            ]
          },
          "method": "GET",
          "querystring": "",
          "uri": "/"
        }
      }
    }
  ]
}

原始伺服器請求範例

下列範例顯示原始伺服器請求事件物件。

{
  "Records": [
    {
      "cf": {
        "config": {
          "distributionDomainName": "d111111abcdef8.cloudfront.net",
          "distributionId": "EDFDVBD6EXAMPLE",
          "eventType": "origin-request",
          "requestId": "4TyzHTaYWb1GX1qTfsHhEqV6HUDd_BzoBZnwfnvQc_1oF26ClkoUSEQ=="
        },
        "request": {
          "clientIp": "203.0.113.178",
          "headers": {
            "x-forwarded-for": [
              {
                "key": "X-Forwarded-For",
                "value": "203.0.113.178"
              }
            ],
            "user-agent": [
              {
                "key": "User-Agent",
                "value": "Amazon CloudFront"
              }
            ],
            "via": [
              {
                "key": "Via",
                "value": "2.0 2afae0d44e2540f472c0635ab62c232b.cloudfront.net (CloudFront)"
              }
            ],
            "host": [
              {
                "key": "Host",
                "value": "example.org"
              }
            ],
            "cache-control": [
              {
                "key": "Cache-Control",
                "value": "no-cache"
              }
            ]
          },
          "method": "GET",
          "origin": {
            "custom": {
              "customHeaders": {},
              "domainName": "example.org",
              "keepaliveTimeout": 5,
              "path": "",
              "port": 443,
              "protocol": "https",
              "readTimeout": 30,
              "sslProtocols": [
                "TLSv1",
                "TLSv1.1",
                "TLSv1.2"
              ]
            }
          },
          "querystring": "",
          "uri": "/"
        }
      }
    }
  ]
}

請求事件欄位

請求事件物件資料包含在兩個子物件中：config (Records.cf.config) 和 request (Records.cf.request)。下列清單說明每個子物件的欄位。

Config 物件中的欄位

下列清單說明 config 物件 (Records.cf.config) 中的欄位。

distributionDomainName (唯讀)

與請求相關的分佈網域名稱。

distributionID (唯讀)

與請求相關的分佈 ID。

eventType (唯讀)

與請求關聯的觸發條件類型：viewer-request 或 origin-request。

requestId (唯讀)

可唯一識別檢視者對象要求的加密字串。CloudFront該requestId值也會在 CloudFront存取記錄中顯示為x-edge-request-id。如需詳細資訊，請參閱 配置和使用標準日誌（訪問日誌） 及 標準日誌檔案欄位。

請求物件中的欄位

下列清單說明 request 物件 (Records.cf.request) 中的欄位。

clientIp (唯讀)

提出請求之檢視器的 IP 地址。如果檢視器使用 HTTP Proxy 或負載平衡器傳送請求，此值為代理或負載平衡器的 IP 地址。

標頭 (讀取/寫入)

請求中的標頭。注意下列事項：

  • 在 headers 物件的金鑰為標準 HTTP 標頭名稱的小寫版本。使用小寫金鑰提供您區分大小寫的標頭值存取權。

  • 每個標頭物件 (例如 headers["accept"] 或 headers["host"]) 都是鍵值組的陣列。針對已知的標頭，陣列會在請求中包含每個值的一組鍵值組。

  • key 包含在 HTTP 請求中出現的標頭的區分大小寫名稱，例如 Host、User-Agent、X-Forwarded-For 等。

  • value 包含在 HTTP 請求中出現的標頭值。

  • 當 Lambda 函數新增或修改請求標頭，而您不想要包含標頭 key 欄位時，Lambda@Edge 會使用您提供的標頭名稱來自動插入 key 標頭。無論您如何設定標頭名稱格式，各部分插入的標頭索引鍵名稱都會自動以大寫開頭，以連字號 (-) 分隔。

    例如，您可以在沒有 key 標頭的情況下，新增標頭如下：

    "user-agent": [
  {
    "value": "ExampleCustomUserAgent/1.X.0"
  }
]

    在此範例中，Lambda@Edge 會自動插入 "key": "User-Agent"。

如需標頭使用限制的詳細資訊，請參閱對邊緣函數的限制。

method (唯讀)

請求的 HTTP 方法。

querystring (讀取/寫入)

請求中的查詢字串 (如果有的話)。如果請求不包含查詢字串，事件物件仍會包含具有空白值的 querystring。如需查詢字串的詳細資訊，請參閱根據查詢字串參數快取內容。

uri (讀取/寫入)

請求物件的相對路徑。如果 Lambda 函數修改了 uri 值，請注意下列事項：

  • 全新的 uri 值必須以正斜線 (/) 做為開頭。

  • 當函數變更 uri 值時，這會變更檢視器請求的物件。

  • 當函數變更 uri 值時，並不會變更請求的快取行為或請求傳送的目標原始伺服器。

body (讀取/寫入)

HTTP 請求的主題。body 結構可包含下列欄位：

inputTruncated (唯讀)

布林值旗標，此旗標會指出 Lambda@Edge 是否截斷了本體。如需詳細資訊，請參閱 使用包含內文選項時的要求內文限制。

action (讀取/寫入)

您想要對本體採取的動作。action 的選項如下：

  • read-only: 此為預設值。從 Lambda 函式將回應傳回時，如果 action 為唯讀狀態，則 Lambda@Edge 會忽略對 encoding 或 data 所進行的任何變更。

  • replace: 如果想取代傳送到原始伺服器的本體，請指定此選項。

encoding (讀取/寫入)

本體的編碼。當 Lambda@Edge 向 Lambda 函式顯露內文時，會先將內文轉換為 base64-encoding。如果針對 action 選擇 replace 以取代本體，您可以選擇使用 base64 (預設) 或 text 編碼。如果您指定encoding為，base64但主體無效base64，則會 CloudFront傳回錯誤。

data (讀取/寫入)

請求本體的內容。

origin (讀取/寫入) (僅限原始伺服器事件)

傳送請求的目標原始伺服器。origin 結構必須確切地包含一個原始伺服器，這可以是自訂原始伺服器或 Amazon S3 原始伺服器。原始伺服器結構可包含下列欄位：

customHeaders (讀取/寫入) (自訂和 Amazon S3 原始伺服器)

您可以透過指定的標頭名稱與每個自訂標頭的值對，於請求中包含自訂標頭。您無法新增已列入不允許的標頭，且具有相同名稱的標頭也無法出現在 Records.cf.request.headers 中。請求標頭的相關注意事項也適用於自訂標頭。如需詳細資訊，請參閱 無法新增至原始請求的 CloudFront 自訂標頭 及 對邊緣函數的限制。

domainName (讀取/寫入) (自訂和 Amazon S3 原始伺服器)

原始伺服器的網域名稱。網域名稱不能空白。

  • 適用於自訂原始伺服器：指定 DNS 網域名稱，例如 www.example.com。網域名稱不能包含冒號 (:)，而且不能是 IP 地址。網域名稱長度上限為 253 個字元。

  • 對於 Amazon S3 原始伺服器 — 指定 Amazon S3 儲存貯體的 DNS 網域名稱，例如 awsexamplebucket.s3.eu-west-1.amazonaws.com. 名稱可以高達 128 個字元，而且必須全部小寫。

path (讀取/寫入) (自訂和 Amazon S3 原始伺服器)

目錄路徑位於需定位內容請求的原始伺服器中。路徑的開頭應為正斜線 (/)，但結尾不應為正斜線 (例如，結尾不應為 example-path/)。僅適用於自訂原始伺服器：路徑應為 URL 編碼，且其長度上限為 255 個字元。

keepaliveTimeout (讀取/寫入) (僅限自訂原始伺服器)

在收到回應的最後一個封包之後， CloudFront 應該嘗試維持與原始伺服器的連線時間 (以秒為單位)。此值必須是介於 1–60 (含) 的數字。

port (讀取/寫入) (僅限自訂原始伺服器)

CloudFront 應該在您的自定義原點連接到的端口。此連結埠必須是 80、443，或是介於 1024–65535 之間的數字。

protocol (讀取/寫入) (僅限自訂原始伺服器)

連線到原始伺服器時 CloudFront 應使用的連線通訊協定。此值可以為 http 或 https。

readTimeout (讀取/寫入) (僅限自訂原始伺服器)

將請求發送到您的來源後， CloudFront 應等待響應的時間（以秒為單位）。這也會指定在接收下一個封包之前，接收回 CloudFront 應封包之後應等待多久。此值必須是介於 4–60 (含) 的數字。

如果您的使用案例需要 60 秒以上，您可以要求更高的配額Response timeout per origin。如需詳細資訊，請參閱 分佈的一般配額。

sslProtocols (讀取/寫入) (僅限自訂原始伺服器)

與您的來源建立 HTTPS 連線時， CloudFront 可以使用的最低 SSL/TLS 通訊協定。可為以下任何一個值：TLSv1.2、TLSv1.1、TLSv1 或 SSLv3。

authMethod (讀取/寫入) (僅限 Amazon S3 原始伺服器)

如果您使用原始存取身分 (OAI)，請將此欄位設定為 origin-access-identity。如果您未使用 OAI，請將其設定為 none。如果您將 authMethod 設定為 origin-access-identity，有幾項要求如下：

  • 您必須指定 region (請參閱下列欄位)。

  • 當您將請求從某個 Amazon S3 原始伺服器變更為其他原始伺服器時，您必須使用相同的 OAI。

  • 當您將請求從某個自訂原始伺服器變更為 Amazon S3 原始伺服器時，您無法使用 OAI。

注意

此欄位不支援原始存取控制 (OAC)。

region (讀取/寫入) (僅限 Amazon S3 原始伺服器)

您的 Amazon S3 儲存貯體的 AWS 區域。只有在您將 authMethod 設定為 origin-access-identity 時才需要。

回應事件

下列主題顯示針對檢視器和來源回應事件 CloudFront 傳遞至 Lambda 函數的物件結構。在範例之後，會提供檢視器和原始伺服器回應事件中的所有可能欄位清單。

原始伺服器回應範例

下列範例顯示原始伺服器回應事件物件。

{
  "Records": [
    {
      "cf": {
        "config": {
          "distributionDomainName": "d111111abcdef8.cloudfront.net",
          "distributionId": "EDFDVBD6EXAMPLE",
          "eventType": "origin-response",
          "requestId": "4TyzHTaYWb1GX1qTfsHhEqV6HUDd_BzoBZnwfnvQc_1oF26ClkoUSEQ=="
        },
        "request": {
          "clientIp": "203.0.113.178",
          "headers": {
            "x-forwarded-for": [
              {
                "key": "X-Forwarded-For",
                "value": "203.0.113.178"
              }
            ],
            "user-agent": [
              {
                "key": "User-Agent",
                "value": "Amazon CloudFront"
              }
            ],
            "via": [
              {
                "key": "Via",
                "value": "2.0 8f22423015641505b8c857a37450d6c0.cloudfront.net (CloudFront)"
              }
            ],
            "host": [
              {
                "key": "Host",
                "value": "example.org"
              }
            ],
            "cache-control": [
              {
                "key": "Cache-Control",
                "value": "no-cache"
              }
            ]
          },
          "method": "GET",
          "origin": {
            "custom": {
              "customHeaders": {},
              "domainName": "example.org",
              "keepaliveTimeout": 5,
              "path": "",
              "port": 443,
              "protocol": "https",
              "readTimeout": 30,
              "sslProtocols": [
                "TLSv1",
                "TLSv1.1",
                "TLSv1.2"
              ]
            }
          },
          "querystring": "",
          "uri": "/"
        },
        "response": {
          "headers": {
            "access-control-allow-credentials": [
              {
                "key": "Access-Control-Allow-Credentials",
                "value": "true"
              }
            ],
            "access-control-allow-origin": [
              {
                "key": "Access-Control-Allow-Origin",
                "value": "*"
              }
            ],
            "date": [
              {
                "key": "Date",
                "value": "Mon, 13 Jan 2020 20:12:38 GMT"
              }
            ],
            "referrer-policy": [
              {
                "key": "Referrer-Policy",
                "value": "no-referrer-when-downgrade"
              }
            ],
            "server": [
              {
                "key": "Server",
                "value": "ExampleCustomOriginServer"
              }
            ],
            "x-content-type-options": [
              {
                "key": "X-Content-Type-Options",
                "value": "nosniff"
              }
            ],
            "x-frame-options": [
              {
                "key": "X-Frame-Options",
                "value": "DENY"
              }
            ],
            "x-xss-protection": [
              {
                "key": "X-XSS-Protection",
                "value": "1; mode=block"
              }
            ],
            "content-type": [
              {
                "key": "Content-Type",
                "value": "text/html; charset=utf-8"
              }
            ],
            "content-length": [
              {
                "key": "Content-Length",
                "value": "9593"
              }
            ]
          },
          "status": "200",
          "statusDescription": "OK"
        }
      }
    }
  ]
}

檢視者回應範例

下列範例顯示檢視器回應事件物件。

{
  "Records": [
    {
      "cf": {
        "config": {
          "distributionDomainName": "d111111abcdef8.cloudfront.net",
          "distributionId": "EDFDVBD6EXAMPLE",
          "eventType": "viewer-response",
          "requestId": "4TyzHTaYWb1GX1qTfsHhEqV6HUDd_BzoBZnwfnvQc_1oF26ClkoUSEQ=="
        },
        "request": {
          "clientIp": "203.0.113.178",
          "headers": {
            "host": [
              {
                "key": "Host",
                "value": "d111111abcdef8.cloudfront.net"
              }
            ],
            "user-agent": [
              {
                "key": "User-Agent",
                "value": "curl/7.66.0"
              }
            ],
            "accept": [
              {
                "key": "accept",
                "value": "*/*"
              }
            ]
          },
          "method": "GET",
          "querystring": "",
          "uri": "/"
        },
        "response": {
          "headers": {
            "access-control-allow-credentials": [
              {
                "key": "Access-Control-Allow-Credentials",
                "value": "true"
              }
            ],
            "access-control-allow-origin": [
              {
                "key": "Access-Control-Allow-Origin",
                "value": "*"
              }
            ],
            "date": [
              {
                "key": "Date",
                "value": "Mon, 13 Jan 2020 20:14:56 GMT"
              }
            ],
            "referrer-policy": [
              {
                "key": "Referrer-Policy",
                "value": "no-referrer-when-downgrade"
              }
            ],
            "server": [
              {
                "key": "Server",
                "value": "ExampleCustomOriginServer"
              }
            ],
            "x-content-type-options": [
              {
                "key": "X-Content-Type-Options",
                "value": "nosniff"
              }
            ],
            "x-frame-options": [
              {
                "key": "X-Frame-Options",
                "value": "DENY"
              }
            ],
            "x-xss-protection": [
              {
                "key": "X-XSS-Protection",
                "value": "1; mode=block"
              }
            ],
            "age": [
              {
                "key": "Age",
                "value": "2402"
              }
            ],
            "content-type": [
              {
                "key": "Content-Type",
                "value": "text/html; charset=utf-8"
              }
            ],
            "content-length": [
              {
                "key": "Content-Length",
                "value": "9593"
              }
            ]
          },
          "status": "200",
          "statusDescription": "OK"
        }
      }
    }
  ]
}

回應事件欄位

回應事件物件資料包含在三個子物件中：config (Records.cf.config)、request (Records.cf.request) 和 response (Records.cf.response)。如需請求物件中欄位的詳細資訊，請參閱請求物件中的欄位。下列清單說明 config 和 response 子物件中的欄位。

Config 物件中的欄位

下列清單說明 config 物件 (Records.cf.config) 中的欄位。

distributionDomainName (唯讀)

與回應關聯的分佈的網域名稱。

distributionID (唯讀)

與回應關聯的分佈 ID。

eventType (唯讀)

與回應關聯的觸發類型：origin-response 或 viewer-response。

requestId (唯讀)

加密字串，可唯一識別與此回應相關聯的檢視者對CloudFront 要求。該requestId值也會在 CloudFront 存取記錄中顯示為x-edge-request-id。如需詳細資訊，請參閱 配置和使用標準日誌（訪問日誌） 及 標準日誌檔案欄位。

回應物件中的欄位

下列清單說明 response 物件 (Records.cf.response) 中的欄位。如需如何使用 Lambda@Edge 函式產生 HTTP 請求的資訊，請參閱在要求觸發程序中產生 HTTP 回應。

headers (讀取/寫入)

回應中的標頭。注意下列事項：

  • 在 headers 物件的金鑰為標準 HTTP 標頭名稱的小寫版本。使用小寫金鑰提供您區分大小寫的標頭值存取權。

  • 每個標頭物件 (例如 headers["content-type"] 或 headers["content-length"]) 都是鍵值組的陣列。針對已知的標頭，陣列會在回應中包含每個值的一組鍵值組。

  • key包含標頭出現在 HTTP 回應中時區分大小寫的名稱；例如Content-TypeContent-Length、Cookie、等等。

  • value 包含在 HTTP 回應中出現的標頭值。

  • 當 Lambda 函數新增或修改回應標頭，而您不想要包含標頭 key 欄位時，Lambda@Edge 會使用您提供的標頭名稱來自動插入 key 標頭。無論您如何設定標頭名稱格式，各部分插入的標頭索引鍵名稱都會自動以大寫開頭，以連字號 (-) 分隔。

    例如，您可以在沒有 key 標頭的情況下，新增標頭如下：

    "content-type": [
  {
    "value": "text/html;charset=UTF-8"
  }
]

    在此範例中，Lambda@Edge 會自動插入 "key": "Content-Type"。

如需標頭使用限制的詳細資訊，請參閱對邊緣函數的限制。

status

回應的 HTTP 狀態碼。

statusDescription

回應的 HTTP 狀態說明。