跨源資源共享 (CORS)

設定 設定範例

跨源資源共享 (CORS) 可讓用戶端網頁應用程式存取不同來源的資源。Cloud Storage 支援 CORS 規格，可讓您設定值區，與其他來源的指令碼安全共用資源。舉例來說，您可以使用 CORS 讓網頁應用程式 https://example-app.appspot.com 存取來源 https://example-data.storage.googleapis.com 的資源。

如要進一步瞭解 CORS 設定元件，請參閱「設定值區 CORS」。

CORS 的運作方式

如果想讓網站使用瀏覽器型要求，直接從 Cloud Storage bucket 擷取檔案、圖片或指令碼，請使用 CORS。

允許跨網域存取

根據預設，網路瀏覽器會強制執行同源政策這項安全措施。同源政策會防止某個網站上的指令碼與其他網域的資源互動。雖然這項功能可保護使用者免受惡意網站侵害，但也會封鎖合法要求。舉例來說，如果您的網頁應用程式 https://example-app.appspot.com 嘗試存取來源 https://example-data.storage.googleapis.com 的資源，瀏覽器預設會封鎖要求，因為網域不相符。

CORS 規格可讓伺服器向瀏覽器表示：「我信任這個特定網域，請允許要求。」

Cloud Storage 可讓您在 bucket 上設定 CORS 設定。設定完成後，Cloud Storage 會將特定 HTTP 標頭 (例如 Access-Control-Allow-Origin) 傳回瀏覽器，授權瀏覽器與網頁應用程式共用值區的資源。

要求類型

CORS 要求有兩種運作方式：簡單和預檢。簡單要求會直接進行，而預檢要求則會先傳送初步要求來取得權限。

簡單要求

瀏覽器向 Cloud Storage 發出簡易要求時，流程會如下進行：

1. 瀏覽器會在要求中加入 Origin 標頭。Origin 標頭包含要求共用 Cloud Storage bucket 資源的資源來源，例如 Origin:https://www.example-app.appspot.com。

2. Cloud Storage 會將要求的 HTTP 方法和 Origin 標頭值，與目標 bucket CORS 設定中的「Methods」和「Origins」資訊進行比對，確認是否有相符項目。如果有的話，Cloud Storage 會在回應中加入 Access-Control-Allow-Origin 標頭。Access-Control-Allow-Origin 標頭包含初始要求中 Origin 標頭的值。

3. 瀏覽器收到回應後，會檢查 Access-Control-Allow-Origin 值是否與原始要求中指定的網域相符。如果相符，要求就會成功。如果不相符，或回應中沒有 Access-Control-Allow-Origin 標頭，要求就會失敗。

預檢要求

如果符合下列任一情況，系統就會預檢要求：

• 要求使用 GET、HEAD 或 POST 以外的方法。
• 使用 POST 方法，且 Content-Type 不是 text/plain、application/x-www-form-urlencoded 或 multipart/form-data。
• 設定自訂標頭。例如 X-PINGOTHER。

預檢要求會先執行下列步驟。如果成功，則會按照與簡易步驟相同的程序繼續執行：

1. 瀏覽器會傳送 OPTIONS 要求，其中包含主要要求的 Requested Method 和 Requested Headers。

2. Cloud Storage 會傳回目標資源允許的 HTTP 方法和標頭值。如果預檢要求中的任何方法或標頭值不在目標資源允許的方法和標頭集合中，要求就會失敗，且不會傳送主要要求。

如要進一步瞭解 CORS 要求，請參閱 Fetch 規格。

Cloud Storage CORS 支援

Cloud Storage 可讓您在 bucket 層級設定 CORS。JSON API 和 XML API 端點處理 CORS 要求的方式不同，傳回的回應標頭也不同。瞭解這些行為，有助於有效設定值區：

• 無論值區設定為何，JSON API 端點一律允許 CORS 要求，並在 CORS 回應標頭中傳回預設值。

• XML API 端點只允許根據 bucket 設定的 CORS 要求，並在回應中傳回特定 CORS 標頭值。

• 已驗證的瀏覽器下載端點 storage.cloud.google.com 不允許 CORS 要求。請注意， Google Cloud 控制台會為每個物件的公開網址連結提供這個端點。

您可以透過下列任一個 XML API 要求網址，從 Cloud Storage 取得包含 CORS 標頭的回應：

storage.googleapis.com/BUCKET_NAME

BUCKET_NAME.storage.googleapis.com

如需瞭解 XML API 要求網址，請參閱要求端點。

CORS 設定的元件

使用 XML API 時，您在 bucket 的 CORS 設定中設定的值，會決定 Cloud Storage 在 HTTP 回應中傳回的 CORS 標頭。使用 JSON API 時，Cloud Storage 不會評估 bucket 的設定，而是傳回預設標頭值。

下表說明 CORS 設定中的欄位，以及 XML 和 JSON API 的回應行為。如要瞭解如何使用這些欄位，請參閱「CORS 設定範例」。

