本頁說明如何建立含有篩選器的 Pub/Sub 訂閱項目。
如果訂閱項目設有篩選器,您只會收到符合篩選條件的訊息。Pub/Sub 服務會自動確認不符合篩選條件的訊息。你可以依屬性篩選訊息,但無法依訊息中的資料篩選。
您可以將多個訂閱項目附加至主題,每個訂閱項目可以有不同的篩選器。
舉例來說,假設某個主題會收到來自世界各地的新聞,您可以設定訂閱項目,只篩選出特定區域發布的新聞。如要進行這項設定,請務必確認其中一個主題訊息屬性會傳達新聞發布區域。
如果訂閱項目設有篩選條件,當您收到訊息時,Pub/Sub 自動確認的訊息不會產生輸出訊息費用。您需要為這些訊息支付訊息傳送費用和搜尋相關儲存空間費用。
建立含有篩選器的訂閱項目
推送和提取訂閱項目都可以套用篩選器。所有訂閱者都能接收來自設有篩選器的訂閱項目訊息,包括使用 StreamingPull API 的訂閱者。
您可以使用 Google Cloud 控制台、Google Cloud CLI、用戶端程式庫或 Pub/Sub API,建立含有篩選條件的訂閱項目。
控制台
如要建立具有篩選器的提取訂閱項目,請按照下列步驟操作:
前往 Google Cloud 控制台的「Subscriptions」(訂閱項目) 頁面。
按一下「Create Subscription」 (建立訂閱項目)。
輸入訂閱 ID。
從下拉式選單中選擇或建立主題。訂閱項目會接收來自主題的訊息。
在「訂閱篩選器」部分,輸入篩選器運算式。
點選「建立」。
如要建立含有篩選器的推送訂閱項目,請按照下列步驟操作:
前往 Google Cloud 控制台的「Subscriptions」(訂閱項目) 頁面。
按一下「Create Subscription」 (建立訂閱項目)。
輸入訂閱 ID。
從下拉式選單中選擇或建立主題。訂閱項目會接收來自主題的訊息。
在「傳送類型」部分,按一下「推送」。
在「Endpoint URL」(端點網址) 欄位中,輸入推送端點的網址。
在「訂閱篩選器」部分,輸入篩選器運算式。
點選「建立」。
gcloud
如要建立具有篩選條件的提取訂閱項目,請使用 gcloud pubsub subscriptions create
指令搭配 --message-filter
旗標:
gcloud pubsub subscriptions create SUBSCRIPTION_ID \ --topic=TOPIC_ID \ --message-filter='FILTER'
更改下列內容:
- SUBSCRIPTION_ID:要建立的訂閱項目 ID
- TOPIC_ID:要附加至訂閱項目的主題 ID
- FILTER:篩選語法中的運算式
如要建立含有篩選器的推送訂閱項目,請使用 gcloud pubsub subscriptions create
指令搭配 --push-endpoint
和 --message-filter
旗標:
gcloud pubsub subscriptions create SUBSCRIPTION_ID \ --topic=TOPIC_ID \ --push-endpoint=PUSH_ENDPOINT \ --message-filter='FILTER'
更改下列內容:
- SUBSCRIPTION_ID:要建立的訂閱項目 ID
- TOPIC_ID:要附加至訂閱項目的主題 ID
- PUSH_ENDPOINT:推送訂閱者執行的伺服器網址
- FILTER:篩選語法中的運算式
REST
如要建立含有篩選器的訂閱項目,請使用 projects.subscriptions.create
方法。
PUT https://pubsub.googleapis.com/v1/projects/PROJECT_ID/subscriptions/SUBSCRIPTION_ID Authorization: Bearer $(gcloud auth print-access-token)
更改下列內容:
- PROJECT_ID:要在其中建立訂閱項目的專案 ID
- SUBSCRIPTION_ID:要建立的訂閱項目 ID
如要建立具有篩選器的提取訂閱項目,請在要求主體中指定篩選器:
{ "topic": "projects/PROJECT_ID/topics/TOPIC_ID", "filter": "FILTER" }
更改下列內容:
- PROJECT_ID:含有主題的專案 ID
- TOPIC_ID:要附加至訂閱項目的主題 ID
- FILTER:篩選語法中的運算式
如要建立含有篩選器的推送訂閱,請在要求主體中指定推送端點和篩選器:
{ "topic": "projects/PROJECT_ID/topics/TOPIC_ID", "pushConfig": { "pushEndpoint": "PUSH_ENDPOINT" }, "filter": "FILTER" }
更改下列內容:
- PROJECT_ID:含有主題的專案 ID
- TOPIC_ID:要附加至訂閱項目的主題 ID
- PUSH_ENDPOINT:推送訂閱者執行的伺服器網址
- FILTER:篩選語法中的運算式
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 參考說明文件。
PHP
在試用這個範例之前,請先按照快速入門:使用用戶端程式庫中的 PHP 設定說明進行操作。 詳情請參閱 Pub/Sub PHP API 參考說明文件。
Python
在試用這個範例之前,請先按照快速入門:使用用戶端程式庫中的 Python 設定操作說明來進行。詳情請參閱 Pub/Sub Python API 參考說明文件。
Ruby
在試用這個範例之前,請先按照快速入門:使用用戶端程式庫的操作說明設定 Ruby 環境。詳情請參閱 Pub/Sub Ruby API 參考說明文件。
篩選條件的長度上限為 256 個位元組。篩選器是訂閱項目的不可變更屬性。訂閱建立完成後,您將無法更新訂閱項目來修改篩選器。
篩選器對待處理事項指標的影響
如要監控剛建立的訂閱項目,請參閱「使用篩選器監控訂閱項目」。
如果啟用篩選功能,積壓工作指標只會納入符合篩選條件的訊息資料。以下列出積壓工作指標:
subscription/backlog_bytes
subscription/unacked_bytes_by_region
subscription/num_undelivered_messages
subscription/num_unacked_messages_by_region
subscription/oldest_unacked_message_age
subscription/oldest_unacked_message_age_by_region
topic/unacked_bytes_by_region
topic/num_unacked_messages_by_region
topic/oldest_unacked_messages_age_by_region
如要進一步瞭解這些指標,請參閱 Pub/Sub 指標清單。
更新訂閱項目的篩選器
您無法更新現有訂閱項目的篩選器。 請改用這個解決方法。
為要變更篩選器的訂閱項目拍攝快照。
如要進一步瞭解如何使用控制台拍攝快照,請參閱「建立快照」一文。
使用新篩選條件建立新訂閱項目。
如要進一步瞭解如何建立含有篩選器的訂閱項目,請參閱「建立含有篩選器的訂閱項目」。
前往 Google Cloud 控制台的「Pub/Sub subscriptions」(Pub/Sub 訂閱項目) 頁面。
按一下剛建立的訂閱項目。
在訂閱詳細資料頁面中,按一下「重播訊息」。
如要「Seek」(搜尋),請按一下「To a snapshot」(快照)。
選取您在步驟 1 中為原始訂閱項目建立的快照,然後按一下「Seek」(搜尋)。
轉換期間不會遺失任何訊息。
將所有訂閱者改用新方案。
完成這項程序後,即可刪除原始訂閱方案。
建立篩選器的語法
如要篩選訊息,請撰寫對屬性執行的運算式。您可以編寫運算式,比對屬性的鍵或值。attributes
識別碼會選取訊息中的屬性。
舉例來說,下表中的篩選器會選取 name
屬性:
篩選器 | 說明 |
---|---|
attributes:name |
含有 name 屬性的訊息 |
NOT attributes:name |
沒有 name 屬性的訊息 |
attributes.name = "com" |
具有 name 屬性和 com 值的訊息 |
attributes.name != "com" |
缺少 name 屬性和 com 值的訊息 |
hasPrefix(attributes.name, "co") |
含有 name 屬性且值開頭為 co 的訊息 |
NOT hasPrefix(attributes.name, "co") |
缺少 name 屬性,且值開頭為 co 的訊息 |
篩選運算式的比較運算子
您可以使用下列比較運算子篩選屬性:
:
=
!=
:
運算子會比對屬性清單中的鍵。
attributes:KEY
等號運算子會比對鍵和值。值必須是字串常值。
attributes.KEY = "VALUE"
使用等號運算子的運算式開頭必須是鍵,且等號運算子必須比較鍵和值。
有效:篩選器會比較鍵和值
attributes.name = "com"
無效:篩選器左側為值
"com" = attributes.name
無效:篩選器會比較兩個鍵
attributes.name = attributes.website
鍵和值有大小寫之分,且必須與屬性完全相符。如果鍵含有連字號、底線或英數字元以外的字元,請使用字串常值。
attributes."iana.org/language_tag" = "en"
如要在篩選器中使用反斜線、引號和非列印字元,請逸出字串常值中的字元。您也可以在字串常值中使用 Unicode、十六進位和八進位逸出序列。
有效:篩選字串常值中的逸出字元
attributes:"\u307F\u3093\u306A"
無效:篩選器會逸出字元,但沒有字串常值
attributes:\u307F\u3093\u306A
篩選器運算式的布林運算子
您可以在篩選條件中使用布林運算子 AND
、NOT
和 OR
。運算子必須全部為大寫字母。舉例來說,下列篩選條件適用於具有 iana.org/language_tag
屬性,但沒有 name
屬性和 com
值的訊息。
attributes:"iana.org/language_tag" AND NOT attributes.name = "com"
NOT
運算子的優先順序最高,如要合併 AND
和 OR
運算子,請使用括號並完成運算式。
有效:含括號的
AND
和OR
運算子attributes:"iana.org/language_tag" AND (attributes.name = "net" OR attributes.name = "org")
無效:沒有括號的
AND
和OR
運算子attributes:"iana.org/language_tag" AND attributes.name = "net" OR attributes.name = "org"
無效:
AND
和OR
運算子會合併不完整的運算式attributes.name = "com" AND ("net" OR "org")
您也可以使用一元減號運算子,取代 NOT
運算子。
attributes.name = "com" AND -attributes:"iana.org/language_tag"
篩選運算式的函式
您可以使用 hasPrefix
函式,篩選出值開頭為子字串的屬性。篩選器中僅支援 hasPrefix
函式。
hasPrefix
函式支援前置字串比對,但不支援一般規則運算式。
hasPrefix(attributes.KEY, "SUBSTRING")
更改下列內容:
- KEY:屬性名稱
- SUBSTRING:值的子字串