已簽署網址

此頁面提供已簽署網址的總覽,您可以使用這些網址將限時資源的存取權提供給任何擁有網址的人,不論他們是否擁有 Google 帳號。如要進一步瞭解已簽署網址的建立方式,請參閱以 Cloud Storage 工具進行的 V4 簽署程序以您本身程式進行的 V4 簽署程序。如要進一步瞭解其他控管值區和物件存取權的方式,請參閱「存取權控管總覽」。

總覽

已簽署網址,這個網址可提供有限的權限和時間來提出要求。已簽署網址在查詢字串中包含驗證資訊,讓不具憑證的使用者可對資源執行特定動作。 產生已簽署網址時,您指定的使用者或服務帳戶必須具備足夠的權限,可提出已簽署網址將提出的要求。產生已簽署網址後,任何擁有該網址的人員都可以使用已簽署網址執行特定動作,例如,在特定時段內讀取物件。

何時應使用已簽署網址?

某些情況下,您可能不想要求使用者擁有 Google 帳戶才能存取 Cloud Storage,不過仍希望使用應用程式專屬邏輯來控制存取權。一般的因應方法是,將已簽署網址提供給使用者,讓使用者能在期限內讀取、寫入或刪除該資源。任何人只要知道網址,就可以存取該資源,直到網址過期。建立已簽署網址時需指定到期時間。

產生已簽署網址的選項

Cloud Storage 支援產生已簽署網址的多種方法:

  • 使用服務帳戶驗證進行 V4 簽署 Beta 版:此簽署機制如下所述。

  • 使用服務帳戶驗證進行 V2 簽署:如需此簽署機制的詳細資訊,請前往此處

  • 使用 HMAC 驗證進行簽署:如果您是 Amazon Simple Storage Service (Amazon S3) 使用者,您可以使用現有的工作流程為 Cloud Storage 產生已簽署網址。 只需指定 Cloud Storage 資源,指向主機 storage.googleapis.com,並在產生已簽署網址的過程中使用 Google HMAC 憑證。

已簽署網址範例

以下範例是在使用服務帳戶驗證進行 V4 簽署程序後所建立的已簽署網址:

https://storage.googleapis.com/example-bucket/cat.jpeg?X-Goog-Algorithm=
GOOG4-RSA-SHA256&X-Goog-Credential=example%40example-project.iam.gserviceaccount
.com%2F20181026%2Fus-central-1%2Fstorage%2Fgoog4_request&X-Goog-Date=20181026T18
1309Z&X-Goog-Expires=900&X-Goog-SignedHeaders=host&X-Goog-Signature=247a2aa45f16
9edf4d187d54e7cc46e4731b1e6273242c4f4c39a1d2507a0e58706e25e3a85a7dbb891d62afa849
6def8e260c1db863d9ace85ff0a184b894b117fe46d1225c82f2aa19efd52cf21d3e2022b3b868dc
c1aca2741951ed5bf3bb25a34f5e9316a2841e8ff4c530b22ceaa1c5ce09c7cbb5732631510c2058
0e61723f5594de3aea497f195456a2ff2bdd0d13bad47289d8611b6f9cfeef0c46c91a455b94e90a
66924f722292d21e24d31dcfb38ce0c0f353ffa5a9756fc2a9f2b40bc2113206a81e324fc4fd6823
a29163fa845c8ae7eca1fcf6e5bb48b3200983c56c5ca81fffb151cca7402beddfc4a76b13344703
2ea7abedc098d2eb14a7

此簽署網址會提供在值區 example-bucket 讀取物件 cat.jpeg 的存取權。產生此已簽署網址的查詢參數為:

  • X-Goog-Algorithm:簽署網址所用的演算法。

  • X-Goog-Credential:建立已簽署網址所用的憑證相關資訊。

  • X-Goog-Date:已簽署網址可供使用的日期和時間,格式為 ISO 8601 基本格式YYYYMMDD'T'HHMMSS'Z'

  • X-Goog-Expires:已簽署網址維持有效的時間長度,以 X-Goog-Date 中的值開始量測 (以秒為單位)。

  • X-Goog-SignedHeaders:需在使用已簽署網址的任何要求中所含標頭。

  • X-Goog-Signature:允許使用此已簽署網址的要求存取 cat.jpeg 的驗證字串。

使用已簽署網址搭配支援續傳的上傳作業

使用已簽署網址搭配可續傳上傳來將物件上傳到值區,您僅需要在初始 POST 要求中使用此已簽署網址。系統不會在 POST 要求中上傳任何資料;該要求反而會傳回工作階段網址,在後續的 PUT 要求中會用到此網址來上傳資料。實際上,此工作階段網址是驗證憑證,PUT 要求就不需使用原始已簽署網址。此行為可讓伺服器提出 POST 要求,用戶端就不需自行處理已簽署網址。

支援續傳的上傳作業最好在啟動此作業的地區進行。舉例來說,如果您在美國建立支援續傳的上傳網址,並將其提供給亞洲的用戶端,則上傳作業仍會透過美國進行。在不是啟動上傳的地區執行支援續傳的上傳作業,可能導致上傳速度緩慢。若要避免此狀況,請透過伺服器建構和簽署初始 POST 要求,然後將已簽署網址提供給用戶端,即可透過用戶端所在的位置啟動上傳。啟動後,用戶端就可以正常使用產生的工作階段 URI,來發出無需簽署的 PUT 要求。

已簽署網址的注意事項

