本页面介绍了如何创建带过滤条件的 Pub/Sub 订阅。
当您通过过滤条件接收订阅消息时,您只会收到与过滤条件匹配的消息。Pub/Sub 服务会自动确认与过滤条件不匹配的消息。您可以 按属性过滤邮件 而不是消息中的数据
一个账号可以关联多个订阅 主题和每个订阅可以有不同的过滤条件。
例如,如果您有一个主题用于接收来自世界各地的新闻,则可以配置订阅,以过滤出仅来自特定地区发布的新闻。对于此配置,您必须确保某个主题消息属性传达了新闻发布区域。
当您接收来自使用过滤器的订阅的消息时 出站消息费用,针对 Pub/Sub 会自动确认。您需要支付消息传送费用以及跳转相关存储费用。
使用过滤条件创建订阅
拉取和推送订阅可以包含过滤条件。所有订阅者都可以接收具有过滤条件的订阅的消息,包括使用 StreamingPull API 的订阅者。
您可以使用 Google Cloud 控制台、Google Cloud CLI、客户端库或 Pub/Sub API 创建具有过滤条件的订阅。
控制台
要创建具有过滤条件的拉取订阅,请按以下步骤操作:
在 Google Cloud 控制台中,进入订阅页面。
点击创建订阅。
输入订阅 ID。
从下拉菜单中选择或创建一个主题。订阅将接收来自该主题的消息。
在订阅过滤条件部分,输入过滤条件表达式。
点击创建。
要创建具有过滤条件的推送订阅,请按以下步骤操作:
gcloud
要创建具有过滤条件的拉取订阅,请使用带有 --message-filter
标志的 gcloud pubsub subscriptions create
命令:
gcloud pubsub subscriptions create SUBSCRIPTION_ID \ --topic=TOPIC_ID \ --message-filter='FILTER'
请替换以下内容:
- SUBSCRIPTION_ID:要创建的订阅的 ID
- TOPIC_ID:要附加到订阅的主题的 ID
- FILTER:过滤语法中的表达式
要创建具有过滤条件的推送订阅,请使用带有 --push-endpoint
和 --message-filter
标志的 gcloud pubsub subscriptions create
命令:
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 订阅页面。
点击您刚刚创建的订阅。
在“订阅详情”页面中,点击重放消息。
对于跳转,点击到快照。
选择您为原始订阅创建的快照 然后点击跳转。
在转换过程中,您不会丢失任何消息。
更改所有订阅者以使用新订阅。
完成此过程后,您可以继续删除原始订阅。
用于创建过滤条件的语法
要过滤消息,请编写对属性运行的表达式。您可以编写与属性的键或值匹配的表达式。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:值的子字符串