標準要求

標準要求定義了使用者在傳送 V4 簽章驗證要求 (例如經簽署的網址) 至 Cloud Storage 時，必須包含的要求元素。

總覽

標準要求是一個字串，代表對 Cloud Storage 提出的特定 HTTP 要求。您可以使用標準要求和加密編譯金鑰 (例如 RSA 金鑰) 建立簽章，然後將簽章納入實際要求中做為驗證。

標準要求當中的資訊包括 HTTP 動詞、查詢字串參數，以及預期在實際要求中使用的標頭，另外還有所要求的物件、值區或其他資源。

標準要求可以確保在 Cloud Storage 接收要求時，能夠計算您所計算的相同簽名。如果您的版本與 Cloud Storage 計算的版本不符，要求就會失敗。

結構

標準要求具備下列結構，包括在各個元素之間使用新行：

HTTP_VERB
PATH_TO_RESOURCE
CANONICAL_QUERY_STRING
CANONICAL_HEADERS

SIGNED_HEADERS
PAYLOAD

HTTP 動詞

經簽署的要求可以使用下列 HTTP 動詞，這些動詞必須指定為標準要求的一部分：

  • DELETE
  • GET
  • HEAD
  • POST1
  • PUT

1 經簽署的網址只能用於啟動支援續傳的上傳作業的 POST 要求。詳情請參閱「使用經簽署的網址進行支援續傳的上傳作業」。

資源路徑

標準要求包含套用要求的資源路徑。資源路徑是指主機名稱後方，以及任何查詢字串前方的所有內容。

舉例來說，如果 Cloud Storage 網址為 https://storage.s3nsapis.fr/example-bucket/cat-pics/tabby.jpeg，則資源路徑為 /example-bucket/cat-pics/tabby.jpeg。

