过滤消息

本页面介绍了如何创建订阅过滤条件。

使用过滤条件创建订阅后,订阅仅传送与过滤条件匹配的消息。Pub/Sub 会自动确认与过滤条件不匹配的消息。您可以按消息的属性过滤消息。

当您收到包含过滤条件的订阅的消息时,您无需为 Pub/Sub 自动确认的消息支付出站流量费用。在 Beta 版发布阶段的限定时间内,您不需要为这些消息支付消息传送费用。所有其他费用均需支付。

使用过滤条件创建订阅

您可以使用 gcloud 命令行工具或 Pub/Sub API 使用过滤条件创建订阅。

gcloud

要使用过滤条件创建订阅,请使用 gcloud beta pubsub subscriptions create 命令和 --message-filter 标志:

gcloud beta pubsub subscriptions create SUBSCRIPTION_ID \
  --topic=TOPIC_ID \
  --message-filter=FILTER

替换以下内容:

  • SUBSCRIPTION_ID:要创建的订阅的 ID
  • TOPIC_ID:要附加到订阅的主题的 ID
  • FILTER过滤语法中的表达式

协议

如需使用过滤条件创建订阅,请使用 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": TOPIC_ID,
  "filter": FILTER
}

替换以下内容:

  • TOPIC_ID:要附加到订阅的主题的 ID
  • FILTER过滤语法中的表达式

过滤条件的最大长度为 256 个字节。创建订阅后,您将无法修改过滤条件。积压指标可能包含与过滤条件不匹配的消息。

过滤语法

要过滤消息,请编写对属性运行的表达式。您可以编写与属性的键或值匹配的表达式。attributes 标识符用于选择消息中的属性。

例如,下表中的过滤条件选择了 domain 属性:

过滤 说明
attributes:domain 具有 domain 属性的消息
NOT attributes:domain 不含 domain 属性的消息
attributes.domain = "com" 具有 domain 属性和 com 值的消息
attributes.domain != "com" 不含 domain 属性和 com 值的消息
hasPrefix(attributes.domain, "co") 具有 domain 属性且值以 co 开头的消息
NOT hasPrefix(attributes.domain, "co") 不含 domain 属性且以 co 开头的值的消息

比较运算符

您可以使用以下比较运算符过滤属性:

  • :
  • =
  • !=

: 运算符匹配属性列表中的键。

attributes:KEY

等式运算符匹配键和值。该值必须是字符串字面量。

attributes.KEY = "VALUE"

具有等式运算符的表达式必须以键开头,等式运算符必须比较键和值。

  • 有效:过滤条件比较键和值

    attributes.domain = "com"
    
  • 无效:过滤条件的左侧是一个值

    "com" = attributes.domain
    
  • 无效:过滤条件比较两个键

    attributes.domain = attributes.website
    

键和值区分大小写,并且必须与属性完全匹配。如果键包含的字符不是连字符、下划线或字母数字字符,请使用字符串字面量。

attributes."iana.org/language_tag" = "en"

要在过滤条件中使用反斜杠、引号和非打印字符,请转义字符串字面量中的字符。您还可以在字符串字面量中使用 Unicode、十六进制和八进制转义序列。

  • 有效:过滤条件对字符串字面量中的字符进行转义

    attributes:"\u307F\u3093\u306A"
    
  • 无效:过滤条件转义不含字符串字面量的字符

    attributes:\u307F\u3093\u306A
    

布尔运算符

您可以在过滤器中使用布尔运算符。例如,以下过滤条件适用于具有 iana.org/language_tag 属性但没有 domain 属性和 com 值的消息。

attributes:"iana.org/language_tag" AND NOT attributes.domain = "com"

NOT 运算符具有最高优先级。要组合 ANDOR 运算符,请使用括号和完整表达式。

  • 有效AND 和带括号的 OR 运算符

    attributes:"iana.org/language_tag" AND (attributes.domain = "net" OR attributes.domain = "org")
    
  • 无效:不带括号的 ANDOR 运算符

    attributes:"iana.org/language_tag" AND attributes.domain = "net" OR attributes.domain = "org"
    
  • 无效ANDOR 运算符结合使用不完整的表达式

    attributes.domain = "com" AND ("net" OR "org")
    

您也可以使用一元取反运算符代替 NOT 运算符。

attributes.domain = "com" AND -attributes:"iana.org/language_tag"

函数

hasPrefix 函数会过滤出值以子字符串开头的属性。

hasPrefix(attributes.KEY, "SUBSTRING")

替换以下内容:

  • KEY:属性的名称。
  • SUBSTRING:值的子字符串