Cloud Storage 的 Cloud Pub/Sub 通知

本頁提供 Cloud Storage 的 Cloud Pub/Sub 通知總覽。想瞭解如何設定及使用 Cloud Pub/Sub 通知,請參閱註冊物件變更一文。

總覽

Cloud Pub/Sub 通知可以將值區內物件的變更資訊傳送到 Cloud Pub/Sub,Cloud Pub/Sub 隨後將資訊以訊息形式新增至您設定的 Cloud Pub/Sub 主題。例如,您可以追蹤在值區內建立和刪除的物件。每則通知都包含說明觸發異動的事件與變更的物件相關資訊。

只要是您有足夠權限的專案,您就能將通知傳送至其中的任何 Cloud Pub/Sub 主題。Cloud Pub/Sub 主題收到通知後,即可將結果訊息傳送給主題訂閱者 (數量不限)。如需將 Cloud Storage 值區連結至 Cloud Pub/Sub 主題的相關資訊,請參閱事前準備一節。

其他通知選項

訂閱 Cloud Pub/Sub 通知功能多元,可以提供值區變動的相關快訊,有助您採取應變動作。服務包括以下選項:

  • Cloud Functions:如果您只想針對事件觸發輕量的獨立式函式,而不想管理 Cloud Pub/Sub 主題,請使用 Cloud Functions。Cloud Functions 可讓您在值區內物件變更時,執行 JavaScript 函式。請注意,您的值區必須與 Cloud Functions 位於同一專案中。如需將 Cloud Functions 與 Cloud Storage 搭配使用的示範,請參閱相關教學課程

  • 物件變更通知:物件變更通知是另一個用於產生通知的 Cloud Storage 舊版功能。這個功能可以將 HTTPS 訊息傳送至您另行設定的用戶端應用程式。一般來說,Cloud Pub/Sub 通知較便宜,且更靈活易於使用。

通知設定

「通知設定」是您附加到值區的規則,可以指定下列項目:

  • Cloud Pub/Sub 中接收通知的主題。
  • 觸發系統傳送通知的事件。
  • 通知中包含的資訊。

您可以將多個通知設定附加到值區。每個事件最多可設定 10 個觸發通知的通知設定。

舉例來說,假如您設有一個可向 Cloud Pub/Sub 主題傳送刪除通知的通知設定,則可以為值區新增第二個通知設定,將刪除通知傳送至其他主題。但是,如果您嘗試建立超過 10 個執行這類動作的通知設定,系統就會顯示錯誤。除了這些通知設定,您也可以另外建立通知設定,將其他的事件通知 (例如物件建立) 傳送至刪除通知使用的 Cloud Pub/Sub 主題或不同主題。

每個通知設定皆使用一個整數進行辨識。整數會在以下情況發生時傳回:

  • 建立通知設定時。
  • 列出附加到值區的通知設定時。
  • 在通知設定觸發的每個通知的 notificationConfig 屬性中。

建立及刪除通知設定會使值區的中繼產生版本號碼遞增。

事件類型

下方為 Cloud Storage 目前支援的事件類型清單:

事件類型 說明
OBJECT_FINALIZE 當在值區中「成功」建立新物件 (或建立現有物件的新產生版本) 時,會傳送這個事件。其中包含複製或重寫現有的物件。上傳失敗不會觸發這個事件。
OBJECT_METADATA_UPDATE 當現有物件的中繼資料變更時,會傳送這個事件。
OBJECT_DELETE 當永久刪除事件時,會傳送這個事件。這包含值區生命週期設定其中覆寫或刪除的物件。如果值區已啟用物件版本管理功能,則系統在封存物件時,不會傳送事件 (即使透過 storage.objects.delete 方法進行封存也不會傳送),詳情請參閱 OBJECT_ARCHIVE 說明。
OBJECT_ARCHIVE 只會在值區已啟用物件版本管理時傳送事件。這個事件表示物件的使用中版本已變為封存版本,原因是物件遭到封存或是因為擁有相同名稱的物件上傳而遭到覆寫。

覆寫物件

使用具有相同名稱的新物件覆寫現有物件,會觸發兩個獨立事件:OBJECT_FINALIZE (針對新版本的物件),以及 OBJECT_ARCHIVEOBJECT_DELETE (針對被覆寫的物件)。OBJECT_FINALIZE 事件包含了額外屬性 overwroteGeneration,提供被覆寫物件的產生版本號碼。OBJECT_ARCHIVEOBJECT_DELETE 事件則包含額外屬性 overwrittenByGeneration,提供新物件的產生版本號碼。

