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