建構 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
公開。根據預設,這個值為 null。
事前準備
已包裝和未包裝訊息的範例
以下範例說明傳送已包裝和未包裝 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"} |
設定酬載解除包裝
您可以使用 Google Cloud 控制台「訂閱詳細資料」頁面、Google Cloud CLI 或用戶端程式庫,為訂閱啟用酬載展開推送傳送功能。
控制台
在 Google Cloud 控制台中,前往「訂閱項目」頁面。
按一下「Create Subscription」 (建立訂閱項目)。
在「Subscription ID」(訂閱項目 ID) 欄位中輸入名稱。
如要瞭解如何命名訂閱項目,請參閱「命名主題或訂閱項目的規範」。
從下拉式選單中選取主題。訂閱項目會接收主題的訊息。
在「Delivery type」(傳送類型) 中,選取「Push」(推送)。
如要啟用酬載解除包裝功能,請選取「啟用酬載解除包裝功能」。
(選用) 如要保留要求標頭中的訊息中繼資料,請選取「Write metadata」。您必須啟用這個選項,才能為郵件設定 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 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
標頭,請務必在發布時明確宣告每個已發布訊息。為此,您必須先啟用「Write metadata」。提供的範例顯示啟用「Write metadata」的結果。
後續步驟
- 如果您在解開酬載時遇到問題,請參閱「排解酬載解開問題」。