原始伺服器修改的協助程式方法

如果您動態更新或變更 CloudFront Functions 程式碼內請求所使用的原始伺服器，則本節適用。您只能在檢視器請求 CloudFront Functions 時更新原始伺服器。CloudFront Functions 有一個模組，可提供協助程式方法來動態更新或變更原始伺服器。

若要使用此模組，請使用 JavaScript 執行期 2.0 建立 CloudFront 函數，並在函數程式碼的第一行中包含下列陳述式：

import cf from 'cloudfront';

如需詳細資訊，請參閱JavaScript 函數的執行階段 2.0 CloudFront 功能。

注意

測試 API 和測試主控台頁面不會測試是否已進行原始伺服器修改。不過，測試可確保函數程式碼執行時不會發生錯誤。

選擇 CloudFront Functions 和 Lambda@Edge

您可以使用 CloudFront Functions 或 Lambda@Edge 更新您的原始伺服器。

使用 CloudFront Functions 更新原始伺服器時，您可以使用檢視器請求事件觸發，這表示使用此函數時，此邏輯會在每次請求上執行。使用 Lambda@Edge 時，原始伺服器更新功能位於原始伺服器請求事件觸發程序上，這表示此邏輯只會在快取遺失時執行。

您的選擇主要取決於您的工作負載，以及分佈上 CloudFront Functions 和 Lambda@Edge 的任何現有用量。下列考量事項可協助您決定是否使用 CloudFront Functions 或 Lambda@Edge 更新您的原始伺服器。

CloudFront Functions 在下列情況中最有用：

• 當您的請求是動態的 （表示無法快取），且一律會前往原始伺服器。CloudFront Functions 提供更好的效能並降低整體成本。

• 當您已有現有的檢視器請求 CloudFront 函數會在每個請求上執行時，您可以將原始伺服器更新邏輯新增至現有的函數。

若要使用 CloudFront Functions 更新原始伺服器，請參閱下列主題中的協助程式方法。

Lambda@Edge 在下列情況中最有用：

• 當您有高度可快取的內容時，Lambda@Edge 可能更具成本效益，因為它只在快取遺漏時執行，而 CloudFront Functions 會在每次請求時執行。

• 當您已有現有的原始伺服器請求 Lambda@Edge 函數時，您可以將原始伺服器更新邏輯新增至現有的函數。

• 當您的原始伺服器更新邏輯需要從第三方資料來源擷取資料時，例如 Amazon DynamoDB 或 Amazon S3。

如需 Lambda@Edge 的詳細資訊，請參閱 使用 Lambda@Edge 在邊緣自訂。

updateRequestOrigin() 方法

使用 updateRequestOrigin()方法更新請求的原始伺服器設定。您可以使用此方法更新已在分佈中定義的原始伺服器現有的原始伺服器屬性，或定義請求的新原始伺服器。若要這麼做，請指定您要變更的屬性。

重要

您在 中未指定的任何設定updateRequestOrigin()都會繼承現有原始伺服器的組態中的相同設定。

updateRequestOrigin() 方法設定的原始伺服器可以是任何 HTTP 端點，不需要是 CloudFront 分佈中的現有原始伺服器。

備註

• 如果您要更新屬於原始群組的原始伺服器，則只會更新原始伺服器群組的主要原始伺服器。次要原始伺服器保持不變。

• 您無法使用 updateRequestOrigin()方法更新 VPC 原始伺服器。請求將會失敗。

請求

updateRequestOrigin({origin properties})

origin properties 可以包含下列項目：

domainName （選用）

原始伺服器的網域名稱。如果未提供，則會改用指派原始伺服器的網域名稱。

對於自訂原始伺服器

指定 DNS 網域名稱，例如 www.example.com。網域名稱不能包含冒號 (：)，也不能是 IP 地址。網域名稱長度上限為 253 個字元。

對於 S3 原始伺服器

指定 Amazon S3 儲存貯體的 DNS 網域名稱，例如 amzn-s3-demo-bucket.s3.eu-west-1.amazonaws.com。名稱可以高達 128 個字元，而且必須全部小寫。

originPath （選用）

目錄路徑位於需定位內容請求的原始伺服器中。路徑應以正斜線 (/) 開頭，但不應以正斜線結尾。例如，它不應以 結尾example-path/。如果未提供，則會使用指派原始伺服器的原始路徑。

