Modèles de messages

<ph type="x-smartling-placeholder"></ph> Vous consultez la documentation Apigee Edge.
Accédez à la page Documentation sur Apigee X. En savoir plus

Cette rubrique explique comment utiliser des modèles de message dans les proxys d'API et fournit des informations de référence sur cette fonction.

Qu'est-ce qu'un modèle de message ?

Un modèle de message vous permet d'effectuer une substitution de chaîne de variables dans certains éléments d'une règle et de TargetEndpoint. Cette fonctionnalité, si elle est compatible, vous permet de renseigner des chaînes de manière dynamique lorsqu'un proxy s'exécute.

Vous pouvez inclure n'importe quelle combinaison de références de variable de flux et de texte littéral dans un modèle de message. Les noms des variables de flux doivent être placés entre accolades, tandis que tout texte qui n'est pas entre accolades est généré sous forme de texte littéral.

Consultez également la section Où utiliser des modèles de message ?

Exemple

Par exemple, la règle AssignMessage vous permet d'utiliser un modèle de message dans l'élément <Payload> :

<AssignMessage name="set-dynamic-content">
  <AssignTo createNew="false" type="response"></AssignTo>
  <Set>
    <Payload contentType="application/json">
      {"name":"Alert", "message":"You entered an invalid username: {user.name}"}
    </Payload>
  </Set>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
</AssignMessage>

Dans l'exemple ci-dessus, la valeur de la variable de flux user.name (entre accolades) sera évalué et substitué dans la chaîne de charge utile au moment de l'exécution. Ainsi, par exemple, si user.name=jdoe, alors le message résultant dans la charge utile sera: You entered an invalid username: jdoe. Si la variable ne peut pas être résolue, une chaîne vide est renvoyée.

Exemple

Lorsqu'un quota est dépassé, il est recommandé de renvoyer un message pertinent à l'appelant. Ce est souvent utilisé avec une "règle d'erreur" afin de fournir un résultat pour fournir à l'appelant des informations sur le non-respect des quotas. Des modèles de messages sont utilisés dans la stratégie "Attribuer des messages" suivante pour insérer les informations sur les quotas de manière dynamique dans plusieurs éléments XML:

<AssignMessage name='AM-QuotaViolationMessage'>
  <Description>message for quota exceeded</Description>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <Set>
    <Headers>
      <Header name='X-Quota-Reset'>{ratelimit.Quota-1.expiry.time}</Header>
      <Header name='X-Quota-Allowed'>{ratelimit.Quota-1.allowed.count}</Header>
      <Header name='X-Quota-Available'>{ratelimit.Quota-1.available.count}</Header>
    </Headers>
    <Payload contentType='application/json'>{
  "error" : {
    "message" : "you have exceeded your quota",
    "clientId" : "{request.queryparam.apikey}"
  }
}
    </Payload>
    <StatusCode>429</StatusCode>
    <ReasonPhrase>Quota Exceeded</ReasonPhrase>
  </Set>
</AssignMessage>

Dans la règle AssignMessage, les éléments suivants de l'élément <Set> sont compatibles avec la modélisation des messages :

  • En-tête
  • QueryParam
  • FormParam
  • Charge utile
  • Version
  • Verbe
  • Chemin
  • StatusCode
  • ReasonPhrase

Encore une fois, notez que les variables de flux d'un modèle de message doivent être placées entre accolades.

