订阅规则 SQL 操作语法

项目
12/26/2023

“SQL 操作”用于在订阅规则的筛选器选择消息后操作消息元数据。它是一个依赖于 SQL-92 标准子集的文本表达式。操作表达式与 Azure 资源管理器模板中服务总线 Rule 的“action”属性的 sqlExpression 元素一起使用，或者与 Azure CLI az servicebus topic subscription rule create 命令的 --action-sql-expression 参数以及几个允许管理订阅规则的 SDK 函数一起使用。

<statements> ::=
    <statement> [, ...n]

<statement> ::=
    <action> [;]
    Remarks
    -------
    Semicolon is optional.

<action> ::=
    SET <property> = <expression>
    REMOVE <property>

<expression> ::=
    <constant>
    | <function>
    | <property>
    | <expression> { + | - | * | / | % } <expression>
    | { + | - } <expression>
    | ( <expression> )

<property> := 
    [<scope> .] <property_name>

参数

<scope> 是一个可选字符串，指示 <property_name> 的范围。有效值为 sys or user进行求值的基于 SQL 语言的筛选器表达式。
- sys 值指示系统范围，其中的 <property_name> 是服务总线消息上的任何属性，如消息、有效负载和序列化中所述。
- user 值指示用户范围，其中 <property_name> 是可在发送到服务总线时在消息上设置的自定义属性的键。
- user 范围是默认范围（如果 <scope> 未指定）。

备注

尝试访问不存在的系统属性属于错误，而尝试访问不存在的用户属性不属于错误。不存在的用户属性在内部是作为未知值计算的。运算符求值期间会对未知值进行特殊处理。

property_name

<property_name> ::=  
     <identifier>  
     | <delimited_identifier>  
  
<identifier> ::=  
     <regular_identifier> | <quoted_identifier> | <delimited_identifier>

参数

<regular_identifier> 是字符串，由以下正则表达式表示：

[[:IsLetter:]][_[:IsLetter:][:IsDigit:]]*

它是指任何以字母开头且后跟一个或多个下划线/字母/数字的字符串。

[:IsLetter:] 是指分类为 Unicode 字母的任何 Unicode 字符。 System.Char.IsLetter(c) 返回 true（如果 c 为 Unicode 字母）。

[:IsDigit:] 是指分类为十进制数字的任何 Unicode 字符。 System.Char.IsDigit(c) 返回 true（如果 c 为 Unicode 数字）。

<regular_identifier> 不能是保留关键字。

<delimited_identifier> 是用左/右方括号 ([]) 括起来的任何字符串。右方括号以两个右方括号表示。下面是 <delimited_identifier>的示例：

[Property With Space]  
[HR-EmployeeID]

<quoted_identifier> 是指使用双引号引起来的任何字符串。标识符中的双引号以两个双引号表示。不建议使用带引号的标识符，因为很容易将其与字符串常量混淆。如果可能，请使用分隔标识符。下面是 <quoted_identifier> 的示例：

"Contoso & Northwind"

pattern

<pattern> ::=  
      <expression>

备注

<pattern> 必须是作为字符串进行求值的表达式。它用作 LIKE 运算符的模式。它可以包含以下通配符：

%：具有零个或多个字符的任何字符串。
_：任何单个字符。

escape_char

<escape_char> ::=  
      <expression>

备注

<escape_char> 必须是作为长度为 1 的字符串进行求值的表达式。它用作 LIKE 运算符的转义符。

例如，property LIKE 'ABC\%' ESCAPE '\' 匹配 ABC%，而不匹配以 ABC 开头的字符串。

constant

<constant> ::=  
      <integer_constant> | <decimal_constant> | <approximate_number_constant> | <boolean_constant> | NULL

参数

<integer_constant> 是指不使用引号引起来且不包含小数点的数字字符串。这些值作为 System.Int64 在内部存储，并具有相同的作用域。

下面是长常量的示例：
```
1894  
2  
```
<decimal_constant> 是指不使用引号引起来但包含小数点的数字字符串。这些值作为 System.Double 在内部存储，并具有相同的作用域/精度。

在未来版本中，此数字可能以其他数据类型存储，目的是支持确切的数字语义，因此不应依赖于 <decimal_constant> 的基础数据类型为 System.Double 这一事实。

下面是十进制常量的示例：
```
1894.1204  
2.0  
```
<approximate_number_constant> 是指使用科学记数法书写的数字。这些值作为 System.Double 在内部存储，并具有相同的作用域/精度。下面是近似数常量的示例：
```
101.5E5  
0.5E-2  
```

boolean_constant

<boolean_constant> :=  
      TRUE | FALSE

备注

布尔常量以关键字 TRUE 或 FALSE 表示。这些值作为 System.Boolean存储。

string_constant

<string_constant>

备注

字符串常量使用单引号引起来，并包含任何有效的 Unicode 字符。字符串常量中嵌入的单引号以两个单引号表示。

函数

<function> :=  
      newid() |  
      property(name) | p(name)

newid() property(name) 目前是唯一支持的函数。

备注

newid() 函数返回 System.Guid.NewGuid() 方法生成的 System.Guid。
property(name) 函数返回 name 所引用的属性的值。 name 值可以是返回字符串值的任何有效表达式。

示例

有关示例，请参阅服务总线筛选器示例。

注意事项

SET 用于创建新属性或更新现有属性的值。
REMOVE 用于移除属性。只能移除用户属性，而不能移除系统属性。
当表达式类型和现有的属性类型不同时，SET 会尽可能执行隐式转换。
如果引用了不存在的系统属性，操作会失败。
如果引用了不存在的用户属性，操作不会失败。
不存在的用户属性在内部的求值为“Unknown”，其遵循的语义与 SQLRuleFilter 相同（在对运算符求值时）。

要点

下面是一些要点：

只能修改消息的属性。
可以修改所有用户属性。
还可以修改所有可公开更新的系统属性，例如 ReplyTo 和 CorreationId，但我们建议不要更改作为规则操作的一部分的系统属性。出于向后兼容性原因，仍允许这样做。
设置属性时，只允许使用数值、布尔和字符串文本。字符串文本又根据要修改的属性转换为类型。如果要设置的属性尚不存在，则不存在来自字符串的类型转换。如果要修改的属性已存在，并且其值为下列类型 Guid、DateTimeOffset、TimeSpan Uri、DateTime 其中之一，则字符串文本将转换为该类型并设置为属性值。更具体地说，该操作会尝试将字符串文本转换为属性的类型。如果成功，则设置属性。否则，规则操作计算将引发异常，并且消息会成为死信。

通过