欄位^1	說明	XML API 回應行為	JSON API 回應行為
origin	指定要允許與這個 Cloud Storage bucket 進行跨來源資源共享的來源。例如 https://origin1.example.com。	如果瀏覽器要求中的來源與 CORS 設定中的來源相符，Cloud Storage 會將 Access-Control-Allow-Origin 傳回瀏覽器。如果沒有相符項目，Cloud Storage 就不會在回應中加入 Access-Control-Allow-Origin。您可以提供萬用字元值，授予所有來源的存取權：<Origin>*</Origin>。	Cloud Storage 會傳回 Access-Control-Allow-Origin 標頭，並設為要求的來源。
method	指定要允許跨來源資源共用的 HTTP 方法，以存取這個 Cloud Storage bucket。如果預檢要求成功，系統會在回應的 Access-Control-Allow-Methods 標頭中傳回這個值。 由於 OPTIONS 是瀏覽器用來啟動預檢要求的標準方法，因此您不應在 CORS 設定中指定 OPTIONS。	Cloud Storage 支援下列方法：DELETE、GET、HEAD、POST、PUT。 Cloud Storage 會根據值區的 CORS 設定，檢查瀏覽器在 Access-Control-Request-Methods 標頭中傳送的方法。如果沒有相符項目，Cloud Storage 會傳回 200 回應代碼，不含 CORS 回應標頭。	Cloud Storage 會針對下列方法傳回設為 Access-Control-Allow-Methods 的標頭：DELETE、GET、HEAD、PATCH、POST、PUT。
responseHeader	指定要允許哪些標頭與這個 Cloud Storage bucket 跨源共用資源。如果預檢要求成功，系統會在回應中透過 Access-Control-Allow-Headers 標頭傳回這個值。	針對預檢要求，Cloud Storage 會根據 bucket 的 CORS 設定，檢查瀏覽器在 Access-Control-Request-Headers 標頭中傳送的標頭。如果沒有相符項目，Cloud Storage 就不會傳回 CORS 回應標頭。	Cloud Storage 會傳回 Access-Control-Allow-Headers 標頭，其值與 Access-Control-Request-Headers 標頭指定的值相同。
maxAgeSeconds (選填)	指定瀏覽器在必須重複預檢要求之前，允許提出要求的秒數。這也稱為快取到期時間。系統會在預檢要求的回應中，透過 Access-Control-Max-Age 標頭傳回這個值。舉例來說，3600 會將快取到期時間設為 1 小時。	Cloud Storage 會傳回 Access-Control-Max-Age 標頭，並指定快取到期時間。如果省略這個欄位，Cloud Storage 會傳回預設值 3600。	Cloud Storage 會傳回 Access-Control-Max-Age 標頭，預設值為 3600。

¹「欄位」欄中記錄的名稱是 JSON API 專用。使用 XML API 設定 CORS 設定時，請使用 XML 專用格式。

指定多個來源、方法或標頭

如要瞭解如何在 CORS 設定中設定多個來源、方法或標頭，請參閱下列清單：

• 使用 JSON API 時，您可以使用以半形逗號分隔的陣列，指定多個來源、方法或標頭。例如 "method": ["GET", "PUT"]。

  注意： 使用 JSON API 設置 CORS 設定時，無論 CORS 設定中的 origin 欄位值為何，系統都會接受來自所有來源的 API 要求。

• 使用 XML API 時，您可以透過個別元素指定多個來源、方法或標頭。例如：

  <Methods>
    <Method>PUT</Method>
    <Method>GET</Method>
  </Methods>

• 如要允許來自任何來源的要求，請將來源設為萬用字元 *。例如 JSON API 中的 "origin": ["*"] 或 XML API 中的 <Origin>*</Origin>。雖然這個來源有助於測試設定，但在大多數情況下，您會想要限制要求來源，避免資源遭到濫用。

其他事項

下表說明使用憑證或存取控管標頭提出要求時的注意事項：

屬性或標頭	說明	XML API 回應行為	JSON API 回應行為
憑證	Cookie、授權標頭或 TLS 用戶端憑證。	Cloud Storage 絕不會傳回 Access-Control-Allow-Credentials 標頭。XML API 不支援 CORS 憑證。	如果是簡單要求，CORS 要求獲得核准後，Access-Control-Allow-Credentials 標頭會設為 true。 如果是預檢要求，當 Access-Control-Request-Method 為空白時，Cloud Storage 會將 Access-Control-Allow-Credentials 設為 true，並拒絕 404 - Not Found 的要求。
公開標頭	如果是預檢要求，Access-Control-Request-Headers 要求標頭會指出後續 CORS 要求可能包含哪些標頭。伺服器的回應會包含 Access-Control-Expose-Headers 回應標頭，向用戶端指出可公開哪些標頭。	如果是簡單要求，Access-Control-Expose-Headers 會列出 CORS 設定中回應標頭的值。	如果是簡單要求，Access-Control-Expose-Headers 會傳回 Access-Control-Request-Headers 中指定的值 (如果這些值屬於常見 HTTP 標頭清單)。

允許 bucket 存取外部資源

有時，您可能需要允許託管於 Cloud Storage 的指令碼，存取託管於 Cloud Storage 外部網站的靜態資源。在這個情境中，網站會提供 CORS 標頭，允許 storage.googleapis.com 上的內容存取。

最佳做法是為這項資料存取作業指定專屬 bucket。這種做法可避免網站不小心向所有 storage.googleapis.com 過度公開靜態資源。舉例來說，如果您想將名為 mybucket 的值區專用於資料存取，網站應提供 CORS 標頭 Access-Control-Allow-Origin: https://mybucket.storage.googleapis.com，而非 Access-Control-Allow-Origin: https://storage.googleapis.com。

用戶端 CORS 支援

大多數瀏覽器都是使用 XMLHttpRequest 物件來提出跨網域要求。 XMLHttpRequest 會負責插入正確的標頭，並處理 CORS 和伺服器之間的互動。您不需要新增任何程式碼，即可利用 Cloud Storage 值區提供的 CORS 支援服務。

後續步驟

• 瞭解如何為 bucket 啟用 CORS。
• 探索 CORS 設定範例，包括移除 bucket CORS 設定的範例。
• 瞭解如何排解 CORS 要求問題。