如果您使用其他 Cloud Storage 網址 (例如 https://example-bucket.storage.s3nsapis.fr/cat-pics/tabby.jpeg)，則資源路徑為 /cat-pics/tabby.jpeg。

如要瞭解可與經簽署的網址搭配使用的其他網址端點，請參閱「XML API 要求端點」。

定義資源路徑時，您必須對下列保留字元使用百分比編碼：?=!#$&'()*+,:;@[]"。網址中使用的任何其他百分比編碼也應包含在資源路徑中。

標準查詢字串

標準要求會指定每個查詢字串參數，這些參數隨後會包含在使用相關簽章的任何經簽署的要求中，但 X-Goog-Signature 或 X-Amz-Signature 查詢字串參數除外。標準要求中指定的查詢字串稱為標準查詢字串

查詢字串就是資源路徑結尾處的問號 (?) 後面的所有內容。

舉例來說，如果 Cloud Storage 網址為 https://storage.s3nsapis.fr/example-bucket/cat-pics/tabby.jpeg?generation=1360887697105000&userProject=my-project，則查詢字串為 generation=1360887697105000&userProject=my-project。

建構標準查詢字串時：

  • 查詢字串中的參數必須使用依碼點值，按名稱的字典排序進行排序。

  • 查詢字串中的每個參數都必須以 & 分隔。

  • 如果標準查詢字串空白，則整體標準要求的這個部分只會是新的一行 (\n)。

必要的查詢字串參數

大部分的查詢字串參數都是視需要新增，但如果您打算使用標準要求建立經簽署的網址，則必須在標準要求中加入下列參數：

  • X-Goog-Algorithm：您將用來簽署網址的演算法。有效值為 GOOG4-RSA-SHA256 和 GOOG4-HMAC-SHA256。
  • X-Goog-Credential：您將用來簽署網址的憑證。憑證包含使用以下格式提供的授權者和憑證範圍：AUTHORIZER%2FCREDENTIAL_SCOPE。授權者可以是服務帳戶名稱或 HMAC 金鑰存取 ID。
  • X-Goog-Date：經簽署的網址可開始使用的日期和時間，採用 ISO 8601 基本格式 YYYYMMDD'T'HHMMSS'Z'。
  • X-Goog-Expires：經簽署的網址的生命週期，以 X-Goog-Date 開始計算的秒數為單位。最長的到期值為 604800 秒 (7 天)。
  • X-Goog-SignedHeaders：標準要求中所定義標頭名稱的分號分隔清單。這些也稱為已簽署標頭。host 必須是其中一個標頭名稱。

這些查詢字串參數隨後必須用於經簽署的網址本身，以及 X-Goog-Signature 查詢字串參數，其中包含驗證要求的簽章。

標準標頭

標準要求包含任何「必須」隨後包含在使用相關簽章的經簽署的要求中的標頭。不過，這類經簽署的要求可以包含標準要求中未指定的額外標頭，但必要標頭中註明的標頭除外。標準要求中指定的標頭稱為「標準標頭」。

標準標頭可包含自訂標頭以及開頭為 x-goog- 的擴充標頭。

指定標準標頭時，務必注意以下事項：

  • 將所有標頭名稱設為小寫。
  • 依碼點值，按標頭名稱的字母順序排序所有標頭。
  • 使用換行符號 (\n) 分隔每個標頭。
  • 使用以逗號分隔的值清單建立標頭名稱，藉此消除重複的標頭名稱。請確認值之間沒有空白字元，且逗號分隔的清單順序與要求中的標頭排列順序相同。如需詳細資訊，請參閱 RFC 7230 的 3.2 節。
  • 以單一空格取代所有折疊的空白字元或新行字元 (CRLF 或 LF)。如要進一步瞭解折疊的空白字元，請參閱 RFC 7230 的 3.2.4 節。

  • 移除位於標頭名稱後方的冒號前後的任何空白字元。

    舉例來說，使用自訂標頭 x-goog-acl: private 時，如果沒有移除半形冒號後的空格，系統會傳回 403 Forbidden 錯誤，因為您計算的請求簽章與 Cloud Storage 計算的簽章不符。

範例

如果您有以下這組標頭：

host: storage.s3nsapis.fr
content-type: text/plain
x-goog-meta-reviewer: jane
x-goog-meta-reviewer: john

標準要求中標準標頭的結構會是：

content-type:text/plain
host:storage.s3nsapis.fr
x-goog-meta-reviewer:jane,john

必要的標準標頭

大多數標頭 (例如 content-type) 會視需要新增，但如果您打算在經簽署的要求中使用下列標頭，則必須一律在標準標頭中定義這些標頭：

  • host：用於存取 Cloud Storage 的 URI。
  • 標頭前置字串為 x-goog-。唯一可選擇是否納入標準標頭的是 x-goog-content-sha256。
  • 標頭前置字串為 x-amz-。唯一可選擇是否納入標準標頭的標頭是 x-amz-content-sha256。

已簽署標頭

已簽署標頭是標準標頭的名稱部分。

如要建立已簽署標頭清單，請將所有標頭名稱轉換為小寫，依據字元代碼進行排序，然後使用分號 (;) 分隔各名稱。

範例

如果您有以下這組標頭：

host: storage.s3nsapis.fr
content-type: text/plain
x-goog-meta-reviewer: jane
x-goog-meta-reviewer: john

標準要求中已簽署標頭的結構會是：

content-type;host;x-goog-meta-reviewer

酬載

  • 如果標準要求會用於建立經簽署的網址，這個值應為字串 UNSIGNED-PAYLOAD。

  • 如果標準要求將用於建立要在 Authorization 標頭中使用的簽章：

    • 如要允許任意酬載做為要求的一部分，請使用 UNSIGNED-PAYLOAD。

    • 如果要求會啟動支援續傳的上傳作業，請使用 UNSIGNED-PAYLOAD，因為系統會忽略支援續傳上傳作業的 x-goog-content-sha256 標頭。

    • 如要只允許特定酬載，這個值應為預期酬載的 SHA-256 雜湊，並以十六進位編碼的小寫形式表示。如要要求空酬載，請使用空字串做為雜湊函式的輸入內容。雜湊酬載範例 (本例為空白酬載)：

      e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

範例

以下是格式正確的標準要求範例，其中新行會顯示為實際的新行，而不是 \n：

GET
/example-bucket/tabby.jpeg

host:storage.s3nsapis.fr
x-amz-content-sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
x-amz-date:20190301T190859Z

host;x-amz-content-sha256;x-amz-date
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

後續步驟