本文件將概略介紹拉取訂閱、其工作流程和相關資源。
在提取訂閱項目中,訂閱端的用戶端會向 Pub/Sub 伺服器要求訊息。
提取模式可使用 Pull 或 StreamingPull 這兩種服務 API 的其中一種。如要執行所選 API,您可以選取 Google 提供的高階用戶端程式庫,或自動產生的低階用戶端程式庫。您也可以選擇非同步或同步訊息處理。
事前準備
閱讀本文前,請先熟悉下列內容:
Pub/Sub 的運作方式和不同的 Pub/Sub 術語。
Pub/Sub 支援的不同訂閱類型,以及您可能會想使用提取訂閱的原因。
提取訂閱項目工作流程
對於提取式訂閱,訂閱端用戶端會向 Pub/Sub 伺服器發出要求,以便擷取訊息。訂閱者用戶端會使用下列任一 API:
大多數訂閱者用戶端不會直接提出這些要求。而是仰賴 Google Cloud提供的高階用戶端程式庫,該程式庫會在內部執行串流提取要求,並以非同步方式傳送訊息。如果訂閱者用戶端需要更細微地控制訊息的擷取方式,Pub/Sub 會使用自動產生的低階 gRPC 程式庫。這個程式庫會直接發出拉取或串流拉取要求。這些要求可以是同步或非同步。
下列兩張圖片顯示訂閱者用戶端與拉取訂閱之間的工作流程。