通知格式

傳送至 Cloud Pub/Sub 主題的通知分為以下兩部分:

  • 屬性:用於說明事件的鍵/值組合。
  • 酬載:含變更物件的中繼資料的字串。

屬性

屬性是 Cloud Storage 傳送至 Cloud Pub/Sub 主題的所有通知中包含的鍵/值組合。無論通知酬載為何,通知都會包含以下鍵/值組合:

屬性名稱 範例 說明
notificationConfig projects/_/buckets/foo/notificationConfigs/3 觸發這則通知的通知設定 ID。
eventType OBJECT_FINALIZE 最新發生事件的類型,如需可能值的清單,請參閱事件類型一節。
payloadFormat JSON_API_V1 物件酬載的格式,如需可能值的清單,請參閱酬載一節。
bucketId foo 包含已變更物件的值區名稱。
objectId bar 已變更物件的名稱。
objectGeneration 123456 已變更物件的產生版本號碼。

無論通知酬載為何,通知有時會包含以下鍵/值組合:

屬性名稱 範例 說明
overwrittenByGeneration 107458 覆寫通知相關物件的物件產生版本號碼。只有在發生覆寫時,這個屬性才會在 OBJECT_ARCHIVEOBJECT_DELETE 事件中出現。
overwroteGeneration 352947 遭到通知相關物件覆寫的物件產生版本號碼。只有在發生覆寫時,這個屬性才會在 OBJECT_FINALIZE 事件中出現。

以下為已淘汰的鍵/值組合。這些組合不會出現在新的訂閱中,也不會出現在 2018 年 6 月 1 日之後的任何訂閱中:

屬性名稱 範例 說明
資源 projects/_/buckets/foo/objects/bar#123456 已變更的 Cloud Storage 物件路徑。

除了上述屬性外,通知也能包含自訂屬性。這些屬性是在建立通知設定時定義,使用 gsutil notification 指令中的 -m 標記;或是 POST notificationConfigs JSON 要求主體中的 custom_attributes 物件。

酬載

酬載是包含已變更物件中繼資料的字串。當您建立通知設定時,需要指定該設定觸發的通知中包含的酬載類型。您可以指定以下酬載類型:

酬載類型 說明
NONE 通知不會包含任何酬載。
JSON_API_V1 酬載為 UTF-8 字串,內含物件中繼資料的資源表示法

對於 OBJECT_DELETE 通知,酬載中包含的中繼資料代表刪除前的物件中繼資料,以及其他 timeDeleted 屬性。對於所有其他的通知,酬載中包含的中繼資料代表變更發生「之後」的物件中繼資料。

假設您設有追縱 OBJECT_METADATA_UPDATE 事件的通知設定。如果使用者將物件的 contentType 屬性從 binary/octet-stream 變更為 video/mp4,系統就會傳送 OBJECT_METADATA_UPDATE 通知,且酬載中的中繼資料包含 "contentType":"video/mp4"

關於通知訊息的注意事項

新增通知設定時,Cloud Storage 最多可能需要 30 秒才能開始傳送與設定有關的通知。啟動之後,Cloud Storage 保證至少向 Cloud Pub/Sub 傳送一次。Cloud Pub/Sub 也會至少向接收者傳送一次,這表示您可以收到代表相同 Cloud Storage 事件、具有多個 ID 的多個訊息。傳送時間目前尚未提供服務水準協議,但是通常通知會在數秒之內完成傳送。只有在極少數的情況下,通知可能會延遲較長時間。

系統無法保證能以 Cloud Pub/Sub 接收通知的順序發佈通知。如果您計劃根據通知來修改 Cloud Storage 物件,則建議使用物件的產生版本號碼及中繼產生版本號碼做為更新要求的先決條件。

如果系統持續無法將通知傳送至 Cloud Pub/Sub 主題,Cloud Storage 會在 7 天以後刪除該項通知。以下的情況可能會導致傳送失敗:Cloud Pub/Sub 主題已不存在、Cloud Storage 不再具有發佈主題的權限,或擁有主題的專案超過發佈配額。

後續步驟

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

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

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