對於自訂原始伺服器

路徑應為 URL 編碼，長度上限為 255 個字元。

customHeaders （選用）

您可以透過指定的標頭名稱與每個自訂標頭的值對，於請求中包含自訂標頭。格式與事件結構中請求和回應標頭的格式不同。使用下列鍵/值對語法：

{"key1": "value1", "key2": "value2", ...}

您無法新增不允許的標頭，而且傳入請求 中也不能有同名的標頭headers。函數程式碼中的標頭名稱必須為小寫。當 CloudFront Functions 將事件物件轉換回 HTTP 請求時，標頭名稱中每個單字的第一個字母會大寫，而單字會以連字號分隔。

例如，如果您函數程式碼新增名為 的標頭example-header-name，CloudFront 會在 HTTP 請求Example-Header-Name中將此標頭轉換為 。如需詳細資訊，請參閱 CloudFront 無法新增到原始伺服器請求的自訂標頭 和 對邊緣函數的限制。

如果未提供，則會使用指派原始伺服器中的任何自訂標頭。

connectionAttempts （選用）

CloudFront 會嘗試連線至原始伺服器的次數。最小值為 1，最大值為 3。如果未提供，則會使用來自指派原始伺服器的連線嘗試。

originShield （選用）

這會啟用或更新 CloudFront Origin Shield。使用 Origin Shield 有利於降低原始伺服器的負載。如需詳細資訊，請參閱使用 Amazon CloudFront Origin Shield。如果未提供，則會使用來自指派原始伺服器的 Origin Shield 設定。

已啟用 （必要）

啟用或停用 Origin Shield 的布林表達式。接受 true或 false值。

區域 （啟用時需要）

AWS 區域 適用於 Origin Shield 的 。指定對原始伺服器延遲最低的 AWS 區域 。使用區域碼，而非區域名稱。例如，使用 us-east-2指定美國東部 （俄亥俄） 區域。

當您啟用 CloudFront Origin Shield 時，您必須 AWS 區域 為其指定 。如需可用的 AWS 區域 清單，並協助選擇最適合您原始伺服器的區域，請參閱選擇 Origin Shield AWS 的區域。

originAccessControlConfig （選用）

此原始伺服器之原始存取控制 (OAC) 的唯一識別符。只有在原始伺服器支援 CloudFront OAC 時，例如 Amazon S3、Lambda 函數 URLs、MediaStore 和 MediaPackage V2，才會使用此值。如果未提供，則會使用指派原始伺服器的 OAC 設定。

這不支援舊版原始存取身分 (OAI)。如需詳細資訊，請參閱限制對原始伺服器的 AWS 存取。

已啟用 （必要）

啟用或停用 OAC 的布林表達式。接受 true或 false值。

signingBehavior （啟用時需要）

指定 CloudFront 會簽署哪些請求 (將身分驗證資訊新增至其中)。針對最常見的使用案例指定 always。如需詳細資訊，請參閱。

此欄位可以有下列其中一個值：

• always – CloudFront 會簽署所有原始伺服器請求，並覆寫來自檢視器請求的 Authorization 標頭 (如果存在)。

• never – CloudFront 不會簽署任何原始伺服器請求。此值會關閉原始伺服器的原始存取控制。

• no-override – 如果檢視器請求不包含 Authorization 標頭，則 CloudFront 會簽署原始伺服器請求。如果瀏覽者請求包含 Authorization 標頭，則 CloudFront 不會簽署原始伺服器請求，而是從瀏覽者請求中沿著 Authorization 標頭傳遞。

  警告

  若要從檢視器請求中傳遞Authorization標頭，您必須將其新增至所有快取行為的原始伺服器請求政策，這些快取行為皆使用與此原始伺服器存取控制相關聯的原始伺服器。如需詳細資訊，請參閱使用政策控制原始伺服器請求。

signingProtocol （啟用時需要）

OAC 的簽署通訊協定，決定 CloudFront 如何簽署 （驗證） 請求。唯一有效的值為 sigv4。

originType （啟用時需要）

此 OAC 的原始伺服器類型。有效值包括 s3、mediapackagev2、mediastore 與 lambda。

