跨源資源共享 (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 可讓您在值區中設定 CORS。設定完成後，Cloud Storage 會將特定 HTTP 標頭 (例如 Access-Control-Allow-Origin) 傳回瀏覽器，授權瀏覽器與您的網路應用程式共用值區的資源。

要求類型

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

簡單要求

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

瀏覽器會將 Origin 標頭新增至要求。Origin 標頭包含尋求共用 Cloud Storage 值區資源的資源來源，例如 Origin:https://www.example-app.appspot.com。
Cloud Storage 會將要求的 HTTP 方法和 Origin 標頭值與目標值區 CORS 設定中的方法和來源資訊進行比較，以查看其是否相符。如果相符，Cloud Storage 就會在回應中加入 Access-Control-Allow-Origin 標頭。Access-Control-Allow-Origin 標頭包含來自初始要求的 Origin 標頭值。
瀏覽器收到回應並檢查 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。

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

瀏覽器傳送 OPTIONS 要求，其中包含主要要求的 Requested Method 和 Requested Headers。
Cloud Storage 會以目標資源允許的 HTTP 方法和標頭值回應。如果預檢要求的任何方法或標頭值並非目標資源允許的方法和標頭，則要求會失敗，系統也不會傳送主要要求。

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

Cloud Storage CORS 支援

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

無論值區設定為何，JSON API 端點一律允許 CORS 要求，並在 CORS 回應標頭中傳回預設值。
XML API 端點只會根據值區設定允許 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 時，您在值區的 CORS 設定中設定的值，會決定 Cloud Storage 在 HTTP 回應中傳回的 CORS 標頭。使用 JSON API 時，Cloud Storage 不會評估值區的設定，而是傳回預設標頭值。

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

欄位¹	說明	XML API 回應行為	JSON API 回應行為
`origin`	指定要允許與這個 Cloud Storage 值區進行跨源資源共享的來源。例如 `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 值區。如果預檢要求成功，系統會在回應的 `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 值區進行跨源資源共享。如果預檢要求成功，系統會在回應的 `Access-Control-Allow-Headers` 標頭中傳回值。	對於預檢要求，Cloud Storage 會根據值區的 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 欄位值為何。
使用 XML API 時，您可以透過個別元素指定多個來源、方法或標頭。例如：
```
<Methods>
  <Method>PUT</Method>
  <Method>GET</Method>
</Methods>
```
如要允許從任何來源提出要求，請將來源設為萬用字元 *。例如，JSON API 中的 "origin": ["*"] 或 XML API 中的 <Origin>*</Origin>。雖然這個來源有助於測試設定，但在大多數情況下，您會想要限制要求來源，避免資源遭到濫用。

其他事項

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

屬性或標題說明 XML API 回應行為 JSON API 回應行為

憑證

Cookie、授權標頭或 TLS 用戶端憑證。

屬性或標題	說明	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 標頭清單)。

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 上的內容。

最佳做法是為這類資料存取提供專屬的特定值區。以防您的網站在無意中將靜態資源過度公開給所有的 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 要求問題。