CloudFront Functions 事件結構

CloudFront Functions 在運行該函數時將 event 物件作為輸入傳遞給您的函數程式碼。測試函數時，建立 event 物件並將其傳遞給函數。建立用於測試函數的 event 物件時，您可以省略 distributionDomainName 物件中的 distributionId、requestId 和 context 欄位。此外，請確保標頭名稱為小寫，CloudFront Functions 在生產期間傳遞給函數的 event 物件中也會始終採用此形式。

以下是此事件物件結構的概觀。

{
    "version": "1.0",
    "context": {
        <context object>
    },
    "viewer": {
        <viewer object>
    },
    "request": {
        <request object>
    },
    "response": {
        <response object>
    }
}

如需詳細資訊，請參閱下列主題：

版本欄位

version 欄位包含指定 CloudFront Functions 事件物件版本的字串。目前版本是 1.0。

內容物件

context 物件包含有關事件的關聯式資訊。它包括以下欄位：

檢視者物件

viewer 物件包含一個 ip 欄位，其值是傳送請求的檢視者 (用戶端) 的 IP 地址。如果檢視者的請求來自 HTTP 代理或負載平衡器，此值為代理或負載平衡器的 IP 地址。

請求物件

request 物件包含檢視者到 CloudFront HTTP 請求的表示。在傳遞給函數的 event 物件中，request 物件代表 CloudFront 從檢視者接收的實際請求。

如果您的函數程式碼將 request 物件返回到 CloudFront，其必須使用相同的結構。

request 物件包含下列欄位：

如需有關查詢字串、標頭和 Cookie 結構的詳細資訊，請參閱 查詢字串、標頭和 Cookie 的結構。

如需範例 event 物件，請參閱 範例事件物件。

回應物件

response 物件包含 CloudFront 到檢視者的 HTTP 回應的表示。在傳遞給函數的 event 物件中，response 物件代表 CloudFront 對檢視者請求的實際回應。

如果您的函數程式碼返回 response 物件，其必須使用相同的結構。

response 物件包含下列欄位：

如需有關已修改狀態碼和本文內容的更多資訊，請參閱 狀態碼和本文。

如需有關標頭和 Cookie 結構的詳細資訊，請參閱 查詢字串、標頭和 Cookie 的結構。

如需範例 response 物件，請參閱 範例回應物件。

狀態碼和本文

透過 CloudFront Functions，您可以更新檢視者回應本文或將其移除。在評估來自 CloudFront 快取或原始伺服器回應的各個層面後，更新檢視器回應的一些常見案例包括：

在您使用 HTTP 回應時，CloudFront Functions 將無法存取回應本文。您可以透過將本文內容設定為所需的值來進行替換，或設定為空值來移除本文。如果您不更新函數中的本文欄位，CloudFront 快取或原始伺服器回傳的原始本文會傳回給檢視器。

如果您的 CloudFront Function 設定為傳回 400 或更高的 HTTP 錯誤，您的檢視者將不會看到您為相同狀態碼指定的自訂錯誤頁面。

查詢字串、標頭和 Cookie 的結構

查詢字串、標頭和 Cookie 共用相同的結構。查詢字串可能會出現在請求中。標頭會出現在請求和回應中。Cookie 會出現在請求和回應中。

每個查詢字串、標頭或 Cookie 都是父系 querystring、headers 或 cookies 物件中的唯一欄位。欄位名稱是查詢字串、標頭或 Cookie 的名稱。每個欄位都包含具有查詢字串、標頭或 Cookie 值的 value 屬性。

查詢字串值或查詢字串物件

除了查詢字串物件之外，函數還可以傳回查詢字串值。查詢字串值可用來依任意自訂順序排列查詢字串參數。

var request = event.request; 
request.querystring = 'ID=42&Exp=1619740800&TTL=1440&NoValue=&querymv=val1&querymv=val2,val3';

標頭的特殊考量

