Sintassi dell'azione SQL della regola di sottoscrizione

  • Articolo

Un'azione SQL viene usata per modificare i metadati dei messaggi dopo che un messaggio è stato selezionato da un filtro di una regola di sottoscrizione. Si tratta di un'espressione di testo che si appoggia a un subset dello standard SQL-92. Le espressioni di azione vengono usate con l'elemento sqlExpression della proprietà 'action' di un bus di servizio Rule in un modello di Azure Resource Manager o con l'argomento del comando dell'interfaccia della riga di comando di --action-sql-expression Azure az servicebus topic subscription rule create e diverse funzioni SDK che consentono la gestione delle regole di sottoscrizione.

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

Argomenti

  • <scope> è una stringa facoltativa che indica l'ambito di <property_name>. I valori validi sono sys o user.
    • Il sys valore indica l'ambito di sistema in cui <property_name> è una delle proprietà del messaggio bus di servizio come descritto in Messaggi, payload e serializzazione.
    • Il user valore indica l'ambito utente in cui <property_name> è una chiave delle proprietà personalizzate che è possibile impostare sul messaggio quando si invia a bus di servizio.
    • L'ambito user è l'ambito predefinito se <scope> non è specificato.

Osservazioni:

Un tentativo di accesso a una proprietà di sistema inesistente è un errore, mentre un tentativo di accesso a una proprietà utente inesistente non è un errore. Una proprietà utente inesistente viene invece valutata internamente come valore sconosciuto. Un valore sconosciuto viene gestito in modo speciale durante la valutazione degli operatori.

property_name

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

Argomenti

<regular_identifier> è una stringa rappresentata dall'espressione regolare seguente:

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

Significa che qualsiasi stringa che inizia con una lettera e viene seguita da uno o più caratteri di sottolineatura/lettera/cifra.

[:IsLetter:] indica qualsiasi carattere Unicode classificato come lettera Unicode. System.Char.IsLetter(c) restituisce true se c è una lettera Unicode.

[:IsDigit:] indica qualsiasi carattere Unicode classificato come cifra decimale. System.Char.IsDigit(c) restituisce true se c è una cifra Unicode.

Un <regular_identifier> oggetto non può essere una parola chiave riservata.

<delimited_identifier> è qualsiasi stringa racchiusa tra parentesi quadra aperta e parentesi quadra chiusa ([]). Una parentesi quadra chiusa è rappresentata con due parentesi quadre chiuse. Di seguito sono riportati esempi di <delimited_identifier>:

[Property With Space]  
[HR-EmployeeID]

<quoted_identifier> è qualsiasi stringa racchiusa tra virgolette doppie. Le virgolette doppie nell'identificatore sono rappresentate con due virgolette doppie. Non è consigliabile usare identificatori tra virgolette perché può essere facilmente confusa con una costante stringa. Usare se possibile un identificatore delimitato. Ecco un esempio di <quoted_identifier>:

"Contoso & Northwind"

Modello

<pattern> ::=  
      <expression>

Osservazioni:

<pattern> deve essere un'espressione valutata come stringa. Viene usato come modello per l'operatore LIKE. e può contenere i caratteri jolly seguenti.

  • %: qualsiasi stringa di zero o più caratteri.
  • _: qualsiasi carattere singolo.

escape_char

<escape_char> ::=  
      <expression>

Osservazioni:

<escape_char> deve essere un'espressione valutata come stringa di lunghezza 1. Viene usato come carattere di escape per l'operatore LIKE.

Ad esempio, property LIKE 'ABC\%' ESCAPE '\' corrisponde a ABC% anziché a una stringa che inizia con ABC.

Costante

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

Argomenti

  • <integer_constant> è una stringa di numeri che non sono racchiusi tra virgolette e non contengono punti decimali. I valori sono archiviati internamente come System.Int64 e seguono lo stesso intervallo.

    Di seguito sono riportati esempi di costanti di tipo long:

    1894  
