標準要求

標準要求定義使用者在傳送 V4 簽名驗證的要求至 Cloud Storage 時,必須納入要求中的元素,例如已簽署的網址)。如果您要傳送 V2 已簽署的網址,請參閱 V2 簽署程序

總覽

標準要求是一個字串,代表對 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 要求端點

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

標準查詢字串

標準要求包含的任何查詢字串參數,後續都必須納入使用相關簽名的已簽署要求當中。不過,這類已簽署要求可能包含未在標準要求中指定的其他查詢字串參數。標準要求中指定的查詢字串稱為標準查詢字串

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

舉例來說,如果 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-SHA256GOOG4-HMAC-SHA256
  • X-Goog-Credential:您將用來簽署網址的憑證。憑證包含使用以下格式提供的授權者和憑證範圍[AUTHORIZER]%2F[CREDENTIAL_SCOPE]。授權者可以是服務帳戶名稱或 HMAC 存取金鑰。
  • X-Goog-Date:使用 [ISO 8601][8] 基本格式 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 錯誤,因為您計算出的要求簽章與 Google 計算出的簽章不符。

範例

如果您有以下這組標頭:

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-project-id
  • x-goog-copy-source
  • x-goog-metadata-directive
  • x-amz-copy-source
  • x-amz-metadata-directive

已簽署標頭

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

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

範例

如果您有以下這組標頭:

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 標頭的要求當中使用,則這個值應為十六進位編碼的 SHA-256 雜湊要求酬載。如果酬載是空白的,請使用空白字串作為雜湊函式輸入。雜湊酬載 (本例中為空白酬載) 的範例如下:

    3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

範例

以下是格式正確的標準要求範例,其中新行會顯示為實際的新行,而不是 \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

後續步驟

本頁內容對您是否有任何幫助?請提供意見:

傳送您對下列選項的寶貴意見...

這個網頁
Cloud Storage
需要協助嗎?請前往我們的支援網頁