建立 Pub/Sub 系統時,酬載解除包裝可協助您連線至其他系統,這些系統不一定會遵守標準 Pub/Sub 推送端點實作的所有系統需求。
以下是有效負載解除包裝的幾個可能用途:
- 您不想為 HTTP 推送端點編寫 Pub/Sub 專屬的訊息剖析程式碼。
- 您偏好以 HTTP 標頭的形式接收 Pub/Sub 訊息中繼資料,而非 HTTP POST 主體中的中繼資料。
- 您想傳送 Pub/Sub 訊息,並排除 Pub/Sub 中繼資料,例如將資料傳送至第三方 API 時。
酬載解除包裝的運作方式
酬載解除包裝功能會從 Pub/Sub 訊息中移除所有訊息中繼資料,只保留訊息資料。傳送原始訊息資料後,訂閱者即可處理訊息,不必遵守 Pub/Sub 的任何系統需求。
- 透過酬載解包,訊息資料會直接以 HTTP 內文的形式傳送。
- 如果沒有解除酬載包裝,Pub/Sub 會傳送 JSON 物件,其中包含多個訊息中繼資料欄位和訊息資料欄位。在這種情況下,必須剖析 JSON 才能擷取訊息資料,然後進行 base64 解碼。
寫入中繼資料
啟用酬載解除包裝後,您可以使用「寫入中繼資料」選項,將先前移除的訊息中繼資料新增至要求標頭。
- 已啟用寫入中繼資料。將訊息中繼資料加回要求標頭。也會傳送已解碼的原始訊息資料。
- 寫入中繼資料已停用。只傳送已解碼的原始訊息資料。
您可以透過 Pub/Sub、Google Cloud CLI 引數 --push-no-wrapper-write-metadata
和 API 屬性 NoWrapper
寫入中繼資料。根據預設,這個值為空值。
事前準備
封裝和未封裝訊息的範例
以下範例說明傳送包裝和未包裝 HTTP 訊息的差異。在這些範例中,訊息資料包含字串 {"status": "Hello there"}
。
在這個範例中,訂閱項目會啟用酬載解除包裝功能,並將訊息發布至 mytopic
。排序鍵的值為 some-key
,媒體類型則宣告為 application/json
。
gcloud pubsub topics publish mytopic --message='{"status": "Hello there"}' --ordering-key="some-key" --attribute "Content-Type=application/json"
以下各節說明封裝和未封裝訊息之間的差異。
已包裝的訊息
以下範例顯示標準 Pub/Sub 包裝訊息。在這種情況下,酬載解除包裝功能不會啟用。
發布 | 推送端點接收 |
---|---|
data="{"status": "Hello there"}" ordering_key="some-key" attributes= { {"Content-Type", "application/json"} } |
Content-Length: 361 Content-Type: application/json User-Agent: CloudPubSub-Google Host: subscription-project.uc.r.appspot.com { "message": { "attributes": { "Content-Type": "application/json" }, "data": "eyJzdGF0dXMiOiAiSGVsbG8gdGhlcmUifQ==", // Base64 - {"status": "Hello there"} "messageId": "2070443601311540", "message_id": "2070443601311540", "publishTime": "2021-02-26T19:13:55.749Z", "publish_time": "2021-02-26T19:13:55.749Z" }, "subscription": "projects/myproject/..." } |
解除包裝的訊息,且寫入中繼資料已停用
以下範例顯示已解除包裝的訊息,且已停用寫入中繼資料選項。在這種情況下,系統不會納入 x-goog-pubsub-*
標頭和訊息屬性。
發布 | 推送端點接收 |
---|---|
data="{"status": "Hello there"}" ordering_key="some-key" attributes= { {"Content-Type", "application/json"} } |
Content-Length: 25 User-Agent: CloudPubSub-Google Host: subscription-project.uc.r.appspot.com {"status": "Hello there"} |
已啟用「寫入中繼資料」的解除包裝訊息
以下範例顯示已解除包裝的訊息,並啟用寫入中繼資料選項。在本例中,系統會納入 x-goog-pubsub-*
標頭和訊息屬性。
發布 | 推送端點接收 |
---|---|
data="{"status": "Hello there"}" ordering_key="some-key" attributes= { {"Content-Type", "application/json"} } |
x-goog-pubsub-subscription-name: "projects/myproject/..." x-goog-pubsub-message-id: "2070443601311540" x-goog-pubsub-publish-time: "2021-02-26T19:13:55.749Z" x-goog-pubsub-ordering-key: "some-key" Content-Type: application/json Content-Length: 12 User-Agent: CloudPubSub-Google Host: subscription-project.uc.r.appspot.com {"status": "Hello there"} |
設定酬載解除包裝
如要為訂閱項目啟用酬載解除包裝推送傳送功能,請使用 Trusted Cloud 控制台的「Subscription Details」(訂閱項目詳細資料) 頁面、Google Cloud CLI 或用戶端程式庫。
控制台
前往 Trusted Cloud 控制台的「Subscriptions」(訂閱項目) 頁面。
按一下「Create Subscription」 (建立訂閱項目)。
在「Subscription ID」(訂閱項目 ID) 欄位中輸入名稱。
如要瞭解如何命名訂閱項目,請參閱「主題或訂閱項目命名規範」。
從下拉式選單中選取主題。訂閱項目會接收來自主題的訊息。
在「傳送類型」部分,選取「推送」。
如要啟用酬載解除包裝功能,請選取「啟用酬載解除包裝功能」。
(選用) 如要在要求標頭中保留訊息的中繼資料,請選取「寫入中繼資料」。 您必須啟用這個選項,才能為郵件設定 Content-Type 標頭。
指定端點網址。
保留其他所有預設值。
點選「建立」。
gcloud
如要設定包含標準 HTTP 標頭的承載內容解封訂閱項目,請執行下列 gcloud pubsub subscriptions create
指令:
gcloud pubsub subscriptions create SUBSCRIPTION \ --topic TOPIC \ --push-endpoint=PUSH_ENDPOINT \ --push-no-wrapper
更改下列內容:
SUBSCRIPTION
:提取訂閱項目的名稱或 ID。TOPIC
:主題的 ID。PUSH_ENDPOINT
:做為這項訂閱項目端點的網址。例如:https://myproject.appspot.com/myhandler
--push-no-wrapper
:直接以 HTTP 主體形式傳送訊息資料。
如要設定具有酬載解除包裝功能的訂閱項目,並控管 x-goog-pubsub-*
標頭的使用情形,請執行下列指令:
gcloud pubsub subscriptions create SUBSCRIPTION \ --topic TOPIC \ --push-endpoint=PUSH_ENDPOINT \ --push-no-wrapper \ --push-no-wrapper-write-metadata
--push-no-wrapper-write-metadata
:如果為 true,系統會將 Pub/Sub 訊息中繼資料寫入 HTTP 要求的x-goog-pubsub-<KEY>:<VAL>
標頭。將 Pub/Sub 訊息屬性寫入 HTTP 要求的<KEY>:<VAL>
標頭。
Python
在試用這個範例之前,請先按照快速入門:使用用戶端程式庫中的 Python 設定操作說明來進行。詳情請參閱 Pub/Sub Python API 參考說明文件。
Java
在試用這個範例之前,請先按照快速入門:使用用戶端程式庫中的 Java 設定操作說明進行操作。詳情請參閱 Pub/Sub Java API 參考說明文件。
C++
在試用這個範例之前,請先按照快速入門:使用用戶端程式庫中的 C++ 設定操作說明進行操作。詳情請參閱 Pub/Sub C++ API 參考說明文件。
Go
以下範例使用 Go Pub/Sub 用戶端程式庫的主要版本 (v2)。如果您仍在使用第 1 版程式庫,請參閱第 2 版遷移指南。如要查看第 1 版程式碼範例清單,請參閱 已淘汰的程式碼範例。
在試用這個範例之前,請先按照快速入門:使用用戶端程式庫中的 Go 設定說明進行操作。詳情請參閱 Pub/Sub Go API 參考說明文件。
Node.js
在嘗試這個範例之前,請先按照快速入門:使用用戶端程式庫中的 Node.js 設定說明進行操作。詳情請參閱 Pub/Sub Node.js API 參考說明文件。
Node.js
在嘗試這個範例之前,請先按照快速入門:使用用戶端程式庫中的 Node.js 設定說明進行操作。詳情請參閱 Pub/Sub Node.js API 參考說明文件。
在郵件中設定內容類型標頭
啟用酬載解除包裝後,Pub/Sub 不會在要求中自動設定媒體類型標頭欄位。如果您未明確設定 Content-Type
標頭欄位,處理您要求的網路伺服器可能會設定 application/octet-stream
的預設值,或以非預期的方式解讀要求。
如果您需要 Content-Type
標頭,請務必在發布時,為每則發布的訊息明確聲明。如要執行這項操作,請先啟用「寫入中繼資料」。啟用「寫入中繼資料」的結果如範例所示。
後續步驟
- 如果解除封裝酬載時發生問題,請參閱「排解解除封裝酬載的問題」。