Lambda@Edge 事件結構說明頁面

下列主題描述觸發 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 (唯讀): 唯一識別 viewer-to-CloudFront請求的加密字串。此requestId值也會在存取日誌中 CloudFront顯示為 x-edge-request-id。如需詳細資訊，請參閱配置和使用標準日誌（訪問日誌）和標準日誌檔案欄位。

請求物件中的欄位

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

clientIp (唯讀)

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

標頭 (讀取/寫入)

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

headers 物件中的金鑰是標準HTTP標頭名稱的小寫版本。使用小寫金鑰提供您區分大小寫的標頭值存取權。
每個標頭物件 (例如 headers["accept"] 或 headers["host"]) 都是鍵值組的陣列。針對已知的標頭，陣列會在請求中包含每個值的一組鍵值組。
key 包含與HTTP請求中顯示的標頭區分大小寫的名稱；例如、X-Forwarded-For、 Host User-Agent等。
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。如果您選擇 replace action取代內文，您可以選擇使用 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網域名稱，例如 amzn-s3-demo-bucket.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 (唯讀): 唯一識別與此回應相關聯之viewer-to-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與回應中顯示的標頭區分大小寫的名稱；例如、Cookie、 Content-Type Content-Length等。
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的狀態描述。

您的瀏覽器已停用或無法使用 Javascript。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

刪除函數和複本

處理請求和回應