本頁面提供 Cloud Storage 的 Pub/Sub 通知總覽。
總覽
Pub/Sub 通知可以將值區內物件的變更資訊傳送到 Pub/Sub，資訊會以訊息形式新增至您設定的 Pub/Sub 主題。例如，您可以追蹤在值區內建立和刪除的物件。每則通知都包含說明觸發異動的事件與變更的物件相關資訊。
只要是您有足夠權限的專案，您就能將通知傳送至其中的任何 Pub/Sub 主題。Pub/Sub 主題收到通知後，主題的訂閱者即可收到相關訊息。如要瞭解如何將 Cloud Storage bucket 連結至 Pub/Sub 主題，請參閱「設定 Cloud Storage 的 Pub/Sub 通知」。
其他通知選項
訂閱 Pub/Sub 通知是觸發警告和動作，以回應 bucket 變更的多功能方式。服務包括以下選項：
- Cloud Run functions：如果只想觸發輕量級獨立函式來回應事件，且不想管理 Pub/Sub 主題，請使用 Cloud Run functions。Cloud Run functions 可讓您在 bucket 中的物件變更時，執行 C#、Go、Java、Node.js、Python、PHP 和 Ruby 函式。請注意，bucket 必須與 Cloud Run functions 位於相同專案。如要瞭解如何搭配使用 Cloud Run 函式和 Cloud Storage，請參閱相關教學課程。
通知設定
「通知設定」是您附加到值區的規則，可以指定下列項目：
- 接收通知的 Pub/Sub 主題。
- 觸發系統傳送通知的事件。
- 通知中包含的資訊。
您可以將多個通知設定附加到值區。一個 bucket 最多可以有 100 項通知設定，在特定事件發生時觸發通知。
舉例來說，如果您已設定通知，將刪除通知傳送至某個 Pub/Sub 主題，可以為 bucket 新增第二項通知設定，將刪除通知傳送至另一個主題。但是，如果您嘗試建立超過 10 個執行這類動作的通知設定，系統就會顯示錯誤。除了這些通知設定外，您也可以建立通知設定，針對其他事件 (例如物件建立) 傳送通知，傳送至刪除通知使用的 Pub/Sub 主題，或傳送至其他主題。
每個通知設定皆使用一個整數進行辨識。整數會在以下情況發生時傳回：
- 建立通知設定時。
- 列出附加至值區的通知設定。
- 在通知設定觸發的每個通知的
notificationConfig屬性中。
建立及刪除通知設定會增加 bucket 的中繼資料版本編號。
事件類型
以下是 Cloud Storage 支援的事件類型清單：
| 事件類型 | 說明 |
|---|---|
OBJECT_FINALIZE |
這個事件會在 bucket 中成功建立新物件 (或現有物件的新版本) 時傳送。複製、重寫或還原現有物件也會觸發此事件，這也包括在可用區 bucket 中完成物件。上傳失敗不會觸發這個事件。 |
OBJECT_INITIALIZE |
這個事件會在物件開始在區域 bucket 中建立時傳送。 |
OBJECT_METADATA_UPDATE |
這個事件會在現有物件的中繼資料變更時傳送。 |
OBJECT_DELETE |
當永久刪除物件時，會傳送這個事件。包含因 bucket 生命週期設定而遭取代或刪除的情況。這不包括變成非現出版的物件 (請參閱 OBJECT_ARCHIVE) 或已取消的分段上傳。 |
OBJECT_ARCHIVE |
只會在值區已啟用物件版本管理時傳送事件。這代表物件的使用中版本已變為非現行版本，原因是物件遭到明確設為非現行版本，或因同名物件上傳而遭到取代。 |
如要監聽其他 Cloud Storage 事件 (例如 bucket 作業或物件讀取)，您可以在 Cloud 稽核記錄中啟用適當的稽核記錄類型，並使用篩選器將稽核記錄轉送至 Pub/Sub。
替換物件
以同名的新物件取代現有物件時，會觸發兩個不同的事件：新版物件的 OBJECT_FINALIZE，以及取代物件的 OBJECT_ARCHIVE 或 OBJECT_DELETE。OBJECT_FINALIZE 事件包含額外屬性 overwroteGeneration，可提供遭取代物件的版本編號。OBJECT_ARCHIVE 或 OBJECT_DELETE 事件包含額外屬性 overwrittenByGeneration，可提供新物件的產生版本號碼。
通知格式
傳送至 Pub/Sub 主題的通知包含兩部分：
- 屬性：用於說明事件的鍵/值組合。
- 酬載：含變更物件的中繼資料的字串。
如要瞭解通知訊息的結構，請參閱 PubsubMessage 資源表示法。
屬性
屬性是鍵/值組合，包含在 Cloud Storage 傳送至 Pub/Sub 主題的所有通知中。無論通知酬載為何，通知都會包含以下鍵值組合：
| 屬性名稱 | 範例 | 說明 |
|---|---|---|
| notificationConfig | projects/_/buckets/foo/notificationConfigs/3 |
觸發這則通知的通知設定 ID。 |
| eventType | OBJECT_FINALIZE |
最新發生事件的類型，如需可能值的清單，請參閱事件類型一節。 |
| payloadFormat | JSON_API_V1 |
物件酬載的格式，如需可能值的清單，請參閱酬載一節。 |
| bucketId | foo |
包含已變更物件的值區名稱。 |
| objectId | bar |
已變更物件的名稱。 |
| objectGeneration | 123456 |
變更物件的代號。 |
| eventTime | 2021-01-15T01:30:15.01Z |
事件發生時間，以 RFC 3339 格式表示。 |
無論通知酬載為何，通知有時會包含以下鍵/值組合：
| 屬性名稱 | 範例 | 說明 |
|---|---|---|
| overwrittenByGeneration | 107458 |
取代這項通知相關物件的物件世代編號。只有在替換時，這項屬性才會出現在 OBJECT_ARCHIVE 或 OBJECT_DELETE 事件中。 |
| overwroteGeneration | 352947 |
物件的產生編號，該物件已被這則通知相關的物件取代。只有在替換時，這項屬性才會出現在 OBJECT_FINALIZE 事件中。 |
除了上述屬性外，通知設定最多可包含 10 個自訂屬性。建立通知設定時，您可以使用 gcloud storage 指令中的 --custom-attributes，或 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 保證至少會將資料傳送至 Pub/Sub 一次。Pub/Sub 也會向收件者提供至少一次的傳送，這表示您可能會收到多則訊息，其中包含多個 ID，代表相同的 Cloud Storage 事件。
通知不一定會按照 Pub/Sub 接收的順序發布。如果您打算根據通知修改 Cloud Storage 物件，建議您在更新要求中，將物件的世代和中繼資料版本編號設為先決條件。
如果通知持續無法傳送至 Pub/Sub 主題，Cloud Storage 可能會在 7 天後刪除通知。如果 Pub/Sub 主題已不存在、Cloud Storage 不再具備發布至主題的權限，或是擁有主題的專案超出發布配額，就可能發生傳送失敗的情況。
後續步驟
- 設定 Cloud Storage 的 Pub/Sub 通知。
- 進一步瞭解 Pub/Sub。
- 訂閱 bucket，接收傳送至 Pub/Sub 的通知。
- 使用 Cloud Run functions 透過 Cloud Storage 觸發條件傳送事件。
- 使用 Pub/Sub 通知，在 Cloud Storage bucket 之間進行事件驅動移轉。