標準要求

標準要求定義使用者在傳送 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.googleapis.com/example-bucket/cat-pics/tabby.jpeg，則資源路徑為 /example-bucket/cat-pics/tabby.jpeg。

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

如需可與已簽署網址搭配使用的網址端點，請參閱 XML API 要求端點。

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

標準查詢字串

標準要求會指定每個查詢字串參數，後續將納入使用相關簽名的任何已簽署要求，但 X-Goog-Signature 或 X-Amz-Signature 查詢字串參數除外。標準要求中指定的查詢字串稱為標準查詢字串

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

舉例來說，如果 Cloud Storage 網址為 https://storage.googleapis.com/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.googleapis.com
content-type: text/plain
x-goog-meta-reviewer: jane
x-goog-meta-reviewer: john

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

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

必要的標準標頭

系統會視需要新增多數標頭 (像是 content-type)，但如果您打算在已簽署要求中使用以下標頭，就必須一律在標準標頭中定義這些標頭：

  • host：存取 Cloud Storage 所用的網址。
  • 標頭前置字串為 x-goog-。唯一可選用的標準標頭是 x-goog-content-sha256。
  • 標頭前置字串為 x-amz-。唯一可選用的標準標頭是 x-amz-content-sha256。

已簽署標頭

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

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

範例

如果您有以下這組標頭：

host: storage.googleapis.com
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.googleapis.com
x-amz-content-sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
x-amz-date:20190301T190859Z

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

後續步驟