本文將概略介紹提取訂閱項目、工作流程和相關聯的屬性。
在提取訂閱項目中,訂閱端的用戶端會從 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。
進一步瞭解 Pull REST 方法: 方法:projects.subscriptions.pull。
進一步瞭解 Pull RPC 方法:PullRequest 和 PullResponse。
訊息處理模式類型
為訂閱端選擇下列其中一種提取模式。
非同步提取模式
非同步提取模式會將訊息接收作業與訂閱端用戶端的訊息處理作業分離。大多數訂閱者用戶端預設會使用這個模式。非同步提取模式可以使用 StreamingPull API 或一元 Pull API。非同步提取作業也可以使用高階用戶端程式庫或低階自動產生的用戶端程式庫。
本文稍後會進一步說明用戶端程式庫。
同步提取模式
在同步擷取模式中,訊息的接收和處理作業會依序進行,彼此不會分離。因此,與 StreamingPull 相對的單元 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 用戶端程式庫的主要版本 (v2)。如果您仍在使用第 1 版程式庫,請參閱第 2 版遷移指南。如要查看第 1 版程式碼範例清單,請參閱 已淘汰的程式碼範例。
在試用這個範例之前,請先按照快速入門:使用用戶端程式庫中的 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 用戶端程式庫的主要版本 (v2)。如果您仍在使用第 1 版程式庫,請參閱第 2 版遷移指南。如要查看第 1 版程式碼範例清單,請參閱 已淘汰的程式碼範例。
在試用這個範例之前,請先按照快速入門:使用用戶端程式庫中的 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 用戶端程式庫的主要版本 (v2)。如果您仍在使用第 1 版程式庫,請參閱第 2 版遷移指南。如要查看第 1 版程式碼範例清單,請參閱 已淘汰的程式碼範例。
在試用這個範例之前,請先按照快速入門:使用用戶端程式庫中的 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 用戶端程式庫的主要版本 (v2)。如果您仍在使用第 1 版程式庫,請參閱第 2 版遷移指南。如要查看第 1 版程式碼範例清單,請參閱 已淘汰的程式碼範例。
在試用這個範例之前,請先按照快速入門:使用用戶端程式庫中的 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 則訊息,則不得將其做為積壓工作中沒有訊息的指標。你可能會在 0 則訊息的情況下收到回覆,並在後續要求中收到訊息。
如要透過一元提取模式達到低延遲的訊息提交,請務必具備許多同時未解決的提取要求。隨著主題總處理量增加,就必須擁有更多提取要求。一般來說,對延遲時間敏感的應用程式,比較適合使用 StreamingPull 模式。
配額與限制
Pull 和 StreamingPull 連線都受配額和限制規範。 詳情請參閱 Pub/Sub 配額與限制。
後續步驟
為主題建立提取訂閱項目。
排解提取訂閱問題。
使用 gcloud CLI 建立或修改訂閱項目。
使用 REST API 建立或修改訂閱項目。
使用 RPC API 建立或修改訂閱方案。