Sintaxe da ação SQL da Regra de Assinatura

  • Artigo

Uma ação SQL é usada para manipular metadados de mensagem depois que uma mensagem é selecionada por um filtro de uma regra de assinatura. É uma expressão de texto que se baseia em um subconjunto do padrão SQL-92. Expressões de ação são usadas com o elemento sqlExpression da propriedade 'action' de um Barramento de Serviço Rule em um modelo do Azure Resource Manager, ou o argumento --action-sql-expression do comando az servicebus topic subscription rule create da CLI do Azure, e várias funções de SDK que permitem o gerenciamento de regras de assinatura.

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

Argumentos

  • <scope> é uma cadeia de caracteres opcional que indica o escopo do <property_name>. Os valores válidos são sys ou user.
    • O valor sys indica o escopo do sistema em que <property_name> é qualquer uma das propriedades na mensagem do Barramento de Serviço, conforme descrito em Mensagens, cargas e serialização.
    • O valor user indica o escopo do usuário em que <property_name> é uma chave das propriedades personalizadas que você pode definir na mensagem ao enviar para o Barramento de Serviço.
    • O escopo user será o escopo padrão se <scope> não for especificado.

Comentários

Uma tentativa de acessar uma propriedade de sistema inexistente é um erro, enquanto uma tentativa de acessar uma propriedade de usuário inexistente não é um erro. Em vez disso, uma propriedade de usuário inexistente é avaliada internamente como um valor desconhecido. Um valor desconhecido é tratado especialmente durante a avaliação de operador.

property_name

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

Argumentos

<regular_identifier> é uma cadeia de caracteres representada pela seguinte expressão regular:

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

Isso significa qualquer cadeia de caracteres que começa com uma letra e é seguida por um ou mais sublinhados/letras/dígitos.

[:IsLetter:] significa qualquer caractere Unicode categorizado como uma letra do Unicode. System.Char.IsLetter(c) retorna true se c é uma letra do Unicode.

[:IsDigit:] significa qualquer caractere Unicode categorizado como um dígito decimal. System.Char.IsDigit(c) retorna true se c é um dígito do Unicode.

Um <regular_identifier> não pode ser uma palavra-chave reservada.

<delimited_identifier> é qualquer cadeia de caracteres incluída em colchetes esquerdo/direito ([]). Um colchete direito é representado como dois colchetes direitos. Estes são exemplos de <delimited_identifier>:

[Property With Space]  
[HR-EmployeeID]

<quoted_identifier> é qualquer cadeia de caracteres entre aspas duplas. Aspas duplas no identificador são representadas como duas aspas duplas. Não é recomendável usar identificadores entre aspas, porque pode ser confundido facilmente com uma constante de cadeia de caracteres. Use um identificador delimitado, se possível. Aqui está um exemplo e <quoted_identifier>:

"Contoso & Northwind"

Padrão

<pattern> ::=  
      <expression>

Comentários

<pattern> deve ser uma expressão avaliada como uma cadeia de caracteres. É usado como um padrão para o operador LIKE. Pode conter os seguintes caracteres curinga:

  • %: qualquer cadeia de zero ou mais caracteres.
  • _: qualquer caractere único.

escape_char

<escape_char> ::=  
      <expression>

Comentários

<escape_char> deve ser uma expressão avaliada como uma cadeia de caracteres de comprimento 1. É usado como um caractere de escape para o operador LIKE.

Por exemplo, property LIKE 'ABC\%' ESCAPE '\' corresponde a ABC%, em vez de a uma cadeia de caracteres que começa com ABC.

Constante

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

Argumentos

  • <integer_constant> é uma cadeia de números que não são incluídos em aspas e que não contêm pontos decimais. Os valores são armazenados como System.Int64 internamente e seguem o mesmo intervalo.

    Estes são exemplos de constantes longas:

    1894  
2

  • <decimal_constant> é uma cadeia de números que não são incluídos em aspas e que contêm um ponto decimal. Os valores são armazenados como System.Double internamente e seguem o mesmo intervalo e a mesma precisão.

    Em uma versão futura, esse número poderá ser armazenado em outro tipo de dados para dar suporte à semântica de número exato; portanto, você não deve se basear no fato de que o tipo de dados subjacente é System.Double para <decimal_constant>.

    Estes são exemplos de constantes decimais:

    1894.1204  
2.0

  • <approximate_number_constant> é um número escrito em notação científica. Os valores são armazenados como System.Double internamente e seguem o mesmo intervalo e a mesma precisão. Estes são exemplos de constantes de número aproximado:

    101.5E5  
0.5E-2

boolean_constant

<boolean_constant> :=  
      TRUE | FALSE

Comentários

Constantes boolianas são representadas pelas palavras-chave TRUE ou FALSE. Os valores são armazenados como System.Boolean.

string_constant

<string_constant>

Comentários

Constantes de cadeia de caracteres são incluídas em aspas simples e incluem caracteres Unicode válidos. Uma aspa simples inserida em uma constante de cadeia de caracteres é representada como duas aspas simples.

Função

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

Atualmente, newid() e property(name) são as únicas funções com suporte.

Comentários

  • A função newid() retorna um System.Guid gerado pelo método System.Guid.NewGuid().
  • A função property(name) retorna o valor da propriedade referenciada por name. O valor name pode ser qualquer expressão válida que retorna um valor de cadeia de caracteres.

Exemplos

Para ver exemplos, consulte Exemplos de filtro do Barramento de Serviço.

Considerações

  • SET é usado para criar uma nova propriedade ou atualizar o valor de uma propriedade existente.
  • REMOVE é usado para remover uma propriedade do usuário. Somente as propriedades do usuário podem ser removidas, não as propriedades do sistema.
  • SET executa uma conversão implícita, se possível, quando o tipo de expressão e o tipo de propriedade existente são diferentes.
  • A ação falhará se propriedades inexistentes do sistema forem referenciadas.
  • A ação não falhará se propriedades de usuário inexistentes forem referenciadas.
  • Uma propriedade de usuário inexistente é avaliada como "Desconhecida" internamente, seguindo a mesma semântica que SQLRuleFilter ao avaliar operadores.

Pontos importantes

Veja a seguir alguns pontos importantes:

  • Somente as propriedades em uma mensagem podem ser modificadas.
  • Todas as propriedades do usuário podem ser modificadas.
  • Todas as propriedades do sistema atualizáveis publicamente também podem ser modificadas, como ReplyTo e CorreationId, mas recomendamos que você não altere as propriedades do sistema como parte de uma ação de regra. Ele ainda é permitido por motivos de compatibilidade com versões anteriores.
  • Ao definir propriedades, somente literais numéricos, boolianos e de cadeia de caracteres são permitidos. Um literal de cadeia de caracteres, por sua vez, é convertido em um tipo com base na propriedade que está sendo modificada. Se a propriedade que está sendo definida ainda não existir, não haverá conversão de tipo de cadeia de caracteres. Se a propriedade que está sendo modificada já existir e seu valor for um destes tipos: Guid, DateTimeOffset, TimeSpan, Uri ou DateTime, o literal da cadeia de caracteres será convertido nesse tipo e definido como o valor da propriedade. Para ser mais específico, a ação tenta converter o literal da cadeia de caracteres no tipo de propriedade. Se for bem-sucedida, a propriedade será definida. Caso contrário, a avaliação da ação de regra gera uma exceção e a mensagem é inativa.

Próximas etapas