原始伺服器修改的協助程式方法 - Amazon CloudFront
在 CloudFront Functions 和 Lambda@Edge 之間進行選擇updateRequestOrigin() 方法selectRequestOriginById() 方法createRequestOriginGroup() 方法

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

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

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

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

import cf from 'cloudfront';

如需詳細資訊，請參閱適用於 CloudFront Functions 的 JavaScript 執行期 2.0 功能。

注意

測試 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 分佈中的現有原始伺服器。

備註

  • 如果您要更新屬於原始伺服器群組的原始伺服器，則只會更新原始伺服器群組的主要原始伺服器。次要原始伺服器保持不變。來自修改原始伺服器且符合容錯移轉條件的任何回應碼都會觸發容錯移轉至次要原始伺服器。

  • 如果您要變更原始伺服器類型並啟用 OAC，請確定 中的原始伺服器類型originAccessControlConfig符合新的原始伺服器類型。

  • 您無法使用 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值。

region （啟用時需要）

Origin Shield AWS 區域 的 。指定對原始伺服器延遲最低的 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 秒，最長為 120 秒。如需詳細資訊，請參閱回應逾時 （僅限自訂和 VPC 原始伺服器）。

keepAliveTimeout （選用）

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

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"
});

selectRequestOriginById() 方法

使用 選取已在分佈中設定的不同原始伺服器，以selectRequestOriginById()更新現有的原始伺服器。此方法使用更新原始伺服器所定義的所有相同設定。

此方法僅接受已在執行函數時所用的相同分佈中定義的原始伺服器。原始伺服器由原始伺服器 ID 參考，這是您在設定原始伺服器時定義的原始伺服器名稱。

如果您的分佈中已設定 VPC 原始伺服器，您可以使用此方法將原始伺服器更新為 VPC 原始伺服器。如需詳細資訊，請參閱使用 VPC 原始伺服器限制存取。

請求

selectRequestOriginById(origin_id)

在上述範例中， origin_id 是指向執行 函數之 分佈中原始伺服器的原始伺服器名稱的字串。

範例 – 選取 Amazon S3 請求原始伺服器

下列範例amzn-s3-demo-bucket-in-us-east-1會從與分佈相關聯的原始伺服器清單中選擇名為 的原始伺服器，並將amzn-s3-demo-bucket-in-us-east-1原始伺服器的組態設定套用至請求。

cf.selectRequestOriginById("amzn-s3-demo-bucket-in-us-east-1");
範例 – 選取 Application Load Balancer 請求原始伺服器

下列範例myALB-prod會從與分佈相關聯的原始伺服器清單中選擇名為 的 Application Load Balancer 原始伺服器，並將 的組態設定套用至myALB-prod請求。

cf.selectRequestOriginById("myALB-prod");

createRequestOriginGroup() 方法

使用 createRequestOriginGroup()定義兩個原始伺服器，以在需要高可用性的情況下做為容錯移轉的原始伺服器群組。

原始伺服器群組包含兩個原始伺服器 （主要和次要），以及您指定的容錯移轉條件。您建立原始伺服器群組以支援 CloudFront 中的原始伺服器容錯移轉。當您使用此方法建立或更新原始伺服器群組時，您可以指定原始伺服器群組，而不是單一原始伺服器。CloudFront 將使用容錯移轉條件，從主要原始伺服器容錯移轉至次要原始伺服器。

如果您的分佈中已設定 VPC 原始伺服器，您可以使用此方法來使用 VPC 原始伺服器建立原始伺服器群組。如需詳細資訊，請參閱使用 VPC 原始伺服器限制存取。

請求

createRequestOriginGroup({origin_group_properties})

在上述範例中， origin_group_properties可以包含下列項目：

originIds （必要）

陣列origin_ids，其中 origin_id是指向執行 函數之分佈中原始伺服器原始伺服器的字串。您必須提供兩個原始伺服器做為陣列的一部分。清單中的第一個原始伺服器是主要原始伺服器，第二個則做為容錯移轉用途的第二個原始伺服器。

selectionCriteria （選用）

選取是要使用default原始伺服器容錯移轉條件，還是使用 media-quality-score 型容錯移轉邏輯。有效值如下：

  • default 根據 中指定的狀態碼， 會使用容錯移轉條件failoverCriteria。如果您未在 函數selectionCriteria中設定 ，default則會使用 。

  • media-quality-score 會在使用媒體感知路由功能時使用。

failoverCriteria （必要）

從主要原始伺服器傳回時，會觸發 CloudFront 容錯移轉至次要原始伺服器的狀態碼陣列。如果您覆寫現有的原始伺服器群組，此陣列會覆寫原始伺服器群組原始組態中設定的所有容錯移轉狀態碼。

當您使用 media-quality-score 時selectionCriteria，CloudFront 會根據媒體品質分數嘗試路由請求。如果選取的原始伺服器傳回此陣列中設定的錯誤碼，CloudFront 會容錯移轉至另一個原始伺服器。

範例 – 建立請求原始伺服器群組

下列範例會使用原始伺服器 IDs 為請求建立原始伺服器群組。這些原始伺服器 IDs 來自用於執行此函數之分佈的原始伺服器群組組態。

cf.createRequestOriginGroup({
    originIds: ["us-east-1-s3-origin", "us-west-2-s3-origin"],
    failoverCriteria: {
        statusCodes: [500, 502, 503, 504] 
    }
});