Partager via

Syntaxe d’action SQL pour les règles d’abonnement

  • Article

Une action SQL permet de manipuler les métadonnées d’un message après qu’un message a été sélectionné par un filtre d’une règle d’abonnement. Il s’agit d’une expression textuelle qui s’appuie sur un sous-ensemble de la norme SQL-92. Les expressions d’action sont utilisées avec l’élément sqlExpression de la propriété « action » d’un objet Rule Service Bus dans un modèle Azure Resource Manager, avec l’argument --action-sql-expression de la commande Azure CLI az servicebus topic subscription rule create et avec plusieurs fonctions de Kit de développement logiciel (SDK) qui autorisent la gestion des règles d’abonnement.

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

Arguments

  • <scope> est une chaîne facultative qui indique la portée de <property_name>. Les valeurs valides sont sys ou user.
    • La valeur sys indique l’étendue du système où <property_name> est l’une des propriétés sur le message Service Bus, comme décrit dans Messages, charges utiles et sérialisation.
    • La valeur user indique l’étendue utilisateur, où <property_name> est une clé des propriétés personnalisées que vous pouvez définir sur le message lors d’un envoi à Service Bus.
    • L’étendue de user est l’étendue par défaut si <scope> n’est pas spécifié.

Notes

Une tentative d’accès à une propriété système inexistante est une erreur, tandis qu’une tentative d’accès à une propriété utilisateur inexistante n’en est pas une. Au lieu de cela, une propriété d’utilisateur inexistante est évaluée en interne en tant que valeur inconnue. Une valeur inconnue est traitée spécialement lors de l’évaluation de l’opérateur.

property_name

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

Arguments

<regular_identifier> est une chaîne est représentée par l’expression régulière suivante :

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

Cela signifie toute chaîne commençant par une lettre et suivie par un(e) ou plusieurs traits de soulignement/lettres/chiffres.

[:IsLetter:] signifie tout caractère Unicode classé en tant que lettre Unicode. System.Char.IsLetter(c) renvoie true si c est une lettre Unicode.

[:IsDigit:] signifie tout caractère Unicode classé en tant que chiffre décimal. System.Char.IsDigit(c) renvoie true si c est un chiffre Unicode.

Un <regular_identifier> ne peut pas être un mot clé réservé.

<delimited_identifier> correspond à toute chaîne placée entre crochets ([]). Un crochet droit est représenté par deux crochets droits. Voici quelques exemples de <delimited_identifier> :

[Property With Space]  
[HR-EmployeeID]

<quoted_identifier> correspond à toute chaîne placée entre guillemets doubles. Un guillemet double dans l’identificateur est représenté par deux guillemets doubles. Il est déconseillé d’utiliser des identificateurs entre guillemets, qui peuvent être facilement confondus avec une constante de chaîne. Utilisez si possible un identificateur délimité. Voici un exemple de <quoted_identifier> :

"Contoso & Northwind"

Modèle

<pattern> ::=  
      <expression>

Remarques

<pattern> doit être une expression évaluée comme chaîne. Il est utilisé comme modèle pour l’opérateur LIKE. Il peut contenir les caractères génériques suivants :

  • % : Une chaîne de zéro ou plusieurs caractères.
  • _ : n’importe quel caractère unique.

escape_char

<escape_char> ::=  
      <expression>

Remarques

<escape_char> doit être une expression évaluée comme chaîne dont la longueur est 1. Il est utilisé comme caractère d’échappement pour l’opérateur LIKE.

Par exemple, property LIKE 'ABC\%' ESCAPE '\' correspond à ABC% au lieu d’une chaîne qui commence par ABC.

Constant

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

Arguments

  • <integer_constant> est une chaîne de nombres qui n’est pas entourée de guillemets et ne contient pas de décimales. Les valeurs sont stockées en tant que System.Int64 en interne et suivent la même plage.

    Voici quelques exemples de constantes longues :

    1894  
2

  • <decimal_constant> est une chaîne de nombres qui n’est pas entourée de guillemets et qui contient une décimale. Les valeurs sont stockées en tant que System.Double en interne et suivent la même plage/précision.

    Dans une version ultérieure, ce nombre pourrait être stocké dans un autre type de données pour prendre en charge la sémantique exacte des nombres. Vous n’aurez donc pas à compter sur le fait que le type de données sous-jacent soit System.Double pour <decimal_constant>.

    Voici quelques exemples de constantes décimales :

    1894.1204  
2.0

  • <approximate_number_constant> est un nombre écrit de manière scientifique. Les valeurs sont stockées en tant que System.Double en interne et suivent la même plage/précision. Voici des exemples de constantes numériques approximatives :

    101.5E5  
0.5E-2

boolean_constant

<boolean_constant> :=  
      TRUE | FALSE

Remarques

Les constantes booléennes sont représentées par les mots clés TRUE ou FALSE. Les valeurs sont stockées en tant que System.Boolean.

string_constant

<string_constant>

Remarques

Les constantes de chaîne sont placées entre guillemets simples et incluent tout caractère Unicode valide. Un guillemet simple intégré à une constante de chaîne est représenté par deux guillemets simples.

Fonction

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

Actuellement, newid() et property(name) sont les seules fonctions prises en charge.

Notes

  • La fonction newid() renvoie un System.Guid généré par la méthode System.Guid.NewGuid().
  • La fonction property(name) renvoie la valeur de la propriété référencée par name. La valeur name peut être toute expression valide renvoyant une valeur de chaîne.

Exemples

Pour obtenir des exemples, consultez Exemples de filtres Service Bus.

Considérations

  • SET est utilisé pour créer une nouvelle propriété ou mettre à jour la valeur d’une propriété existante.
  • SUPPRIMER permet de supprimer une propriété utilisateur. Seules les propriétés utilisateur peuvent être supprimées, pas les propriétés système.
  • SET effectue si possible une conversion implicite lorsque le type d’expression et le type de propriété existant sont différents.
  • L’action échoue s’il est fait référence à des propriétés de système inexistantes.
  • L’action réussit s’il est fait référence à des propriétés d’utilisateur inexistantes.
  • Une propriété d’utilisateur inexistante est évaluée comme « Inconnue » en interne, suivant la même sémantique que SQLRuleFilter lors de l’évaluation des opérateurs.

Points importants

Voici quelques points importants :

  • Seules les propriétés d’un message peuvent être modifiées.
  • Toutes les propriétés utilisateur peuvent être modifiées.
  • Toutes les propriétés système pouvant être mises à jour publiquement peuvent également être modifiées, comme ReplyTo et CorreationId, mais nous vous recommandons de ne pas modifier les propriétés système dans le cadre d’une action de règle. Cela reste autorisé pour des raisons de compatibilité descendante.
  • Lorsque vous définissez des propriétés, seuls les littéraux de chaîne, numériques et booléens sont autorisés. Un littéral de chaîne est converti en type en fonction de la propriété en cours de modification. Si la propriété à définir n’existe pas encore, il n’y a pas de conversion de type à partir de la chaîne. Si la propriété en cours de modification existe déjà et que sa valeur est l’un de ces types : Guid, DateTimeOffset, TimeSpan, Uri ou DateTime ; le littéral de chaîne est converti en ce type et défini comme valeur de propriété. Pour être plus spécifique, l’action tente de convertir le littéral de chaîne en type de propriété. Si elle réussit, la propriété est définie. Sinon, l’évaluation de l’action de règle lève une exception et le message est en lettres mortes.

Étapes suivantes