Lorsque cette règle s'exécute :

  • Les éléments Header reçoivent les valeurs des variables de flux spécifiées.
  • La charge utile inclut une combinaison de texte littéral et de variables (l'élément client_id est renseigné de manière dynamique).
  • "StatusCode" et "ReasonPhrase" ne comportent que du texte littéral ; toutefois, ces éléments sont également compatibles avec la modélisation de messages si vous souhaitez l'utiliser.

Exemple

Dans une définition TargetEndpoint de proxy, les éléments enfants de <SSLInfo> sont compatibles avec la modélisation de messages. En suivant le même modèle que celui utilisé dans les règles, les variables de flux entre accolades sont remplacées lorsque le proxy s'exécute. 

<TargetEndpoint name="default">
  …
  <HTTPTargetConnection>
    <SSLInfo>
        <Enabled>{myvars.ssl.enabled}</Enabled>
        <ClientAuthEnabled>{myvars.ssl.client.auth.enabled}</ClientAuthEnabled>
        <KeyStore>{myvars.ssl.keystore}</KeyStore>
        <KeyAlias>{myvars.ssl.keyAlias}</KeyAlias>
        <TrustStore>{myvars.ssl.trustStore}</TrustStore>
    </SSLInfo>

  </HTTPTargetConnection>
  …
</TargetEndpoint>

Où utiliser des modèles de message ?

Les modèles de message sont compatibles avec plusieurs règles ainsi que certains éléments utilisés dans la configuration de TargetEndpoint.

Règles qui acceptent les modèles de messages

Règle Éléments et éléments enfants compatibles avec les modèles de message
Règle AccessControl <SourceAddress>, pour l'attribut mask et l'adresse IP.
Règle AssignMessage Éléments enfants de <Set> : Payload, ContentType, Verb, Version, Path, StatusCode, ReasonPhrase, Headers, QueryParams, FormParams

Éléments enfants de <Add> : Headers, QueryParams, FormParams

Élément enfant de <AssignVariable> : <Template>
Règle ExtensionCallout <Input>
Règle ExtractVariables <JsonPath>
Règle GenerateJWS
Règle VerifyJWS		 <Payload> (Règle GenerateJWS seulement)

<AdditionalHeaders><Claim>

* Ces éléments ne sont compatibles avec un modèle de message que lorsque type=map.

Règle GenerateJWT
Règle VerifyJWT		 <AdditionalClaims><Claim>

<AdditionalHeaders><Claim>

* Ces éléments ne sont compatibles avec un modèle de message que lorsque type=map.

Règles LDAP <SearchQuery>
Règle MessageLogging <Syslog><Message>

<File><Message>
Règle OASValidation Élément <OASResource>
Règle RaiseFault Éléments de <Set> : Payload, ContentType, Verb, Version, Path, StatusCode, ReasonPhrase, Headers, QueryParams, FormParams

Éléments de <Add> : Headers, QueryParams, FormParams
Règle SAMLAssertion <Template>

* Seulement lorsque la règle a pour signature <GenerateSAMLAssertion>
Règle ServiceCallout Éléments de <Set> : Payload, ContentType, Verb, Version, Path, StatusCode, ReasonPhrase, /Headers, QueryParams, FormParams

Éléments de <Add> : Headers, QueryParams, FormParams

<HTTPTargetConnection>/<URL> : notez que la première partie de la chaîne doit correspondre à http ou https.

Éléments TargetEndpoint compatibles avec les modèles de message

Éléments HTTPTargetConnection Éléments enfants compatibles avec les modèles de message
SSLInfo Enabled, KeyAlias, KeyStore, TrustStore, ClientAuthEnabled, CLRStore
LocalTargetConnection ApiProxy, ProxyEndpoint
Chemin ND

Syntaxe des modèles de messages

Cette section explique les règles que vous devez suivre pour utiliser des modèles de messages.

Utiliser des accolades pour désigner les variables

Placez les noms des variables entre accolades { }. Si la variable n'existe pas, une valeur Une chaîne vide est renvoyée dans la sortie. Toutefois, vous pouvez spécifier des valeurs par défaut dans les messages modèles (valeurs remplacées si la variable n'est pas résolue). Voir Définir des valeurs par défaut dans les modèles de message

Notez que le fait de mettre la chaîne entière du modèle de message entre guillemets est autorisé, mais facultatif. Par exemple, les deux modèles de message suivants sont équivalents :

<Set>
    <Headers>
        <Header name="x-h1">"Hello {user.name}"</Header>
        <Header name="x-h1">Hello {user.name}</Header>
    </Headers>
</Set>

Définir des valeurs par défaut dans les modèles de messages

Si une variable modélisée ne peut pas être résolue, Edge remplace une chaîne vide. Toutefois, vous pouvez spécifier une valeur par défaut comme suit : 

<Header name="x-h1">Test message. id = {request.header.id:Unknown}</Header>

Dans l'exemple ci-dessus, si la variable request.header.id ne peut être résolue, sa valeur est remplacée par Unknown. Exemple :

Test message. id = Unknown

Les espaces ne sont pas autorisés dans les expressions de fonction

Les espaces ne sont pas autorisés dans les expressions de fonction des modèles de messages. Par exemple :

Autorisé : 

{substring(alpha,0,4)}
{createUuid()}
{randomLong(10)}

Non autorisé :

{substring( alpha, 0, 4 )}
{ createUuid( ) }
{randomLong( 10 )}

Ancienne syntaxe des charges utiles JSON

Dans les versions d'Edge antérieures à la version 16.08.17 de Cloud, vous ne pouviez pas Utilisez des accolades pour désigner les références de variables dans les charges utiles JSON. Dans ces versions, il fallait utiliser les attributs variablePrefix et variableSuffix pour spécifier des caractères de délimitation, et les utiliser pour encapsuler les noms de variables, comme ceci :

<Set>
  <Payload contentType="application/json" variablePrefix="@" variableSuffix="#">
    {"name":"foo", "type":"@variable_name#"}
  </Payload>
</Set>

Bien qu'Apigee vous recommande d'utiliser la syntaxe avec accolades la plus récente, l'ancienne syntaxe fonctionne toujours.

