本頁說明如何建立含有篩選條件的 Pub/Sub 訂閱項目。
當您透過含有篩選條件的訂閱項目接收訊息時,您只會收到符合篩選條件的訊息。Pub/Sub 服務會自動確認不符合篩選條件的訊息。您可以依據屬性篩選訊息,但無法依據訊息中的資料篩選。
您可以為一個主題加入多個訂閱項目,每個訂閱項目可設有不同的篩選器。
舉例來說,如果您有一個主題會接收來自世界各地的新聞,可以設定訂閱項目,篩選出只來自特定區域的新聞。針對這項設定,您必須確保其中一個主題訊息屬性會傳達新聞發布區域。
當您透過含有篩選條件的訂閱項目接收訊息時,您不必為 Pub/Sub 自動確認的訊息支付傳出訊息費用。您必須為這些訊息支付訊息傳送費用和與搜尋功能相關的儲存空間費用。
使用篩選器建立訂閱
拉取和推送訂閱項目可以包含篩選器。所有訂閱者都能透過篩選器訂閱項目接收訊息,包括使用 StreamingPull API 的訂閱者。
您可以使用 Google Cloud 控制台、Google Cloud CLI、用戶端程式庫或 Pub/Sub API,建立含有篩選條件的訂閱。
控制台
如要建立含篩選條件的拉取訂閱,請按照下列步驟操作:
在 Google Cloud 控制台中,前往「訂閱項目」頁面。
按一下「Create Subscription」 (建立訂閱項目)。
輸入「Subscription ID」(訂閱 ID)。
從下拉式選單中選擇或建立主題。訂閱項目會接收主題的訊息。
在「訂閱篩選器」部分,輸入篩選器運算式。
按一下 [建立]。
如要建立含篩選器的推播訂閱,請按照下列步驟操作:
在 Google Cloud 控制台中,前往「訂閱項目」頁面。
按一下「Create Subscription」 (建立訂閱項目)。
輸入「Subscription ID」(訂閱 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 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 訂閱項目)頁面。
按一下剛剛建立的訂閱項目。
在訂閱詳細資料頁面中,按一下「Replay messages」(重播訊息)。
如要使用「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:值的子字串