逾時 （選用）

您可以指定 CloudFront 應嘗試等待原始伺服器回應或傳送資料的逾時時間。如果未提供，則會使用指派原始伺服器的逾時設定。

readTimeout （選用）

逾時僅適用於自訂原始伺服器，不適用於 Amazon S3 原始伺服器。(S3 原始伺服器組態會忽略這些設定。) readTimeout 適用於下列兩個值：

• 在將請求轉送到自訂原始伺服器之後，CloudFront 等待回應的時間 (以秒為單位)。

• CloudFront 在收到來自原始伺服器的回應封包後，並在接收下一個封包前，等待的時間長短 (以秒為單位)

最小逾時為 1 秒，最大逾時為 60 秒。如需詳細資訊，請參閱回應逾時 (僅限自訂原始伺服器)。

keepAliveTimeout （選用）

逾時僅適用於自訂原始伺服器，不適用於 Amazon S3 原始伺服器。(S3 原始伺服器組態會忽略這些設定。) keepAliveTimeout指定 CloudFront 在收到回應的最後一個封包後，應嘗試維持原始伺服器的連線多久。最小逾時為 1 秒，最大逾時為 60 秒。如需詳細資訊，請參閱保持連線逾時 (僅限自訂原始伺服器)。

connectionTimeout （選用）

嘗試建立與原始伺服器的連線時，CloudFront 所等待的秒數。最小逾時為 1 秒，最大逾時為 10 秒。如需詳細資訊，請參閱連線逾時。。

customOriginConfig （選用）

使用 customOriginConfig指定非 Amazon S3 儲存貯體之原始伺服器的連線設定。有一個例外：如果 S3 儲存貯體設定為靜態網站託管，您可以指定這些設定。（其他類型的 S3 儲存貯體組態會忽略這些設定。) 如果customOriginConfig未提供 ，則會使用來自指派原始伺服器的設定。

連接埠 （必要）

CloudFront 用來連線至來源的 HTTP 連接埠。指定來源接聽使用的 HTTP 連接埠。

通訊協定 （必要）

指定 CloudFront 用來連線至來源的通訊協定 (HTTP 或 HTTPS)。有效值如下：

• http – CloudFront 一律使用 HTTP 連線至原始伺服器

• https – CloudFront 一律使用 HTTPS 連線至原始伺服器

sslProtocols （必要）

指定 CloudFront 透過 HTTPS 連線至原始伺服器時所使用的最低 SSL/TLS 通訊協定的清單。有效值包括 SSLv3、TLSv1、TLSv1.1 與 TLSv1.2。如需詳細資訊，請參閱最低來源 SSL 通訊協定。

範例 – 更新至 Amazon S3 請求原始伺服器

下列範例會將檢視器請求的原始伺服器變更為 S3 儲存貯體、啟用 OAC，以及重設傳送至原始伺服器的自訂標頭。

cf.updateRequestOrigin({
    "domainName" : "amzn-s3-demo-bucket-in-us-east-1.s3.us-east-1.amazonaws.com",
    "originAccessControlConfig": {
        "enabled": true,
        "signingBehavior": "always",
        "signingProtocol": "sigv4",
        "originType": "s3"
    },
    // Empty object resets any header configured on the assigned origin
    "customHeaders": {}
});

範例 – 更新 Application Load Balancer 請求原始伺服器

下列範例會將檢視器請求的原始伺服器變更為 Application Load Balancer 原始伺服器，並設定自訂標頭和逾時。

cf.updateRequestOrigin({
    "domainName" : "example-1234567890.us-east-1.elb.amazonaws.com",
    "timeouts": {
        "readTimeout": 30,
        "connectionTimeout": 5
    },
    "customHeaders": {
        "x-stage": "production",
        "x-region": "us-east-1"
    }
});

範例 – 在啟用 Origin Shield 的情況下更新原始伺服器

在下列範例中，分佈中的原始伺服器已啟用 Origin Shield。函數程式碼只會更新用於原始伺服器的網域名稱，並省略所有其他選用參數。在此情況下，Origin Shield 仍會與修改後的原始網域名稱搭配使用，因為 Origin Shield 參數未更新。

cf.updateRequestOrigin({
    "domainName" : "www.example.com"
});