訂用帳戶規則 SQL 動作語法

SQL 動作是在訂用帳戶規則的篩選條件選取了訊息之後，用來操作訊息中繼資料。 此動作是依賴 SQL-92 標準子集的文字運算式。 動作運算式會與 Azure Resource Manager 範本中服務匯流排 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 或 user。
  • sys 值表示系統範圍，其中 <property_name> 是服務匯流排訊息上的任何屬性，如訊息、承載和序列化中所述。
  • user 值表示使用者範圍，其中 <property_name> 是傳送至服務匯流排時可在訊息上設定的自訂屬性金鑰。
  • 如果未指定 <scope>，則 user 範圍是預設範圍。

備註

嘗試存取不存在的系統屬性時會發生錯誤，而嘗試存取不存在的使用者屬性時不會發生錯誤。 反之，不存在的使用者屬性會在內部評估為未知的值。 未知的值在運算子評估期間會特別處理。

property_name

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

引數

<regular_identifier> 是由下列規則運算式所表示的字串︰

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

其表示任何以字母開頭且後面跟著一或多個底線/字母/數字的字串。

[:IsLetter:] 表示分類為 Unicode 字母的任何 Unicode 字元。 如果 c 為 Unicode 字母，System.Char.IsLetter(c) 會傳回 true。

[:IsDigit:] 表示分類為十進位數字的任何 Unicode 字元。 如果 c 為 Unicode 數字，System.Char.IsDigit(c) 會傳回 true。

<regular_identifier> 不能是保留的關鍵字。

<delimited_identifier> 是使用左/右方括弧 ([]) 括住的任何字串。 右方括弧會以兩個右方括弧代表。 以下為 <delimited_identifier>的範例：

[Property With Space]  
[HR-EmployeeID]  
  

<quoted_identifier> 是以雙引號括住的任何字串。 識別項中的雙引號會以兩個雙引號表示。 不建議使用引號識別項，因為其容易與字串常數造成混淆。 盡可能使用分隔的識別碼。 以下是 <quoted_identifier> 的範例：

"Contoso & Northwind"  

模式

<pattern> ::=  
      <expression>  

備註

<pattern> 必須是評估為字串的運算式。 其是用作 LIKE 運算子的模式。 它可以包含下列萬用字元︰

• %：任何含有零或多個字元的字串。
• _︰任何單一字元。

escape_char

<escape_char> ::=  
      <expression>  

備註

<escape_char> 必須是評估為字串為 1 的運算式。 其是用作 LIKE 運算子的逸出字元。

例如，property LIKE 'ABC\%' ESCAPE '\' 符合 ABC% 而不是以 ABC開頭的字串。

持續性

<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。

  以下是 decimal 常數的範例：

  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 會盡可能執行隱含轉換。
• 如果參考不存在的系統屬性，動作就會失敗。
• 如果參考不存在的使用者屬性，動作不會失敗。
• 不存在的使用者屬性會在內部評估為「不明」，評估運算子時遵循與 SQLRuleFilter 相同的語意。

重點

以下是一些重點：

• 只能修改訊息上的屬性。
• 所有使用者屬性都可加以修改。
• 所有可公開更新的系統屬性也可加以修改，例如 ReplyTo 和 CorreationId，但建議您不要在規則動作中更改系統屬性。 由於回溯相容性原因，仍然允許更改。
• 設定屬性時，只允許數字、布林值和字串常值。 字串常值又會根據所修改的屬性轉換為類型。 如果所設定的屬性尚未存在，則不會從字串進行類型轉換。 如果要修改的屬性已經存在，而且其值是下列其中一種類型：Guid、DateTimeOffset、TimeSpan、Uri、DateTime，則字元串常值會轉換為該類型，並設定為屬性值。 為了更加具體，動作會嘗試將字串常值轉換為屬性的類型。 如果成功，則會設定屬性。 否則，規則動作評估會擲回例外狀況，而且訊息是信件無效。

下一步

• SQLRuleAction (.NET)
• SqlRuleAction (Java)
• SqlRuleAction (JavaScript)
• az servicebus topic subscription rule
• New-AzServiceBusRule