僅針對標頭，標頭名稱會在事件物件中轉換為小寫，而在函數程式碼新增標頭名稱時，標頭名稱則必須是小寫。當 CloudFront Functions 將事件物件轉換回 HTTP 請求或回應時，標頭名稱中每個單字的第一個字母會大寫。單字以連字號分隔 (-)。例如，如果函數程式碼新增名為 example-header-name 的標題，CloudFront 會將其轉換為 HTTP 請求或回應中的 Example-Header-Name。

Host: video.example.com

"headers": {
    "host": {
        "value": "video.example.com"
    }
}

var request = event.request;
var host = request.headers.host.value;

var request = event.request;
request.headers['x-custom-header'] = {value: 'example value'};

重複的查詢字串、標頭和 Cookie (multiValue 陣列)

HTTP 請求或回應可以包含多個具有相同名稱的查詢字串、標頭或 Cookie。在此情況下，重複的查詢字串、標頭或 Cookie 會折疊成 request 或 response 物件中的一個欄位，但此欄位包含一個名為 multiValue 的額外屬性。multiValue 屬性包含一個陣列，其中帶有每個重複查詢字串、標頭或 Cookie 的值。

Accept: application/json
Accept: application/xml
Accept: text/html

"headers": {
    "accept": {
        "value": "application/json",
        "multiValue": [
            {
                "value": "application/json"
            },
            {
                "value": "application/xml"
            },
            {
                "value": "text/html"
            }
        ]
    }
}

如果您的函數程式碼修改具有 multiValue 陣列的查詢字串、標頭或 Cookie，CloudFront Functions 會使用下列規則來套用變更：

只有當 HTTP 請求或回應包含具有相同名稱的重複查詢字串、標頭或 Cookie 時，才會使用 multiValue 屬性，如上述範例所示。但是，如果單一查詢字串、標頭或 Cookie 中有多個值，則不會使用該 multiValue 屬性。

Accept: application/json, application/xml, text/html

"headers": {
    "accept": {
        "value": "application/json, application/xml, text/html"
    }
}

Cookie 屬性

在 HTTP 回應的 Set-Cookie 標頭中，標頭包含 Cookie 的名稱/值對，以及選用的一組屬性 (以分號分隔)。

Set-Cookie: cookie1=val1; Secure; Path=/; Domain=example.com; Expires=Wed, 05 Apr 2021 07:28:00 GMT

"cookie1": {
    "value": "val1",
    "attributes": "Secure; Path=/; Domain=example.com; Expires=Wed, 05 Apr 2021 07:28:00 GMT"
}

範例回應物件

以下範例顯示一個本文已被檢視器回應函數替換的 response 物件 (檢視器回應函數的輸出)。

{
  "response": {
    "statusCode": 200,
    "statusDescription": "OK",
    "headers": {
      "date": {
        "value": "Mon, 04 Apr 2021 18:57:56 GMT"
      },
      "server": {
        "value": "gunicorn/19.9.0"
      },
      "access-control-allow-origin": {
        "value": "*"
      },
      "access-control-allow-credentials": {
        "value": "true"
      },
      "content-type": {
        "value": "text/html"
      },
      "content-length": {
        "value": "86"
      }
    },
    "cookies": {
      "ID": {
        "value": "id1234",
        "attributes": "Expires=Wed, 05 Apr 2021 07:28:00 GMT"
      },
      "Cookie1": {
        "value": "val1",
        "attributes": "Secure; Path=/; Domain=example.com; Expires=Wed, 05 Apr 2021 07:28:00 GMT",
        "multiValue": [
          {
            "value": "val1",
            "attributes": "Secure; Path=/; Domain=example.com; Expires=Wed, 05 Apr 2021 07:28:00 GMT"
          },
          {
            "value": "val2",
            "attributes": "Path=/cat; Domain=example.com; Expires=Wed, 10 Jan 2021 07:28:00 GMT"
          }
        ]
      }
    },
    
    // Adding the body field is optional and it will not be present in the response object
    // unless you specify it in your function.
    // Your function does not have access to the original body returned by the CloudFront
    // cache or origin.
    // If you don't specify the body field in your viewer response function, the original
    // body returned by the CloudFront cache or origin is returned to viewer.

     "body": {
      "encoding": "text",
      "data": "<!DOCTYPE html><html><body><p>Here is your custom content.</p></body></html>"
    }
  }
}

