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

# Lambda@Edge 事件結構說明頁面
<a name="lambda-event-structure"></a>

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

**Topics**
+ [動態原始伺服器選擇](#lambda-event-content-based-routing)
+ [請求事件](#lambda-event-structure-request)
+ [回應事件](#lambda-event-structure-response)

## 動態原始伺服器選擇
<a name="lambda-event-content-based-routing"></a>

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

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

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

## 請求事件
<a name="lambda-event-structure-request"></a>

下列主題說明 CloudFront 針對[檢視器和原始伺服器請求事件](lambda-cloudfront-trigger-events.md)傳遞到 Lambda 函數的結構。這些範例顯示不含任何主體的 `GET` 請求。在範例之後，會提供檢視器和原始伺服器請求事件中的所有可能欄位清單。

**Topics**
+ [檢視者請求範例](#example-viewer-request)
+ [原始伺服器請求範例](#example-origin-request)
+ [請求事件欄位](#request-event-fields)

### 檢視者請求範例
<a name="example-viewer-request"></a>

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

```
{
  "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": "/"
        }
      }
    }
  ]
}
```

### 原始伺服器請求範例
<a name="example-origin-request"></a>

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

```
{
  "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,
              "responseCompletionTimeout": 30,
              "sslProtocols": [
                "TLSv1",
                "TLSv1.1",
                "TLSv1.2"
              ]
            }
          },
          "querystring": "",
          "uri": "/"
        }
      }
    }
  ]
}
```

### 請求事件欄位
<a name="request-event-fields"></a>

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

#### Config 物件中的欄位
<a name="request-event-fields-config"></a>

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

**`distributionDomainName` (唯讀)**  
與請求相關的分佈網域名稱。

**`distributionID` (唯讀)**  
與請求相關的分佈 ID。

**`eventType` (唯讀)**  
與請求關聯的觸發條件類型：`viewer-request` 或 `origin-request`。

**`requestId` (唯讀)**  
可獨特識別檢視器至 CloudFront 請求的加密字串。此 `requestId` 值也會在 CloudFront 存取記錄中顯示為 `x-edge-request-id`。如需詳細資訊，請參閱[存取日誌 （標準日誌）](AccessLogs.md)及[日誌檔案欄位](standard-logs-reference.md#BasicDistributionFileFormat)。

#### 請求物件中的欄位
<a name="request-event-fields-request"></a>

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

**`clientIp` (唯讀)**  
提出請求之檢視器的 IP 位址。如果檢視器使用 HTTP Proxy 或負載平衡器傳送請求，此值為代理或負載平衡器的 IP 位址。

** 標頭 (讀取/寫入)**  
請求中的標頭。注意下列事項：  
+ 在 `headers` 物件的金鑰為標準 HTTP 標頭名稱的小寫版本。使用小寫金鑰提供您區分大小寫的標頭值存取權。
+ 每個標頭物件 (例如 `headers["accept"]` 或 `headers["host"]`) 都是鍵值組的陣列。針對已知的標頭，陣列會在請求中包含每個值的一組鍵值組。
+ `key` 包含在 HTTP 請求中出現的標頭名稱 (區分大小寫)，例如 `Host`、`User-Agent`、`X-Forwarded-For`、`Cookie` 等。
+ `value` 包含在 HTTP 請求中出現的標頭值。
+ 當 Lambda 函數新增或修改請求標頭，而您不想要包含標頭 `key` 欄位時，Lambda@Edge 會使用您提供的標頭名稱來自動插入 `key` 標頭。無論您如何設定標頭名稱格式，各部分插入的標頭索引鍵名稱都會自動以大寫開頭，以連字號 (-) 分隔。

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

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

  在此範例中，Lambda@Edge 會自動插入 `"key": "User-Agent"`。
如需標頭使用限制的詳細資訊，請參閱[對邊緣函數的限制](edge-functions-restrictions.md)。

**`method` (唯讀)**  
請求的 HTTP 方法。

**`querystring` (讀取/寫入)**  
請求中的查詢字串 (如果有的話)。如果請求不包含查詢字串，事件物件仍會包含具有空白值的 `querystring`。如需查詢字串的詳細資訊，請參閱[根據查詢字串參數快取內容](QueryStringParameters.md)。

**`uri` (讀取/寫入)**  
請求物件的相對路徑。如果 Lambda 函數修改了 `uri` 值，請注意下列事項：  
+ 全新的 `uri` 值必須以正斜線 (/) 做為開頭。
+ 當函數變更 `uri` 值時，這會變更檢視器請求的物件。
+ 當函數變更 `uri` 值時，並*不會*變更請求的快取行為或請求傳送的目標原始伺服器。

**`body` (讀取/寫入)**  
HTTP 請求的主題。`body` 結構可包含下列欄位：    
**`inputTruncated` (唯讀)**  
布林值旗標，此旗標會指出 Lambda@Edge 是否截斷了本體。如需詳細資訊，請參閱[使用包含內文選項時的要求內文限制](lambda-at-edge-function-restrictions.md#lambda-at-edge-restrictions-request-body)。  
**`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 原始伺服器。  
根據您指定的原始伺服器類型 (自訂或 Amazon S3 原始伺服器)，您必須在請求中指定下列欄位：    
**`customHeaders` (讀取/寫入) (自訂和 Amazon S3 原始伺服器)**  
(選用) 您可以透過指定的標頭名稱與每個自訂標頭的值對，於請求中包含自訂標頭。您無法新增已列入不允許的標頭，且具有相同名稱的標頭也無法出現在 `Records.cf.request.headers` 中。[請求標頭的相關注意事項](#request-event-fields-request-headers)也適用於自訂標頭。如需詳細資訊，請參閱[CloudFront 無法新增到原始伺服器請求的自訂標頭](add-origin-custom-headers.md#add-origin-custom-headers-denylist)及[對邊緣函數的限制](edge-functions-restrictions.md)。  
**`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 到 120 之間的數字。  
**`port` (讀取/寫入) (僅限自訂原始伺服器)**  
CloudFront 應在您的自訂原始伺服器連線的連線埠。此連結埠必須是 80、443，或是介於 1024–65535 之間的數字。  
**`protocol` (讀取/寫入) (僅限自訂原始伺服器)**  
CloudFront 在連線到原始伺服器時應使用的連線通訊協定。此值可以為 `http` 或 `https`。  
**`readTimeout` (讀取/寫入) (自訂和 Amazon S3 原始伺服器)**  
CloudFront 在傳送請求給原始伺服器後應等候回應的時間長度 (以秒為單位)。這也會指定 CloudFront 在收到回應封包後與收到下一個封包前，應等候的時間長度。此值必須是介於 1 到 120 之間的數字。  
如果您需要更高的配額，請參閱[每個原始伺服器的回應逾時](cloudfront-limits.md#limits-web-distributions)。  
**`responseCompletionTimeout` (讀取/寫入) (自訂和 Amazon S3 原始伺服器)**  
從 CloudFront 到原始伺服器的請求可以保持開啟並等待回應的時間 (以秒為單位)。如果此時未從原始伺服器收到完整回應，CloudFront 會結束連線。  
`responseCompletionTimeout` 值必須大於或等於 `readTimeout` 的值。如果您將此值設定為 0，則會移除您設定的任何先前值，並返回預設值。您也可以從事件請求中刪除 `responseCompletionTimeout` 欄位來完成此操作。  
**`sslProtocols` (讀取/寫入) (僅限自訂原始伺服器)**  
當在您原始伺服器建立 HTTPS 連線時，CloudFront 可以使用的最低 SSL/TLS 通訊協定。可為以下任何一個值：`TLSv1.2`、`TLSv1.1`、`TLSv1` 或 `SSLv3`。  
**`authMethod` (讀取/寫入) (僅限 Amazon S3 原始伺服器)**  
如果您使用[原始存取身分 (OAI)](private-content-restricting-access-to-s3.md#private-content-restricting-access-to-s3-oai)，請將此欄位設定為 `origin-access-identity`。如果您未使用 OAI，請將其設定為 `none`。如果您將 `authMethod` 設定為 `origin-access-identity`，有幾項要求如下：  
+ 您必須指定 `region` (請參閱下列欄位)。
+ 當您將請求從某個 Amazon S3 原始伺服器變更為其他原始伺服器時，您必須使用相同的 OAI。
+ 當您將請求從某個自訂原始伺服器變更為 Amazon S3 原始伺服器時，您無法使用 OAI。
此欄位不支援[原始存取控制 (OAC)](private-content-restricting-access-to-s3.md)。  
**`region` (讀取/寫入) (僅限 Amazon S3 原始伺服器)**  
Amazon S3 儲存貯體 AWS 的區域。只有在您將 `authMethod` 設定為 `origin-access-identity` 時才需要。

## 回應事件
<a name="lambda-event-structure-response"></a>

下列主題說明 CloudFront 針對[檢視器和原始伺服器回應事件](lambda-cloudfront-trigger-events.md)傳遞到 Lambda 函數的結構。在範例之後，會提供檢視器和原始伺服器回應事件中的所有可能欄位清單。

**Topics**
+ [原始伺服器回應範例](#lambda-event-structure-response-origin)
+ [檢視者回應範例](#lambda-event-structure-response-viewer)
+ [回應事件欄位](#response-event-fields)

### 原始伺服器回應範例
<a name="lambda-event-structure-response-origin"></a>

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

```
{
  "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,
              "responseCompletionTimeout": 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"
        }
      }
    }
  ]
}
```

### 檢視者回應範例
<a name="lambda-event-structure-response-viewer"></a>

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

```
{
  "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"
        }
      }
    }
  ]
}
```

### 回應事件欄位
<a name="response-event-fields"></a>

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

#### Config 物件中的欄位
<a name="response-event-fields-config"></a>

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

**`distributionDomainName` (唯讀)**  
與回應關聯的分佈的網域名稱。

**`distributionID` (唯讀)**  
與回應關聯的分佈 ID。

**`eventType` (唯讀)**  
與回應關聯的觸發類型：`origin-response` 或 `viewer-response`。

**`requestId` (唯讀)**  
可獨特識別與此回應相關聯之檢視器至 CloudFront 請求的加密字串。此 `requestId` 值也會在 CloudFront 存取記錄中顯示為 `x-edge-request-id`。如需詳細資訊，請參閱[存取日誌 （標準日誌）](AccessLogs.md)及[日誌檔案欄位](standard-logs-reference.md#BasicDistributionFileFormat)。

#### 回應物件中的欄位
<a name="response-event-fields-response"></a>

下列清單說明 `response` 物件 (`Records.cf.response`) 中的欄位。如需如何使用 Lambda@Edge 函式產生 HTTP 請求的資訊，請參閱[在請求觸發條件中產生 HTTP 回應](lambda-generating-http-responses.md#lambda-generating-http-responses-in-requests)。

**`headers` (讀取/寫入)**  
回應中的標頭。注意下列事項：  
+ 在 `headers` 物件的金鑰為標準 HTTP 標頭名稱的小寫版本。使用小寫金鑰提供您區分大小寫的標頭值存取權。
+ 每個標頭物件 (例如 `headers["content-type"]` 或 `headers["content-length"]`) 都是鍵值組的陣列。針對已知的標頭，陣列會在回應中包含每個值的一組鍵值組。
+ `key` 包含在 HTTP 回應中出現的標頭名稱 (區分大小寫)，例如 `Content-Type`、`Content-Length`、`Cookie` 等。
+ `value` 包含在 HTTP 回應中出現的標頭值。
+ 當 Lambda 函數新增或修改回應標頭，而您不想要包含標頭 `key` 欄位時，Lambda@Edge 會使用您提供的標頭名稱來自動插入 `key` 標頭。無論您如何設定標頭名稱格式，各部分插入的標頭索引鍵名稱都會自動以大寫開頭，以連字號 (-) 分隔。

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

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

  在此範例中，Lambda@Edge 會自動插入 `"key": "Content-Type"`。
如需標頭使用限制的詳細資訊，請參閱[對邊緣函數的限制](edge-functions-restrictions.md)。

**`status`**  
回應的 HTTP 狀態碼。

**`statusDescription`**  
回應的 HTTP 狀態說明。