2

  • <decimal_constant> è una stringa di numeri che non sono racchiusi tra virgolette e che contengono un separatore decimale. I valori sono archiviati internamente come System.Double e seguono lo stesso intervallo e la stessa precisione.

    In una versione futura, questo numero potrebbe essere archiviato in un tipo di dati diverso per supportare la semantica dei numeri esatta, pertanto non è consigliabile basarsi sul fatto che il tipo di dati sottostante sia System.Double per <decimal_constant>.

    Di seguito sono riportati esempi di costanti decimal:

    1894.1204  
2.0

  • <approximate_number_constant> è un numero scritto in notazione scientifica. I valori sono archiviati internamente come System.Double e seguono lo stesso intervallo e la stessa precisione. Di seguito sono riportati esempi di costanti numeriche approssimative:

    101.5E5  
0.5E-2

boolean_constant

<boolean_constant> :=  
      TRUE | FALSE

Osservazioni:

Le costanti booleane sono rappresentate dalle parole chiave TRUE e FALSE. I valori sono archiviati come System.Boolean.

string_constant

<string_constant>

Osservazioni:

Le costanti di tipo stringa sono racchiuse tra virgolette singole e includono qualsiasi carattere Unicode valido. Le virgolette singole incorporate in una costante di tipo stringa sono rappresentate con due virgolette singole.

Funzione

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

newid() Attualmente e property(name) sono le uniche funzioni supportate.

Osservazioni:

  • La newid() funzione restituisce un System.Guid oggetto generato dal System.Guid.NewGuid() metodo .
  • La funzione property(name) restituisce il valore della proprietà a cui viene fatto riferimento con name. Il valore di name può essere qualsiasi espressione valida che restituisce un valore stringa.

Esempi

Per esempi, vedere esempi di filtro bus di servizio.

Considerazioni

  • L'azione SET viene usata per creare una nuova proprietà o aggiornare il valore di una proprietà esistente.
  • REMOVE viene utilizzato per rimuovere una proprietà utente. È possibile rimuovere solo le proprietà utente, non le proprietà di sistema.
  • SET esegue la conversione implicita, se possibile, quando il tipo dell'espressione e il tipo della proprietà esistente sono diversi.
  • L'azione ha esito negativo se si fa riferimento a proprietà di sistema inesistenti.
  • L'azione non ha esito negativo se si fa riferimento a proprietà utente inesistenti.
  • Una proprietà utente inesistente viene valutata internamente come "Sconosciuto", seguendo la stessa semantica di SQLRuleFilter durante la valutazione degli operatori.

Aspetti importanti

Ecco alcuni punti importanti:

  • È possibile modificare solo le proprietà di un messaggio.
  • Tutte le proprietà utente possono essere modificate.
  • Tutte le proprietà di sistema aggiornabili pubblicamente possono anche essere modificate, ad ReplyTo esempio e CorreationId, ma è consigliabile non modificare le proprietà di sistema come parte di un'azione della regola. È comunque consentita per motivi di compatibilità con le versioni precedenti.
  • Quando si impostano proprietà, sono consentiti solo valori letterali numerici, booleani e stringa. Un valore letterale stringa a sua volta viene convertito in un tipo in base alla proprietà da modificare. Se la proprietà impostata non esiste già, non esiste alcuna conversione del tipo da stringa. Se la proprietà da modificare esiste già e il relativo valore è uno di questi tipi Guid, , TimeSpanDateTimeOffsetUri, , DateTimeil valore letterale stringa viene convertito in tale tipo e impostato come valore della proprietà. Per essere più specifico, l'azione tenta di convertire il valore letterale stringa nel tipo di proprietà. Se ha esito positivo, la proprietà viene impostata. In caso contrario, la valutazione dell'azione della regola genera un'eccezione e il messaggio viene inviato senza messaggi non recapitabili.

Passaggi successivi