サブスクリプション ルールの SQL アクション構文

  • [アーティクル]

"SQL アクション" は、メッセージがサブスクリプション ルールのフィルターによって選択された後にメッセージ メタデータを操作するために使用されます。 これは、SQL-92 標準のサブセットに基づくテキスト式です。 アクション式は、Azure Resource Manager テンプレート内の Service Bus 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> は「メッセージ、ペイロード、およびシリアル化」で説明されている Service Bus メッセージのプロパティのいずれかです。
    • user 値はユーザー スコープを示します。ここで、<property_name> は Service Bus に送信するときにメッセージに設定できるカスタム プロパティのキーです。
    • <scope> が指定されていない場合、user スコープが既定のスコープです。

解説

存在しないシステム プロパティにアクセスしようとするとエラーになりますが、存在しないユーザー プロパティにアクセスしようとしてもエラーにはなりません。 代わりに、存在しないユーザー プロパティは不明な値として内部的に評価されます。 不明な値は演算子の評価時に特別に処理されます。

property_name

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

引数

<regular_identifier> は、次の正規表現で表される文字列です。

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

これは、文字で始まり、その後に 1 つ以上のアンダースコア/文字/数字が続くことを意味します。

[:IsLetter:] は、Unicode の文字として分類される任意の Unicode 文字を表します。 c が Unicode の文字の場合、System.Char.IsLetter(c) は true を返します。

[:IsDigit:] は、10 進数として分類される任意の Unicode 文字を表します。 c が Unicode の数字の場合、System.Char.IsDigit(c) は true を返します。

<regular_identifier> に予約キーワードを指定することはできません。

<delimited_identifier> は、左右の各かっこ ([]) で囲まれた任意の文字列です。 右角かっこは 2 つの右角かっこで表されます。 <delimited_identifier> の例を次に示します。

[Property With Space]  
[HR-EmployeeID]

<quoted_identifier> は、二重引用符で囲まれた任意の文字列です。 識別子の二重引用符は 2 つの二重引用符で表されます。 引用符で囲まれた識別子は、文字列定数と混同されやすい可能性があるので使用しないことをお勧めします。 可能であれば、区切られた識別子を使用してください。 こちらに <quoted_identifier> の例を示します。

"Contoso & Northwind"

パターン

<pattern> ::=  
      <expression>

解説

<pattern> は、文字列として評価される式である必要があります。 これは LIKE 演算子のパターンとして使用されます。 次のワイルドカード文字を含めることができます。

  • %: 0 個以上の文字で構成される任意の文字列。
  • _: 1 つの任意の文字。

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 であることに依存しないでください。

    10 進定数の例を次に示します。

    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 文字が含まれます。 文字列定数に組み込む単一引用符は、2 つの単一引用符で表されます。

関数

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

現在、サポートされている関数は newid() と property(name) のみです。

解説

  • newid() 関数は、System.Guid.NewGuid() メソッドによって生成された System.Guid を返します。
  • property(name) 関数は、name によって参照されるプロパティの値を返します。 name 値には、文字列値を返す任意の有効な式を指定できます。

例

例については、Service Bus フィルターの例を参照してください。

考慮事項

  • SET は、新しいプロパティを作成するとき、または既存のプロパティの値を更新するときに使用します。
  • REMOVE は、ユーザー プロパティを削除するときに使います。 削除できるのはユーザー プロパティのみで、システム プロパティは削除できません。
  • 式の型と既存のプロパティの型が異なる場合、可能であれば、SET は暗黙的な変換を実行します。
  • 存在しないシステム プロパティが参照されている場合、アクションは失敗します。
  • 存在しないユーザー プロパティが参照されていても、アクションは失敗しません。
  • 存在しないユーザー プロパティは内部的に "Unknown" と評価され、演算子を評価するときに SQLRuleFilter と同じセマンティクスに従います。

重要なポイント

重要な点がいくつかあります。

  • メッセージのプロパティのみを変更できます。
  • すべてのユーザー プロパティは変更できます。
  • ReplyTo や CorreationId など、パブリックに更新可能なすべてのシステム プロパティも変更できますが、ルール アクションの一部としてシステム プロパティを変更しないことをお勧めします。 下位互換性の理由から、引き続き許可されています。
  • プロパティを設定する場合、数値、ブール値、および文字列リテラルのみを使用できます。 文字列リテラルは、変更されるプロパティに基づいて型に変換されます。 設定されるプロパティがまだ存在しない場合、文字列からの型変換は行われません。 変更するプロパティがすでに存在し、その値が Guid、DateTimeOffset、TimeSpan、Uri、DateTime のいずれかの型である場合、文字列リテラルがその型に変換され、プロパティ値として設定されます。 より具体的に言うと、アクションは文字列リテラルをプロパティの型に変換しようとします。 成功すると、プロパティが設定されます。 それ以外の場合、ルール アクションの評価で例外がスローされ、メッセージは配信不能になります。

次のステップ