[適用於 JavaScript 的 AWS SDK V3 API 參考指南](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/)詳細說明 第 3 版 適用於 JavaScript 的 AWS SDK (V3) 的所有 API 操作。

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

# 跨來源資源共享 (CORS)
<a name="cors"></a>

跨來源資源分享 (CORS) 是現代 Web 瀏覽器的一項安全功能，其可讓 Web 瀏覽器協調能請求外部網站或服務的網域。

由於系統會將大多數資源請求傳送至外部網域 (如 Web 服務的端點)，當您使用 適用於 JavaScript 的 AWS SDK 開發瀏覽器應用程式時，CORS 是項重要的考量條件。如果 JavaScript 環境會強制執行 CORS 安全性，您就必須使用服務設定 CORS。

CORS 會根據下列項目，決定是否允許在跨來源請求中共用資源：
+ 提出請求的特定網域 
+ 提出的 HTTP 請求類型 (GET、PUT、POST、DELETE 等)

## CORS 的運作方式
<a name="how-cors-works"></a>

在最簡單的案例中，瀏覽器指令碼會從另一個網域中的伺服器發出資源 GET 請求。依據該伺服器的 CORS 組態而定，如果請求是來自有權提交 GET 請求的網域，則跨來源伺服器會透過傳回請求的資源來予以回應。

若發出請求的網域或 HTTP 請求類型皆未經授權，該請求即會遭拒。然而，CORS 能夠在實際提交請求前進行預檢。此案例中，會發出預檢請求，此請求中會一併傳送 `OPTIONS` 存取請求操作。如果跨來源伺服器的 CORS 組態將存取權限授予給提出請求的網域，伺服器就會傳回預檢回應，其中列出提出請求的網域能對請求資源所進行的 HTTP 請求類型。

![\[CORS 請求的處理流程\]](http://docs.aws.amazon.com/zh_tw/sdk-for-javascript/v3/developer-guide/images/cors-overview.png)


## 是否需要 CORS 組態？
<a name="the-need-for-cors-configuration"></a>

Amazon S3 儲存貯體需要 CORS 組態，才能對其執行操作。在某些 JavaScript 環境中，CORS 可能不會強制執行，因此不需要設定 CORS。例如，如果您從 Amazon S3 儲存貯體託管應用程式，並從 `*.s3.amazonaws.com`或其他一些特定端點存取資源，您的請求將不會存取外部網域。因此，這個組態就不需要 CORS。在此情況下，CORS 仍會用於 Amazon S3 以外的服務。

## 設定 Amazon S3 儲存貯體的 CORS
<a name="configuring-cors-s3-bucket"></a>

您可以在 Amazon S3 主控台中設定 Amazon S3 儲存貯體以使用 CORS。

如果您在 AWS Web Services 管理主控台中設定 CORS，則必須使用 JSON 來建立 CORS 組態。新的 AWS Web Services 管理主控台僅支援 JSON CORS 組態。

**重要**  
在新的 AWS Web 服務管理主控台中，CORS 組態必須是 JSON。

1. 在 AWS Web Services 管理主控台中，開啟 Amazon S3 主控台，尋找您要設定的儲存貯體，然後選取其核取方塊。

1. 在開啟的窗格中，選擇**許可**。

1. 在**許可**索引標籤上，選擇 **CORS 組態**。

1. 在 CORS 組態**編輯器中輸入 CORS 組態**，然後選擇**儲存**。

CORS 組態是一種 XML 檔案，包含 `<CORSRule>` 內的一系列規則。一個組態最多可以擁有 100 條規則，而規則是由下列其中一個標籤所定義：
+ `<AllowedOrigin>` – 指定您允許 提出跨網域請求的網域原始伺服器。
+ `<AllowedMethod>` – 指定您在跨網域請求中允許的請求類型 (GET、PUT、POST、DELETE、HEAD)。
+ `<AllowedHeader>` – 指定預檢請求中允許的標頭。

如需範例組態，請參閱《*Amazon Simple Storage Service 使用者指南*》中的[如何在儲存貯體上設定 CORS？](https://docs.aws.amazon.com/AmazonS3/latest/userguide/cors.html#how-do-i-enable-cors)。

## CORS 組態範例
<a name="cors-configuration-example"></a>

下列 CORS 組態範例可讓使用者從網域 檢視、新增、移除或更新儲存貯體內的物件`example.org`。不過，我們建議您將 範圍`<AllowedOrigin>`限定為網站的網域。若要允許任何來源，則可指定 `"*"`。

**重要**  
在新的 S3 主控台中，CORS 組態必須為 JSON 格式。

------
#### [ XML ]

```
<?xml version="1.0" encoding="UTF-8"?>
<CORSConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <CORSRule>
    <AllowedOrigin>https://example.org</AllowedOrigin>
    <AllowedMethod>HEAD</AllowedMethod>
    <AllowedMethod>GET</AllowedMethod>
    <AllowedMethod>PUT</AllowedMethod>
    <AllowedMethod>POST</AllowedMethod>
    <AllowedMethod>DELETE</AllowedMethod>
    <AllowedHeader>*</AllowedHeader>
    <ExposeHeader>ETag</ExposeHeader>
    <ExposeHeader>x-amz-meta-custom-header</ExposeHeader>
  </CORSRule>
</CORSConfiguration>
```

------
#### [ JSON ]

```
[
    {
        "AllowedHeaders": [
            "*"
        ],
        "AllowedMethods": [
            "HEAD",
            "GET",
            "PUT",
            "POST",
            "DELETE"
        ],
        "AllowedOrigins": [
            "https://www.example.org"
        ],
        "ExposeHeaders": [
             "ETag",
             "x-amz-meta-custom-header"]
    }
]
```

------

這個組態並不會授權使用者對儲存貯體執行任何動作，它可讓瀏覽器的安全模型允許對 Amazon S3 提出請求。必須透過儲存貯體許可或 IAM 角色許可來設定許可。

您可以使用 `ExposeHeader` 讓 SDK 讀取從 Amazon S3 傳回的回應標頭。例如，從 `PUT`或分段上傳讀取 `ETag` 標頭，您需要在組態中包含 `ExposeHeader`標籤，如上一個範例所示。軟體開發套件僅能存取透過 CORS 組態公開的標頭。若您在物件上設定中繼資料，則傳回的值即為具有字首 `x-amz-meta-` 的標頭 (如 `x-amz-meta-my-custom-header`)；請務必以相同方式公開該標頭。