範例事件物件

以下範例顯示完整的 event 物件。這是標準分佈的範例調用，而不是多租用戶分佈。對於多租戶分佈，使用 endpoint 欄位，而不是 distributionDomainName 的值endpoint是與事件相關聯之連線群組的 CloudFront 網域名稱 （例如 d111111abcdef8.cloudfront.net)。

{
    "version": "1.0",
    "context": {
        "distributionDomainName": "d111111abcdef8.cloudfront.net",
        "distributionId": "EDFDVBD6EXAMPLE",
        "eventType": "viewer-response",
        "requestId": "EXAMPLEntjQpEXAMPLE_SG5Z-EXAMPLEPmPfEXAMPLEu3EqEXAMPLE=="
    },
    "viewer": {"ip": "198.51.100.11"},
    "request": {
        "method": "GET",
        "uri": "/media/index.mpd",
        "querystring": {
            "ID": {"value": "42"},
            "Exp": {"value": "1619740800"},
            "TTL": {"value": "1440"},
            "NoValue": {"value": ""},
            "querymv": {
                "value": "val1",
                "multiValue": [
                    {"value": "val1"},
                    {"value": "val2,val3"}
                ]
            }
        },
        "headers": {
            "host": {"value": "video.example.com"},
            "user-agent": {"value": "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:83.0) Gecko/20100101 Firefox/83.0"},
            "accept": {
                "value": "application/json",
                "multiValue": [
                    {"value": "application/json"},
                    {"value": "application/xml"},
                    {"value": "text/html"}
                ]
            },
            "accept-language": {"value": "en-GB,en;q=0.5"},
            "accept-encoding": {"value": "gzip, deflate, br"},
            "origin": {"value": "https://website.example.com"},
            "referer": {"value": "https://website.example.com/videos/12345678?action=play"},
            "cloudfront-viewer-country": {"value": "GB"}
        },
        "cookies": {
            "Cookie1": {"value": "value1"},
            "Cookie2": {"value": "value2"},
            "cookie_consent": {"value": "true"},
            "cookiemv": {
                "value": "value3",
                "multiValue": [
                    {"value": "value3"},
                    {"value": "value4"}
                ]
            }
        }
    },
    "response": {
        "statusCode": 200,
        "statusDescription": "OK",
        "headers": {
            "date": {"value": "Mon, 04 Apr 2021 18:57:56 GMT"},
            "server": {"value": "gunicorn/19.9.0"},
            "access-control-allow-origin": {"value": "*"},
            "access-control-allow-credentials": {"value": "true"},
            "content-type": {"value": "application/json"},
            "content-length": {"value": "701"}
        },
        "cookies": {
            "ID": {
                "value": "id1234",
                "attributes": "Expires=Wed, 05 Apr 2021 07:28:00 GMT"
            },
            "Cookie1": {
                "value": "val1",
                "attributes": "Secure; Path=/; Domain=example.com; Expires=Wed, 05 Apr 2021 07:28:00 GMT",
                "multiValue": [
                    {
                        "value": "val1",
                        "attributes": "Secure; Path=/; Domain=example.com; Expires=Wed, 05 Apr 2021 07:28:00 GMT"
                    },
                    {
                        "value": "val2",
                        "attributes": "Path=/cat; Domain=example.com; Expires=Wed, 10 Jan 2021 07:28:00 GMT"
                    }
                ]
            }
        }
    }
}