在 CloudFront Functions 和 Lambda@Edge 之間進行選擇 updateRequestOrigin() 方法 selectRequestOriginById() 方法 createRequestOriginGroup() 方法

原始伺服器修改的 Helper 方法

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

若要使用此模組，請使用 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 更新原始伺服器，請參閱下列主題中的 helper 方法。

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 設定。

enabled (必要)

啟用或停用 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 函數 URL、MediaStore 和 MediaPackage V2。如果未提供，則會使用來自指派原始伺服器的 OAC 設定。

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

enabled (必要)

啟用或停用 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。

timeout (選用)

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

注意

除非另行指定，否則這些逾時支援自訂原始伺服器和 Amazon S3 原始伺服器。

readTimeout (選用)

readTimeout 適用於下列兩個值：

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

最短的逾時時間是 1 秒，最長是 120 秒。如需更多詳細資訊，請參閱回應逾時。

responseCompletionTimeout (選用)

從 CloudFront 到原始伺服器的請求可以保持開啟並等待回應的時間 (以秒為單位)。如果此時未從原始伺服器收到完整回應，CloudFront 會結束連線。

responseCompletionTimeout 值必須大於或等於 readTimeout 的值。如需更多詳細資訊，請參閱回應完成逾時。

keepAliveTimeout (選用)

此逾時僅適用於自訂原始伺服器，不適用於 Amazon S3 原始伺服器。(S3 原始伺服器組態會忽略這些設定。)

keepAliveTimeout 指定 CloudFront 在收到上次封包的回應後維持與原始伺服器的連線所需的時間長度。最短的逾時時間是 1 秒，最長是 120 秒。如需更多詳細資訊，請參閱保持連線逾時 (僅限自訂與 VPC 原始伺服器)。

connectionTimeout (選用)

嘗試建立與原始伺服器的連線時，CloudFront 所等待的秒數。最短的逾時時間是 1 秒，最長是 10 秒。如需更多詳細資訊，請參閱連線逾時。。

customOriginConfig (選用)

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

port (必要)。

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

protocol (必要)

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

http — CloudFront 一律使用 HTTP 來連線至原始伺服器
https — CloudFront 一律使用 HTTPS 來連線至原始伺服器

sslProtocols (必要)

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

ipAddressType (選用)

指定 CloudFront 用來連線至原始伺服器的 IP 位址類型。有效值包括 ipv4、ipv6 與 dualstack。只有在同時變更 domainName 屬性時，才支援變更 ipAddressType。

範例 – 更新至 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 會容錯移轉至另一個原始伺服器。

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

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


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

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

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

文件慣用形式

鍵值存放區的協助程式方法

CloudFront SaaS Manager 屬性的 helper 方法