使用已簽署網址時,請注意下列幾點:

  • 系統通常可為任何 XML API 要求產生已簽署網址;然而,Node.js Cloud Storage 用戶端程式庫目前僅能夠為個別物件產生已簽署網址。例如,無法使用此程式庫來產生在值區中列出物件的已簽署網址。

  • Python 和 Go Cloud Storage 用戶端程式庫目前不支援 V4 已簽署網址。

  • 無法藉由簽章來對 response-content-dispositionresponse-content-type 之類的查詢字串參數進行驗證。若要在回應中強制執行 Content-Disposition 或 Content-Type,請在物件中繼資料中設定那些參數

  • 指定憑證時,建議您使用服務帳戶的電子郵件地址來進行識別,但也支援使用服務帳戶 ID。

標準要求

標準要求會定義使用者在使用已簽署網址時必須提出的要求。其中包含的資訊像是 HTTP 動詞、查詢字串參數以及必須在已簽署網址的要求中使用的標頭,以及物件值區,和已簽署網址將存取權授予其中的其他資源。

HTTP 動詞

已簽署網址可與以下 HTTP 動詞搭配使用:

資源路徑

在標準要求中包含的是已簽署網址適用的資源路徑。資源路徑是接在主機名稱但在任何查詢字串後的部分。

例如,如果 Cloud Storage 網址是 https://storage.googleapis.com/example-bucket/cat-pics/tabby.jpeg?userProject=my-project,則資源路徑是 /example-bucket/cat-pics/tabby.jpeg

如果您使用 https://example-bucket.storage.googleapis.com/cat-pics/tabby.jpeg?userProject=my-project 這類替代的 Cloud Storage 網址,則資源路徑是 /cat-pics/tabby.jpeg

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

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

查詢字串

在標準要求中包含的是,必須在使用已簽署網址的任何要求中包含的查詢字串參數。查詢字串是在資源路徑結尾接在問號 (?) 之後的部分。

例如,如果 Cloud Storage 網址是 https://storage.googleapis.com/example-bucket/cat-pics/tabby.jpeg?userProject=my-project,則查詢字串是 userProject=my-project

在標準要求中,查詢字串必須使用依碼點值,按名稱的字典排序為所有參數排序,所有參數必須以 & 分隔。

必要的查詢字串參數

系統會視需要新增許多查詢字串參數 (像是 alt),但在每個已簽署網址中都需要以下查詢字串參數:

  • X-Goog-Algorithm:簽署網址所用的演算法。有效值為 GOOG4-RSA-SHA256GOOG4-HMAC-SHA256
  • X-Goog-Credential:簽署網址所用的憑證。憑證包含使用以下格式提供的授權者和憑證範圍[AUTHORIZER]%2F[CREDENTIAL_SCOPE]。授權者可以是服務帳戶名稱或 HMAC 存取金鑰。
  • X-Goog-Date:使用 ISO 8601 基本格式的目前日期和時間,YYYYMMDD'T'HHMMSS'Z'
  • X-Goog-Expires:已簽署網址的生命週期,從 X-Goog-Date 開始以秒為單位量測。
  • X-Goog-SignedHeaders:必須在使用已簽署網址的任何要求中所含標頭名稱清單 (以分號分隔)。host 必須是這些標頭中的其中一個。
  • X-Goog-Signature:驗證要求的簽章。

標頭

標準要求中包含的是必須在使用已簽署網址的任何要求中包含的標頭,包含以 x-goog 開頭的自訂標頭和擴充標頭。您會在標準要求的幾個部分中指定標頭:

  1. X-Goog-SignedHeaders 查詢字串參數中指定標頭名稱,每個名稱以 ; 分隔。
  2. 指定在標準要求的查詢字串部分後的標頭 name:value,每一個配對以換行符號 (\n) 分隔。
  3. 在標頭 name:value 配對清單後的換行符號中指定標頭名稱,每個名稱以 ; 分隔。

為標頭指定 name:value 配對時,請留意以下事項:

  • 將所有標頭名稱設為小寫。
  • 依碼點值,按標頭名稱的字母順序排序所有標頭。
  • 使用以逗號分隔的值清單建立標頭名稱,藉此消除重複的標頭名稱。請確認值之間沒有空白字元,且逗號分隔的清單順序與要求中的標頭排列順序相同。如需詳細資訊,請參閱 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

憑證範圍

此憑證範圍會同時出現在要簽署的字串與 X-Goog-Credential 查詢字串參數中。其結構如下:

[DATE]/[LOCATION]/storage/goog4_request
  • [DATE]:日期格式為 YYYYMMDD,此日期必須與在要簽署字串中所用的日期相符。
  • [LOCATION]:資源所在或即將建立的區域。Cloud Storage 資源的 [LOCATION] 可是任意值:[LOCATION] 參數的存在是為保持與 Amazon Simple Storage Service (Amazon S3) 的相容性。
  • storage:服務名稱。
  • goog4_request:已簽署網址的類型。

範例: 20181102/us/storage/goog4_request

使用 Google Cloud Platform 工具簽署字串

使用程式產生已簽署網址時,簽署字串的一個選項是使用 GCP 提供的工具。

App Engine App Identity 服務

在 App Engine 應用程式中的簽署會使用 App Engine Identity 服務,後者會利用 App Engine 服務帳戶憑證。例如,您可以使用 Python App Identity API 執行以下作業:

  • 使用 google.appengine.api.app_identity.sign_blob() 從建構的字串簽署位元組,以提供組合已簽署網址時所需的 Signature

  • 使用 google.appengine.api.app_identity.get_service_account_name() 擷取服務帳戶名稱,這是組合已簽署網址時所需的 GoogleAccessId

App Engine 也提供其他語言的支援:

App Identity 服務在簽署 blob 時會輪替私密金鑰。從 App Identity 服務產生的已簽署網址,有效期限至少一小時,最適合需要短期資源存取權的情況。

IAM signBlob

可使用 IAM signBlob 方法完成簽署。

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

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

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