跨來源資源分享 (CORS) - Amazon Simple Storage Service

本指南已不再更新。如需取得最新資訊和指示,請參閱全新 Amazon S3 使用者指南

跨來源資源分享 (CORS)

跨來源資源分享 (CORS) 會定義一種方式,讓載入單一個網域的用戶端 Web 應用程式,能與不同網域中的資源互動。透過 CORS 支援,您可以使用 Amazon S3 建立功能豐富的用戶端 Web 應用程式,而且也可以選擇性地允許跨來源存取您的 Amazon S3 資源。

本節提供 CORS 的概觀。各個副主題則說明使用 Amazon S3 主控台啟用 CORS 的方式,或是透過 Amazon S3 REST API 及 AWS 開發套件以程式設計的方式啟用。

跨來源資源分享:使用案例情境

以下為使用 CORS 的情境範例。

案例 1

假設您正在名為 website 的 Amazon S3 儲存貯體中託管網站,如 託管於 Amazon S3 的靜態網站 所述。您的使用者載入了網站端點:

http://website.s3-website.us-east-1.amazonaws.com

現在您想在存放於此儲存貯體中的網頁使用 JavaScript,以藉由儲存貯體的 Amazon S3 API 端點 (website.s3.us-east-1.amazonaws.com) 對相同的儲存貯體進行驗證 GET 及 PUT 要求。瀏覽器一般會封鎖 JavaScript 進行這類要求,但您可以透過 CORS 設定儲存貯體,明確地啟用來自 website.s3-website.us-east-1.amazonaws.com 的跨來源要求。

案例 2

假設您希望從 S3 儲存貯體託管一個 Web 字型。再者,瀏覽器需要 CORS 檢查(也稱為預先檢查),來載入 Web 字體。您可以設定裝載 Web 字體的儲存貯體,允許任何來源發出這些要求。

如何在儲存貯體上設定 CORS?

若要設定儲存貯體允許跨來源要求,您可以建立 CORS 組態。CORS 組態是具有規則的文件,這些規則可以識別允許存取您儲存貯體的來源、每個來源支援的操作 (HTTP 方法),以及其他操作特定資訊。最多可以將 100 條規則新增至組態。您可以將 CORS 組態以 cors 子資源的形式新增至儲存貯體。

如果您在 S3 主控台中設定 CORS,則必須使用 JSON 建立 CORS 組態。新的 S3 主控台只支援 JSON CORS 組態。

重要

在新的 S3 主控台中,CORS 組態必須為 JSON 格式。

除了使用 Amazon S3 網站端點存取網站之外,您也可以使用自己的網域 (例如 example1.com) 提供內容。如需使用自有網域的資訊,請參閱「使用透過 Route 53 登記的自訂網域配置靜態網站」。

範例 1