提取工作流程
請參考圖 1,瞭解下列的拉取工作流程:
- 訂閱者用戶端會明確呼叫
pull
方法,要求傳送訊息。這項要求就是圖片中顯示的PullRequest
。 Pub/Sub 伺服器會傳回零或多個訊息和確認 ID。回應中訊息為零或發生錯誤,不一定表示沒有可接收的訊息。這個回應是圖片中顯示的
PullResponse
。訂閱者用戶端會明確呼叫
acknowledge
方法。用戶端會使用傳回的確認 ID,確認訊息已處理,不需要再次傳送。
對於單一串流提取要求,訂閱者用戶端可能會因開放連線而傳回多個回應。相反地,每個提取要求只會傳回一個回應。
提取訂閱項目的屬性
您為提取訂閱項目設定的屬性,會決定您將訊息寫入訂閱項目的方式。詳情請參閱訂閱屬性。
Pub/Sub 服務 API
Pub/Sub 提取訂閱項目可使用下列兩個 API 擷取訊息:
- 提取
- StreamingPull
使用這些 API 接收訊息時,請使用單一 Acknowledge 和 ModifyAckDeadline RPC。以下各節將說明這兩個 Pub/Sub API。
StreamingPull API
在可能的情況下,Pub/Sub 用戶端程式庫會使用 StreamingPull,以便提高總處理量並降低延遲時間。雖然您可能從未直接使用 StreamingPull API,但請務必瞭解它與 Pull API 的差異。
StreamingPull API 會使用持續性雙向連線,在多個訊息可用時接收這些訊息。以下是工作流程:
用戶端會向伺服器傳送要求,以建立連線。如果超出連線配額,伺服器會傳回資源用盡錯誤。用戶端程式庫會自動重試配額不足錯誤。
如果沒有錯誤,或連線配額再次可用,伺服器會持續傳送訊息給已連線的用戶端。
如果或當吞吐量配額超出時,伺服器就會停止傳送訊息。不過,連線並未中斷。只要有足夠的傳輸量配額,串流就會恢復。
用戶端或伺服器最終會關閉連線。
StreamingPull API 會維持開放連線。Pub/Sub 伺服器會在一段時間後重複關閉連線,以避免長時間執行的黏性連線。用戶端程式庫會自動重新開啟 StreamingPull 連線。
訊息會在可用時傳送至連線。因此,StreamingPull API 可盡量減少訊息的延遲時間,並提高訊息的總處理量。
進一步瞭解 StreamingPull RPC 方法:StreamingPullRequest 和 StreamingPullResponse。
Pull API
這個 API 是傳統的單一 RPC,以要求和回應模型為基礎。單一提取回應對應至單一提取要求。以下是工作流程:
用戶端會向伺服器傳送訊息要求。如果吞吐量超出配額,伺服器會傳回資源用盡錯誤。
如果沒有錯誤,或傳輸量配額再次可用,伺服器會回覆零或多個訊息和確認 ID。
使用一元式 Pull API 時,回應中訊息為零或出現錯誤,不一定表示沒有可接收的訊息。
使用 Pull API 不保證訊息的延遲時間短且處理量高。如要透過 Pull API 達到高處理量和低延遲,您必須同時有許多未解決的要求。舊要求收到回應時,系統會建立新要求。建構這類解決方案容易出錯且難以維護。建議您在這種情況下使用 StreamingPull API。
只有在您需要嚴格控管下列項目時,才應改用 Pull API 而非 StreamingPull API:
- 訂閱端用戶端可處理的訊息數量
- 用戶端記憶體和資源
如果訂閱者是 Pub/Sub 與另一個以拉取為導向的服務之間的 Proxy,您也可以使用這個 API。
進一步瞭解提取 REST 方法:方法:projects.subscriptions.pull。
進一步瞭解 Pull RPC 方法:PullRequest 和 PullResponse。
訊息處理模式類型
請為訂閱者用戶端選擇下列其中一種提取模式。
非同步提取模式
非同步提取模式會將接收訊息與訂閱端用戶端中的訊息處理作業分開。這是大多數訂閱者用戶端的預設模式。非同步提取模式可使用 StreamingPull API 或一元提取 API。非同步提取也可以使用高階用戶端程式庫或低階自動產生的用戶端程式庫。
您可以在本文稍後的部分進一步瞭解用戶端程式庫。
同步提取模式
在同步的拉取模式中,系統會依序接收及處理訊息,而不會彼此解耦。因此,與 StreamingPull 和 unary Pull API 類似,非同步處理的延遲時間比同步處理短,且傳輸量更高。
請僅在低延遲和高傳輸量相較於其他要求不那麼重要的應用程式中使用同步拉取模式。舉例來說,應用程式可能只能使用同步程式設計模式。或者,如果應用程式有資源限制,可能需要更精確地控制記憶體、網路或 CPU。在這種情況下,請搭配單一 Pull API 使用同步模式。
Pub/Sub 用戶端程式庫
Pub/Sub 提供高層級和低層級的自動產生用戶端程式庫。
高階 Pub/Sub 用戶端程式庫
高階用戶端程式庫提供多種選項,可透過釋出管理來控制確認期限。這些選項比在訂閱層級使用控制台或 CLI 設定確認期限時,提供更精細的設定。高階用戶端程式庫也實作了支援功能,例如有序傳送、精確傳送和流量控制。
建議您搭配高階用戶端程式庫使用非同步拉取和 StreamingPull API。並非所有支援Google Cloud 的語言都支援高階用戶端程式庫中的 Pull API。
如要使用高階用戶端程式庫,請參閱 Pub/Sub 用戶端程式庫。
自動產生的低階 Pub/Sub 用戶端程式庫
如果您必須直接使用 Pull API,可以使用低階用戶端程式庫。您可以使用同步或非同步處理作業搭配低階自動產生的用戶端程式庫。使用低階自動產生的用戶端程式庫時,您必須手動編寫功能程式碼,例如有序傳送、確切一次傳送、流程控制和租用管理。
您可以使用同步處理模式,為所有支援的語言使用低階自動產生的用戶端程式庫。在直接使用 Pull API 的情況下,您可以使用低階自動產生的用戶端程式庫和同步拉取功能。舉例來說,您可能有依賴此模型的現有應用程式邏輯。
如要直接使用低階自動產生的用戶端程式庫,請參閱 Pub/Sub API 總覽。
用戶端程式庫程式碼範例
StreamingPull 和高階用戶端程式庫程式碼範例
C++
在嘗試這個範例之前,請先按照 快速入門:使用用戶端程式庫中的操作說明設定 C++ 環境。詳情請參閱 Pub/Sub C++ API 參考說明文件。
C#
在嘗試這個範例之前,請先按照 快速入門:使用用戶端程式庫中的操作說明設定 C# 環境。詳情請參閱 Pub/Sub C# API 參考說明文件。
Go
在試用這個範例之前,請先按照 快速入門:使用用戶端程式庫中的 Go 設定說明進行操作。詳情請參閱 Pub/Sub Go API 參考說明文件。
Java
在嘗試這個範例之前,請先按照 快速入門:使用用戶端程式庫中的操作說明設定 Java 環境。詳情請參閱 Pub/Sub Java API 參考說明文件。
Node.js
在嘗試這個範例之前,請先按照 快速入門:使用用戶端程式庫中的操作說明設定 Node.js 環境。詳情請參閱 Pub/Sub Node.js API 參考說明文件。
Node.js
在嘗試這個範例之前,請先按照 快速入門:使用用戶端程式庫中的操作說明設定 Node.js 環境。詳情請參閱 Pub/Sub Node.js API 參考說明文件。
Python
在嘗試這個範例之前,請先按照 快速入門:使用用戶端程式庫中的操作說明設定 Python 環境。詳情請參閱 Pub/Sub Python API 參考說明文件。
Ruby
在嘗試這個範例之前,請先按照 快速入門:使用用戶端程式庫中的操作說明設定 Ruby 環境。詳情請參閱 Pub/Sub Ruby API 參考說明文件。
使用高階用戶端程式庫擷取自訂屬性
以下範例說明如何非同步擷取訊息,並從中繼資料擷取自訂屬性。
C++
在嘗試這個範例之前,請先按照 快速入門:使用用戶端程式庫中的操作說明設定 C++ 環境。詳情請參閱 Pub/Sub C++ API 參考說明文件。
C#
在嘗試這個範例之前,請先按照 快速入門:使用用戶端程式庫中的操作說明設定 C# 環境。詳情請參閱 Pub/Sub C# API 參考說明文件。
Go
在試用這個範例之前,請先按照 快速入門:使用用戶端程式庫中的 Go 設定說明進行操作。詳情請參閱 Pub/Sub Go API 參考說明文件。
Java
在嘗試這個範例之前,請先按照 快速入門:使用用戶端程式庫中的操作說明設定 Java 環境。詳情請參閱 Pub/Sub Java API 參考說明文件。
Node.js
在嘗試這個範例之前,請先按照 快速入門:使用用戶端程式庫中的操作說明設定 Node.js 環境。詳情請參閱 Pub/Sub Node.js API 參考說明文件。
Python
在嘗試這個範例之前,請先按照 快速入門:使用用戶端程式庫中的操作說明設定 Python 環境。詳情請參閱 Pub/Sub Python API 參考說明文件。
Ruby
在嘗試這個範例之前,請先按照 快速入門:使用用戶端程式庫中的操作說明設定 Ruby 環境。詳情請參閱 Pub/Sub Ruby API 參考說明文件。
使用高階用戶端程式庫處理錯誤
下列範例說明如何處理訂閱訊息時發生的錯誤。
C++
在嘗試這個範例之前,請先按照 快速入門:使用用戶端程式庫中的操作說明設定 C++ 環境。詳情請參閱 Pub/Sub C++ API 參考說明文件。
Go
在試用這個範例之前,請先按照 快速入門:使用用戶端程式庫中的 Go 設定說明進行操作。詳情請參閱 Pub/Sub Go API 參考說明文件。
Java
在嘗試這個範例之前,請先按照 快速入門:使用用戶端程式庫中的操作說明設定 Java 環境。詳情請參閱 Pub/Sub Java API 參考說明文件。
Node.js
在嘗試這個範例之前,請先按照 快速入門:使用用戶端程式庫中的操作說明設定 Node.js 環境。詳情請參閱 Pub/Sub Node.js API 參考說明文件。
Python
在嘗試這個範例之前,請先按照 快速入門:使用用戶端程式庫中的操作說明設定 Python 環境。詳情請參閱 Pub/Sub Python API 參考說明文件。
Ruby
在試用這個範例之前,請先按照 快速入門:使用用戶端程式庫中的 Go 設定說明進行操作。詳情請參閱 Pub/Sub Go API 參考說明文件。
一元拉取程式碼範例
C++
在嘗試這個範例之前,請先按照 快速入門:使用用戶端程式庫中的操作說明設定 C++ 環境。詳情請參閱 Pub/Sub C++ API 參考說明文件。
C#
在嘗試這個範例之前,請先按照 快速入門:使用用戶端程式庫中的操作說明設定 C# 環境。詳情請參閱 Pub/Sub C# API 參考說明文件。
Java
在嘗試這個範例之前,請先按照 快速入門:使用用戶端程式庫中的操作說明設定 Java 環境。詳情請參閱 Pub/Sub Java API 參考說明文件。
Node.js
在嘗試這個範例之前,請先按照 快速入門:使用用戶端程式庫中的操作說明設定 Node.js 環境。詳情請參閱 Pub/Sub Node.js API 參考說明文件。
PHP
在嘗試這個範例之前,請先按照 快速入門:使用用戶端程式庫中的操作說明設定 Node.js 環境。詳情請參閱 Pub/Sub Node.js API 參考說明文件。
Ruby
在嘗試這個範例之前,請先按照 快速入門:使用用戶端程式庫中的操作說明設定 Ruby 環境。詳情請參閱 Pub/Sub Ruby API 參考說明文件。
通訊協定
要求:
POST https://pubsub.googleapis.com/v1/projects/myproject/subscriptions/mysubscription:pull
{
"returnImmediately": "false",
"maxMessages": "1"
}
回應:
200 OK
{
"receivedMessages": [{
"ackId": "dQNNHlAbEGEIBERNK0EPKVgUWQYyODM2LwgRHFEZDDsLRk1SK...",
"message": {
"data": "SGVsbG8gQ2xvdWQgUHViL1N1YiEgSGVyZSBpcyBteSBtZXNzYWdlIQ==",
"messageId": "19917247034"
}
}]
}
要求:
POST https://pubsub.googleapis.com/v1/projects/myproject/subscriptions/mysubscription:acknowledge
{
"ackIds": [
"dQNNHlAbEGEIBERNK0EPKVgUWQYyODM2LwgRHFEZDDsLRk1SK..."
]
}
Python
在嘗試這個範例之前,請先按照 快速入門:使用用戶端程式庫中的操作說明設定 Python 環境。詳情請參閱 Pub/Sub Python API 參考說明文件。
Pub/Sub 會傳送訊息清單。如果清單中有多則訊息,Pub/Sub 會依據相同的排序鍵排序訊息。以下是一些重要注意事項:
在要求中設定
max_messages
的值,並不會保證會傳回max_messages
,即使積壓佇列中有多個訊息也是如此。Pub/Sub Pull API 可能會傳回少於max_messages
的值,以便減少可立即傳送的訊息傳送延遲時間。請勿將回應訊息數為 0 的拉取回應,視為 backlog 中沒有任何訊息的指標。您可能會收到回應,其中包含 0 則訊息,且後續要求會傳回訊息。
為了讓一元提取模式達到低延遲的訊息提交,請務必具備許多同時未解決的提取要求。隨著主題總處理量增加,就必須擁有更多提取要求。一般來說,對延遲時間敏感的應用程式,比較適合使用 StreamingPull 模式。
配額與限制
Pull 和 StreamingPull 連線都受配額和限制的約束。詳情請參閱「Pub/Sub 配額與限制」。
後續步驟
為主題建立提取訂閱項目。
排解提取訂閱問題。
使用 gcloud CLI 建立或修改訂閱項目。
使用 REST API 建立或修改訂閱項目。
使用 RPC API 建立或修改訂閱項目。