Utiliser les fonctions de modélisation de messages

Edge fournit un ensemble de fonctions que vous pouvez utiliser dans les modèles de message pour échapper, encoder, hacher, et mettre en forme les variables de chaîne.

Les fonctions de modèle de message sont décrites en détail dans la documentation de référence sur les fonctions des modèles de message.

Example : toLowerCase()

Utilisez la fonction toLowerCase() intégrée pour convertir une variable de chaîne en minuscules :

<AssignMessage name="AM-Set-Custom-Response">
    <AssignTo createNew="false" type="response"/>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <Set>
        <Headers>
            <Header name="x-h1">Test header: {toLowerCase(foo.bar:FOO)}</Header>
        </Headers>
    </Set>
</AssignMessage>

Si la variable de flux foo.bar est résolue, ses caractères sont en minuscules. Si foo.bar n'est pas résolu, la valeur par défaut FOO est remplacée et convertie en caractères minuscules. Par exemple : 

Test header: foo

Example : escapeJSON()

Voici un cas d'utilisation intéressant : supposons que votre application backend renvoie une réponse JSON contenant des caractères d'échappement valides. Exemple : 

{
      "code": "INVALID",
      "user_message": "Invalid value for \"logonId\" check your input."
}

Imaginons que vous souhaitiez renvoyer ce message à l'appelant du client dans une charge utile personnalisée. La méthode habituelle consiste à extraire le message de la charge utile de la réponse cible et à utiliser Attribuer un message pour l'ajouter à une réponse de proxy personnalisée (c'est-à-dire, le renvoyer au client).

Voici la règle ExtractVariables qui extrait les informations user_message dans une variable appelée standard.systemMessage :

<ExtractVariables name="EV-BackendErrorResponse">
    <DisplayName>EV-BackendErrorResponse</DisplayName>
    <JSONPayload>
        <Variable name="standard.systemMessage">
            <JSONPath>$.user_message</JSONPath>
        </Variable>
    </JSONPayload>
</ExtractVariables>

Voici maintenant une règle AssignMessage parfaitement valide qui ajoute la variable extraite à la charge utile de la réponse (la réponse du proxy) :

<AssignMessage name="AM-SetStandardFaultResponse">
    <DisplayName>AM-SetStandardFaultResponse</DisplayName>
    <Set>
        <Payload contentType="application/json">
           {
              "systemMessage": "{standard.systemMessage}"
           }
        </Payload>
    </Set>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <AssignTo createNew="false" transport="http" type="response"/>
</AssignMessage>


Malheureusement, un problème se pose. La règle ExtractVariables a supprimé les guillemets échappés de chaque côté d'une partie du message. Cela signifie que la réponse renvoyée au client ne possède pas un format JSON valide. On est loin du but recherché ! 

{
    "systemMessage": "Invalid value for "logonId" check your input."
}

Pour contourner ce problème, vous pouvez modifier la règle AssignMessage afin d'utiliser une fonction de modèle de message qui échappe les guillemets dans le fichier JSON. Cette fonction, escapeJSON(), échappe les guillemets ou autres caractères spéciaux qui apparaissent dans une expression JSON: 

<AssignMessage name="AM-SetStandardFaultResponse">
    <DisplayName>AM-SetStandardFaultResponse</DisplayName>
    <Set>
        <Payload contentType="application/json">
           {
              "systemMessage": "{escapeJSON(standard.systemMessage)}"
           }
        </Payload>
    </Set>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <AssignTo createNew="false" transport="http" type="response"/>
</AssignMessage>


La fonction échappe les guillemets intégrés et génère un code JSON valide, ce qui est le but recherché.

{
      "systemMessage": "Invalid value for \"logonId\" check your input.",
}

Un message modèle est une fonctionnalité de substitution de chaîne dynamique que vous pouvez utiliser dans certaines règles et dans les définitions de TargetEndpoint. Les fonctions des modèles de messages vous permettent d'effectuer des opérations utiles comme le hachage, la manipulation de chaînes, l'échappement des caractères, etc. au sein d'un modèle de message.

Par exemple, dans la règle AssignMessage suivante, la fonction toLowerCase() est utilisée dans un modèle de message :

<AssignMessage name="AM-Set-Custom-Response">
    <AssignTo createNew="false" type="response"/>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <Set>
       <Headers>
         <Header name="x-h1">Test header: {Hello, toLowerCase(user.name)}</Header>
       </Headers>
    </Set>
</AssignMessage>

Cet article décrit les fonctions des modèles de messages, leurs arguments et les résultats. Dans cette rubrique, nous partons du principe que vous connaissez bien avec les messages modèles et les contextes dans lesquels ils sont utilisés.

Fonctions de hachage

Calculent une valeur de hachage et renvoient la représentation sous forme de chaîne de ce hachage.

Fonctions de hachage hexadécimal

Calculent une valeur de hachage et renvoient la représentation de la chaîne de ce hachage sous la forme d'un nombre hexadécimal.

Syntaxe

Fonction Description
md5Hex(string) Calcule un hachage MD5 exprimé sous la forme d'un nombre hexadécimal.
sha1Hex(string) Calcule un hachage SHA1 exprimé sous la forme d'un nombre hexadécimal.
sha256Hex(string) Calcule un hachage SHA256 exprimé sous la forme d'un nombre hexadécimal.
sha384Hex(string) Calcule un hachage SHA384 exprimé sous la forme d'un nombre hexadécimal.
sha512Hex(string) Calcule un hachage SHA512 exprimé sous la forme d'un nombre hexadécimal.

Arguments

string : les fonctions de hachage prennent un argument de type chaîne unique en fonction duquel l'algorithme de hachage est calculé. Cet argument peut être une chaîne littérale ou une variable de flux de chaîne.

Exemples

Function call :

sha256Hex('abc')

Result:

ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad

Function call :

var str = 'abc';
sha256Hex(str)

Result:

ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad

Fonctions de hachage en Base64

Calculent une valeur de hachage et renvoient la représentation de la chaîne de ce hachage sous forme de valeur encodée en base64.

Syntaxe

Fonction Description
md5Base64(string) Calcule un hachage MD5 exprimé sous la forme d'une valeur encodée en base64.
sha1Base64(string) Calcule un hachage SHA1 exprimé sous la forme d'une valeur encodée en base64.
sha256Base64(string) Calcule un hachage SHA256 exprimé sous la forme d'une valeur encodée en base64.
sha384Base64(string) Calcule un hachage SHA384 exprimé sous forme de valeur encodée en base64.
sha512Base64(string) Calcule un hachage SHA512 exprimé sous la forme d'une valeur encodée en base64.

Arguments

string : les fonctions de hachage prennent un argument de type chaîne unique en fonction duquel l'algorithme de hachage est calculé. L'argument peut être une chaîne littérale ou une variable de flux de chaînes.

Exemples

Function call :

sha256Base64('abc')

Result:

ungWv48Bz+pBQUDeXa4iI7ADYaOWF3qctBD/YfIAFa0=

Function call :

var str = 'abc';
sha256Base64(str)

Result:

ungWv48Bz+pBQUDeXa4iI7ADYaOWF3qctBD/YfIAFa0=

Fonctions de chaîne

Effectuent des opérations sur des chaînes dans un modèle de message.

Fonctions d'encodage en Base64

Encodent et décodent des chaînes à l'aide du schéma d'encodage en Base64.

Syntaxe

Fonction Description
encodeBase64(string) Encode une chaîne en Base64. Par exemple : encodeBase64(value), lorsque value contient abc, la fonction renvoie la chaîne suivante : YWJj
decodeBase64(string) Décode une chaîne encodée en Base64. Par exemple : decodeBase64(value) lorsque value contient aGVsbG8sIHdvcmxk, la fonction renvoie la chaîne hello, world.

Arguments

chaîne : chaîne à encoder ou à décoder. Il peut s'agir d'une chaîne littérale ou d'une variable de flux de chaînes.

Exemple

<AssignMessage name="AM-Set-Custom-Response">
    <AssignTo createNew="false" type="response"/>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <Set>
       <Headers>
         <Header name="x-h1">Hello, {decodeBase64('d29ybGQK')}</Header>
       </Headers>
    </Set>
</AssignMessage>

Fonctions de conversion de cas

Convertissent une chaîne en majuscules ou en minuscules.

Syntaxe

Fonction Description
toUpperCase(string) Convertir une chaîne en majuscules.
toLowerCase(string) Convertir une chaîne en minuscules.


Arguments

string : chaîne à convertir. Il peut s'agir d'une chaîne littérale ou d'une variable de flux de chaînes.

Exemple

<AssignMessage name="AM-Set-Custom-Response">
    <AssignTo createNew="false" type="response"/>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <Set>
       <Headers>
         <Header name="x-h1">Hello, {toLowerCase(user.name)}</Header>
       </Headers>
    </Set>
</AssignMessage>

Fonction Substring

Renvoie les caractères entre l'index de départ et de fin de la chaîne spécifiée.

Syntaxe

substring(str,start_index,end_index)

Arguments

  • str : chaîne littérale ou variable de flux de chaînes.
  • start_index : index de départ au sein de la chaîne.
  • end_index : (facultatif) index de fin au sein de la chaîne. S'il n'est pas fourni, l'index de fin équivaut à la fin de la chaîne.

Exemples

Pour les exemples suivants, supposons que ces variables de flux existent :

Nom de la variable Valeur
alpha ABCDEFGHIJKLMNOPQRSTUVWXYZ
seven 7


Voici les résultats des appels de fonction utilisant ces variables :

Expression du modèle de message Résultat
{substring(alpha,22)} WXYZ
hello {substring(alpha,22)} hello WXYZ
{substring(alpha,-4)} WXYZ
{substring(alpha,-8,-4)} STUV
{substring(alpha,0,10)} ABCDEFGHIJ
{substring(alpha,0,seven)} ABCDEFG

Fonction Replace All

Applique une expression régulière à une chaîne. Pour les correspondances, la correspondance est remplacée par une valeur de remplacement.

Syntaxe

replaceAll(string,regex,value)

Arguments

  • string : chaîne littérale ou variable de flux de chaîne dans laquelle effectuer les remplacements.
  • regex : expression régulière.
  • value : valeur de remplacement de toutes les correspondances identifiées par l'expression régulière dans la chaîne.

Exemples

Pour les exemples suivants, supposons que ces variables de flux existent :

Nom de la variable Valeur
header Bearer ABCDEFGHIJKLMNOPQRSTUVWXYZ-9993
regex1 "^Bearer "
replacement "TOKEN: "

Voici les résultats des appels de fonction utilisant ces variables :

Expression du modèle de message Résultat
{replaceAll(header,"9993",'')} Bearer ABCDEFGHIJKLMNOPQRSTUVWXYZ-
{replaceAll(header,regex1,'')} ABCDEFGHIJKLMNOPQRSTUVWXYZ-9993
{replaceAll(header,regex1,replacement)} TOKEN: ABCDEFGHIJKLMNOPQRSTUVWXYZ-9993

Fonction Replace First

Remplace uniquement la première occurrence de la correspondance identifiée par l'expression régulière dans la chaîne.

Syntaxe

replaceFirst(string,regex,value)

Arguments

  • string : chaîne littérale ou variable de flux de chaîne dans laquelle effectuer les remplacements.
  • regex : expression régulière.
  • value : valeur permettant de remplacer les correspondances identifiées par l'expression régulière dans la chaîne.

Fonctions d'échappement et d'encodage des caractères

Fonctions qui échappent ou encodent des caractères spéciaux dans une chaîne.

Syntaxe

Fonction Description
escapeJSON(string) Échappement des guillemets doubles par barre oblique inverse.
escapeXML(string) Remplace les chevrons, l'apostrophe, les guillemets doubles et les esperluettes par les entités XML respectives. À utiliser pour les documents XML 1.0.

escapeXML11(string) Fonctionne de la même manière qu'escapeXML, mais pour les entités XML v1.1. Consultez les notes d'utilisation ci-dessous.
encodeHTML(string) Encode les apostrophes, les chevrons et les esperluettes.

Arguments

chaîne : chaîne à échapper. Il peut s'agir d'une chaîne littérale ou d'une variable de flux de chaînes.

Remarques sur l'utilisation

XML 1.1 peut représenter certains caractères de contrôle, mais pas les points de code du caractère nul ou de substitution Unicode dissociés, même après échappement. La fonction escapeXML11() supprime les caractères qui ne correspondent pas aux plages suivantes : 

[#x1-#xD7FF] | [#xE000-#xFFFD] | [#x10000-#x10FFFF]

La fonction escapeXML11() échappe les caractères des plages suivantes :

[#x1-#x8] | [#xB-#xC] | [#xE-#x1F] | [#x7F-#x84] | [#x86-#x9F]

Exemples

Supposons qu'une variable de flux appelée food existe avec la valeur suivante : "bread" & "butter". Ensuite, la fonction: 

{escapeHTML(food)}

a pour résultat :

&quot;bread&quot; &amp; &quot;butter&quot;

Fonctions de format horaire

Renvoie une chaîne représentant l'heure, formatée selon le fuseau horaire local ou UTC.

Syntaxe

Fonction Description
timeFormat(format,str) Renvoie la date formatée selon le fuseau horaire local.
timeFormatMs(format,str) Renvoie la date formatée selon le fuseau horaire local.
timeFormatUTC(format,str) Renvoie la date au format UTC.
timeFormatUTCMs(format,str) Renvoie la date au format UTC.

Arguments

  • format : chaîne au format date/heure. Il peut s'agir d'une chaîne littérale ou d'une variable de chaîne.
  • str : chaîne ou variable de flux de chaînes contenant une valeur horaire. La valeur peut être exprimée en secondes ou en millisecondes écoulées depuis l'époch pour timeFormatMs.

Exemples

Prenons les valeurs suivantes et supposons que le fuseau horaire local est celui du Pacifique :

  • epoch_time_ms = 1494390266000
  • epoch_time = 1494390266
  • fmt1 = yyyy-MM-dd
  • fmt2 = yyyy-MM-dd HH-mm-ss
  • fmt3 = yyyyMMddHHmmss

Les fonctions renvoient les résultats suivants :

    Fonction Résultat
    timeFormatMs(fmt1,epoch_time_ms) 2017-05-09
    timeFormat(fmt1,epoch_time) 2017-05-09
    timeFormat(fmt2,epoch_time) 2017-05-09 21:24:26
    timeFormat(fmt3,epoch_time) 20170509212426
    timeFormatUTC(fmt1,epoch_time) 2017-05-10
    timeFormatUTC(fmt2,epoch_time) 2017-05-10 04:24:26
    timeFormatUTC(fmt3,epoch_time) 20170510042426

    Fonctions de calcul HMAC

    Les fonctions de calcul HMAC constituent une alternative à l'utilisation de la règle HMAC pour calculer un HMAC. Ces fonctions sont pratiques lors de l'exécution d'un calcul HMAC en cascade, comme lorsque la sortie d'un HMAC est utilisée comme clé pour un second HMAC.

    Syntaxe

    Fonction Description
    hmacSha224(key,valueToSign[,keyencoding[,outputencoding]]) Calcule un HMAC à l'aide de la fonction de hachage SHA-224.
    hmacSha256(key,valueToSign[,keyencoding[,outputencoding]]) Encode un HMAC à l'aide de la fonction de hachage SHA-256.
    hmacSha384(key,valueToSign[,keyencoding[,outputencoding]]) Encode un HMAC à l'aide de la fonction de hachage SHA-384.
    hmacSha512(key,valueToSign[,keyencoding[,outputencoding]]) Encode un HMAC à l'aide de la fonction de hachage SHA-512.
    hmacMd5(key,valueToSign[,keyencoding[,outputencoding]]) Encode un HMAC à l'aide de la fonction de hachage MD5.
    hmacSha1(key, valueToSign [,keyencoding[,outputencoding]]) Encode un HMAC à l'aide de l'algorithme de chiffrement SHA-1.

    Arguments

    • key (obligatoire) : spécifie la clé secrète, encodée sous forme de chaîne, utilisée pour calculer le HMAC.
    • valueToSign (obligatoire) : spécifie le message à signer. Il doit s'agir d'une chaîne.
    • keyencoding (facultatif) : la chaîne de clé secrète sera décodée selon cet encodage spécifié. Valeurs valides : hex, base16, base64 et utf-8. Valeur par défaut : utf-8
    • outputencoding (facultatif) : spécifie l'algorithme d'encodage à utiliser pour la sortie. Valeurs valides : hex, base16 et base64. Les valeurs ne sont pas sensibles à la casse. hex et base16 sont des synonymes. Valeur par défaut : base64

    Exemples

    Cet exemple utilise la règle AssignMessage pour calculer un HMAC-256 et l'attribuer à une variable de flux : 

    <AssignMessage name='AM-HMAC-1'>
  <AssignVariable>
    <Name>valueToSign</Name>
    <Template>{request.header.apikey}.{request.header.date}</Template>
  </AssignVariable>
  <AssignVariable>
    <Name>hmac_value</Name>
    <Template>{hmacSha256(private.secretkey,valueToSign)}</Template>
  </AssignVariable>
</AssignMessage>

    Cet exemple montre comment générer un HMAC en cascade pouvant être utilisé avec le processus de signature AWS Signature v4. L'exemple utilise la règle AssignMessage pour générer les cinq niveaux du HMAC en cascade utilisés pour calculer une signature pour AWS Signature v4 : 

    <AssignMessage name='AM-HMAC-AWS-1'>
  <!-- 1 -->
  <AssignVariable>
    <Name>DateValue</Name>
    <Template>{timeFormatUTCMs('yyyyMMdd',system.timestamp)}</Template>
  </AssignVariable>
  <!-- 2 -->
  <AssignVariable>
    <Name>FirstKey</Name>
    <Template>AWS4{private.secret_aws_access_key}</Template>
  </AssignVariable>
  <!-- 3 -->
  <AssignVariable>
    <Name>DateKey</Name>
    <Template>{hmacSha256(FirstKey,DateValue,'utf-8','base16')}</Template>
  </AssignVariable>
  <!-- 4 -->
  <AssignVariable>
    <Name>DateRegionKey</Name>
    <Template>{hmacSha256(DateKey,aws_region,'base16','base16')}</Template>
  </AssignVariable>
  <!-- 5 -->
  <AssignVariable>
    <Name>DateRegionServiceKey</Name>
    <Template>{hmacSha256(DateRegionKey,aws_service,'base16','base16')}</Template>
  </AssignVariable>
  <!-- 6 -->
  <AssignVariable>
    <Name>SigningKey</Name>
    <Template>{hmacSha256(DateRegionServiceKey,'aws4_request','base16','base16')}</Template>
  </AssignVariable>
  <!-- 7 -->
  <AssignVariable>
    <Name>aws4_hmac_value</Name>
    <Template>{hmacSha256(SigningKey,stringToSign,'base16','base16')}</Template>
  </AssignVariable>
</AssignMessage>

    Autres fonctions

    Fonction Create UUID

    Génère et renvoie un UUID.

    Syntaxe

    createUuid()

    Arguments

    Aucune

    Exemple

    {createUuid()}

    Exemple de résultat :

    ec3ca9be-d1e1-4ef4-aee4-4a58f3130db8

    Fonction Random Long Generator

    Renvoie un entier long aléatoire.

    Syntaxe

    randomLong(args)

    Arguments

    • Si aucun argument n'est spécifié, la fonction renvoie un entier long aléatoire, calculé par la classe Java SecureRandom.
    • Si un argument est présent, il est considéré comme la valeur minimale du calcul.
    • Si un deuxième argument est présent, il est traité comme la valeur maximale du calcul.

    Exemple

    {random()}

    produit un résultat semblable au suivant :

    5211338197474042880

    Générateur de texte selon une expression régulière

    Génère une chaîne de texte qui correspond à une expression régulière donnée.

    Syntaxe

    xeger(regex)

    Argument

    regex : expression régulière.

    Exemple

    Cet exemple génère une chaîne à sept chiffres sans zéro : 

    xeger('[1-9]{7}')

    Exemple de résultat : 

    9857253

    Fonction Null-coalescing

    La fonction firstnonnull() renvoie la valeur de l'argument non vide le plus à gauche.

    Syntaxe

    firstnonnull(var1,varn)

    Argument

    var1 : variable de contexte.

    varn : une ou plusieurs variables de contexte. Vous pouvez définir l'argument le plus à droite sur une chaîne pour fournir une valeur de remplacement (valeur qui sera définie si aucun des arguments de gauche n'est défini).

    Exemples

    Le tableau suivant montre comment utiliser la fonction :

    Modèle Var1 Var2 Var3 Résultat
    {firstnonnull(var1,var2)} Non défini foo ND foo
    {firstnonnull(var1,var2)} foo bar ND foo
    {firstnonnull(var1,var2)} foo Non défini ND foo
    {firstnonnull(var1,var2,var3)} foo bar baz foo
    {firstnonnull(var1,var2,var3)} Non défini bar baz bar
    {firstnonnull(var1,var2,var3)} Non défini Non défini baz baz
    {firstnonnull(var1,var2,var3)} Non défini Non défini Non défini null
    {firstnonnull(var1)} Non défini ND N/A null
    {firstnonnull(var1)} foo N/A N/A foo
    {firstnonnull(var1,var2)} "" bar ND ""
    {firstnonnull(var1,var2,'fallback value')} null null fallback value fallback value

    Fonction XPath

    Applique une expression XPath à une variable XML.

    Syntaxe

    xpath(xpath_expression,xml_string,[datatype])

    Arguments

    xpath_expression : expression XPath.

    xml_string : variable ou chaîne de flux contenant du code XML.

    datatype (facultatif) : spécifie le type renvoyé par la requête. Il peut s'agir de "nodeset", "node", "number", "boolean" ou "string". Par défaut, il est défini sur "nodeset". La valeur par défaut est généralement l'option correcte.

    Exemple 1

    Supposons que ces variables de contexte définissent une chaîne XML et une expression XPath : 

    xml = "<tag><tagid>250397</tagid><readerid>1</readerid><rssi>74</rssi><date>2019/06/15</date></tag>"
xpath = "/tag/tagid"

    La fonction xpath() est utilisée dans une règle AssignMessage, comme suit :

    <AssignMessage>
  <AssignVariable>
    <Name>extracted_tag</Name>
    <Template>{xpath(xpath,xml)}</Template>
  </AssignVariable>
</AssignMessage><

    La fonction renvoie la valeur <tagid>250397</tagid>. Cette valeur est placée dans la variable de contexte nommée extracted_tag.

    Exemple 2

    Si vous souhaitez obtenir uniquement la valeur du nœud, utilisez la fonction text() comme suit :

    <AssignMessage>
  <AssignVariable>
    <Name>extracted_tag</Name>
    <Template>{xpath('/tag/tagid/text()',xml)}</Template>
  </AssignVariable>
</AssignMessage>

    À la suite de cette opération, la variable de contexte extracted_tag est définie sur 250397.

    Si plusieurs nœuds sont sélectionnés, le résultat xpath() correspond à toutes les valeurs de la sélection, concaténées avec une virgule.

    Exemple 3 : espaces de noms XML

    Pour spécifier un espace de noms, ajoutez des paramètres supplémentaires, chacun correspondant à une chaîne de type prefix:namespaceuri. Par exemple, une fonction xpath() qui sélectionne l'élément enfant d'un corps SOAP peut ressembler à ceci : 

    <AssignMessage>
  <AssignVariable>
    <Name>soapns</Name>
    <Value>soap:http://schemas.xmlsoap.org/soap/envelope/</Value>
  </AssignVariable>
  <AssignVariable>
    <Name>xpathexpression</Name>
    <Value>/soap:Envelope/soap:Body/*</Value>
  </AssignVariable>
  <AssignVariable>
    <Name>extracted_element</Name>
    <Template>{xpath(xpathexpression,xml,soapns)}</Template>
  </AssignVariable>
</AssignMessage>

    Pour les espaces de noms supplémentaires, vous pouvez ajouter jusqu'à 10 paramètres supplémentaires à la fonction xpath().

    Vous pouvez spécifier une expression XPath simple sous forme de chaîne entre guillemets simples :

    {xpath('/tag/tagid/text()',xml)}

    Si l'expression XPath inclut des préfixes d'espace de noms (et des deux-points), elle doit être attribuée à une variable et vous devez spécifier le nom de la variable plutôt que l'expression directement.

    {xpath(xpathexpression,xml,ns1)}

    Exemple 4 : Spécifier le type renvoyé

    Le troisième paramètre facultatif transmis à la fonction xpath() spécifie le type renvoyé par la requête.

    Certaines requêtes XPath peuvent renvoyer des valeurs numériques ou booléennes. Par exemple, la fonction count() renvoie un nombre. Voici une requête XPath valide : 

    count(//Record/Fields/Pair)

    Cette requête valide renvoie un booléen :

    count(//Record/Fields/Pair)>0

    Dans de tels cas, appelez la fonction xpath() avec un troisième paramètre spécifiant ce type :

    {xpath(expression,xml,'number')}
{xpath(expression,xml,'boolean')}

    Si le troisième paramètre contient un deux-points, celui-ci est interprété comme un argument d'espace de noms. Sinon, il est traité comme le type renvoyé souhaité. Dans ce cas, si le troisième paramètre n'est pas l'une des valeurs valides (en ignorant la casse), la fonction xpath() renvoie par défaut un ensemble de nœuds.

    Fonction JSON Path

    Applique une expression de chemin JSON à une variable JSON.

    Syntaxe

    jsonPath(json-path,json-var,want-array)

    Arguments

    • (Obligatoire) json-path : (chaîne) Expression de chemin JSON.
    • (Obligatoire) json-var : (chaîne) Variable de flux ou chaîne contenant JSON.
    • (Facultatif) want-array: (Chaîne) si ce paramètre est défini sur 'true' et si l'ensemble de résultats est un tableau, tous les éléments du tableau sont renvoyés. Si ce paramètre est défini sur une autre valeur ou si ce paramètre est omis, seul l'élément zéro d'un tableau d'ensemble de résultats est renvoyé. Si l'ensemble de résultats n'est pas un tableau, alors ce troisième paramètre, s'il est présent, est ignoré.

    Exemple 1

    S'il s'agit du modèle de message :

    The address is {jsonPath($.results[?(@.name == 'Mae West')].address.line1,the_json_variable)}

    et que the_json_variable contient :

    {
  "results" : [
    {
      "address" : {
        "line1" : "18250 142ND AV NE",
        "city" : "Woodinville",
        "state" : "Washington",
        "zip" : "98072"
      },
      "name" : "Fred Meyer"
    },
    {
      "address" : {
        "line1" : "1060 West Addison Street",
        "city" : "Chicago",
        "state" : "Illinois",
        "zip" : "60613"
      },
      "name" : "Mae West"
    }
  ]
}

    le résultat de la fonction est le suivant :

    The address is 1060 West Addison Street

    Notez que, dans ce cas, l'ensemble de résultats est constitué d'un seul élément (et non d'un tableau d'éléments). Si l'ensemble de résultats est un tableau, seul l'élément zéro du tableau est renvoyé. Pour renvoyer le tableau complet, appelez la fonction avec 'true' comme troisième paramètre, comme indiqué dans l'exemple suivant.

    Exemple 2

    S'il s'agit du modèle de message :

    {jsonPath($.config.quota[?(@.operation=='ManageOrder')].appname,the_json_variable,'true')}

    et que the_json_variable contient :

    {
  "results" : [
     {
      "config": {
        "quota": [
          {
            "appname": "A",
            "operation": "ManageOrder",
            "value": "900"
          },
          {
            "appname": "B",
            "operation": "ManageOrder",
            "value": "1000"
          },
          {
            "appname": "B",
            "operation": "SubmitOrder",
            "value": "800"
          }
        ]
      }
    }
  ]
}

    le résultat de la fonction est le suivant :

    ['A','B']