下列範例 cors 組態中有三條規則,以 CORSRule 元素的方式指定:

  • 第一項規則允許來自 http://www.example1.com 來源的跨來源 PUT、POST 及 DELETE 要求。該規則也允許透過 Access-Control-Request-Headers 標頭傳送之預檢 OPTIONS 要求中的所有標頭。為回應預檢 OPTIONS 要求,Amazon S3 會傳回所有要求的標頭。

  • 第二項規則允許與第一項規則相同的跨來源要求,但該規則適用於另一個來源 (http://www.example2.com)。

  • 第三項規則則允許來自所有來源的跨來源 GET 要求。* 萬用字元表示所有來源。

XML
<CORSConfiguration> <CORSRule> <AllowedOrigin>http://www.example1.com</AllowedOrigin> <AllowedMethod>PUT</AllowedMethod> <AllowedMethod>POST</AllowedMethod> <AllowedMethod>DELETE</AllowedMethod> <AllowedHeader>*</AllowedHeader> </CORSRule> <CORSRule> <AllowedOrigin>http://www.example2.com</AllowedOrigin> <AllowedMethod>PUT</AllowedMethod> <AllowedMethod>POST</AllowedMethod> <AllowedMethod>DELETE</AllowedMethod> <AllowedHeader>*</AllowedHeader> </CORSRule> <CORSRule> <AllowedOrigin>*</AllowedOrigin> <AllowedMethod>GET</AllowedMethod> </CORSRule> </CORSConfiguration>
JSON
[ { "AllowedHeaders": [ "*" ], "AllowedMethods": [ "PUT", "POST", "DELETE" ], "AllowedOrigins": [ "http://www.example1.com" ], "ExposeHeaders": [] }, { "AllowedHeaders": [ "*" ], "AllowedMethods": [ "PUT", "POST", "DELETE" ], "AllowedOrigins": [ "http://www.example2.com" ], "ExposeHeaders": [] }, { "AllowedHeaders": [], "AllowedMethods": [ "GET" ], "AllowedOrigins": [ "*" ], "ExposeHeaders": [] } ]

範例 2

CORS 組態也允許選用的組態參數,如下列 CORS 組態中所示。在此範例中,以下 CORS 組態會允許來自 http://www.example.com 來源的跨來源 PUT、POST 及 DELETE 要求。

XML
<CORSConfiguration> <CORSRule> <AllowedOrigin>http://www.example.com</AllowedOrigin> <AllowedMethod>PUT</AllowedMethod> <AllowedMethod>POST</AllowedMethod> <AllowedMethod>DELETE</AllowedMethod> <AllowedHeader>*</AllowedHeader> <MaxAgeSeconds>3000</MaxAgeSeconds> <ExposeHeader>x-amz-server-side-encryption</ExposeHeader> <ExposeHeader>x-amz-request-id</ExposeHeader> <ExposeHeader>x-amz-id-2</ExposeHeader> </CORSRule> </CORSConfiguration>
JSON
[ { "AllowedHeaders": [ "*" ], "AllowedMethods": [ "PUT", "POST", "DELETE" ], "AllowedOrigins": [ "http://www.example.com" ], "ExposeHeaders": [ "x-amz-server-side-encryption", "x-amz-request-id", "x-amz-id-2" ], "MaxAgeSeconds": 3000 } ]

先前組態中的 CORSRule 元素,包含下列選用元素:

  • MaxAgeSeconds — 指定時間秒數 (在此範例中為 3000),瀏覽器會為指定的資源對預檢 OPTIONS 要求快取 Amazon S3 回應的時間。藉由快取回應的方式,瀏覽器便不需要在原始要求重複時,將再次向 Amazon S3 傳送預檢要求。

  • ExposeHeader — 識別客戶能夠從其應用程式 (例如 JavaScript x-amz-server-side-encryption 物件) 存取的回應標頭 (在此範例中為 x-amz-request-idx-amz-id-2XMLHttpRequest)。

AllowedMethod 元素

在 CORS 組態中,您可以為 AllowedMethod 元素指定下列數值。

  • GET

  • PUT

  • POST

  • DELETE

  • HEAD

AllowedOrigin 元素

AllowedOrigin 元素中,可指定希望允許跨網域要求的來源,例如 http://www.example.com。原始字串只可包含一個 '*' 萬用字元,例如 http://*.example.com。您可以選擇性地指定 '*' 作為來源,允許所有來源傳送跨來源要求。您也可以指定 https 而只允許安全的來源。

AllowedHeader 元素

AllowedHeader 元素透過 Access-Control-Request-Headers 標頭,可指定在預檢要求中允許的標頭。在 Access-Control-Request-Headers 標頭中的每個標頭名稱,都必須符合規則中相對應的項目。Amazon S3 在要求的回應中只會傳送允許的標頭。如需可用於 Amazon S3 請求的標頭範例清單,請移至 Amazon 簡易儲存服務 API 參考指南中的常見請求標頭

規則中的每個 AllowedHeader 字串,最多只能有一個 '*' 萬用字元。例如,<AllowedHeader>x-amz-*</AllowedHeader> 會啟用所有 Amazon 專屬的標頭。

ExposeHeader 元素

每個 ExposeHeader 元素都會識別回應中您希望客戶能從其應用程式 (例如 JavaScript XMLHttpRequest 物件) 進行存取的標頭。如需常見的 Amazon S3 回應標頭清單,請移至 Amazon 簡易儲存服務 API 參考指南中的常用回應標頭

MaxAgeSeconds 元素

MaxAgeSeconds 元素會指定秒數,即您的瀏覽器為根據資源、HTTP 方法及來源所識別之預檢,快取要求的時間。

Amazon S3 如何評估儲存貯體上的 CORS 組態?

當 Amazon S3 從瀏覽器接收到預檢要求時,會評估儲存貯體的 CORS 組態,並使用第一個符合來源瀏覽器要求的 CORSRule 規則來啟用跨來源要求。符合規則必須滿足下列條件:

  • 要求的 Origin 標頭必須符合 AllowedOrigin 元素。

  • 要求的方法 (例如 GET 或 PUT) 或預檢 Access-Control-Request-Method 要求的 OPTIONS 標頭,必須是 AllowedMethod 元素中的其中之一。

  • 預檢要求上要求的 Access-Control-Request-Headers 標頭中所列出之每一個標頭,都必須符合 AllowedHeader 元素。

注意

在儲存貯體上啟用 CORS 時,仍繼續適用 ACL 及政策。