Modèles de messages

Vous consultez la documentation d'Apigee Edge.
Consultez la documentation 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 variables de flux et de texte littéral dans un modèle de message. Les noms des variables de flux doivent être entourés d'accolades. Tout texte qui n'est pas entre accolades est généré sous forme de texte littéral.

Consultez également l'article Où utiliser les 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ée et remplacée dans la chaîne de charge utile au moment de l'exécution. Ainsi, par exemple, si la valeur est user.name=jdoe, le message de sortie 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 modèle est couramment utilisé avec une "règle d'erreur" pour fournir un résultat fournissant à l'appelant des informations sur la violation de quota. Dans la règle d'attribution de message suivante, les modèles de message permettent de renseigner 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 de messages:

• En-tête
• QueryParam
• FormParam
• PayLoad
• Version
• Verbe
• Chemin d'accès
• 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 d'en-tête reçoivent les valeurs des variables de flux spécifiées.
• La charge utile comprend un mélange de texte littéral et de variables (client_id est renseigné de manière dynamique).
• Les éléments StatusCode et ReasonPhrase n'incluent que du texte littéral. Toutefois, si vous souhaitez les utiliser, ces éléments sont également compatibles avec la création de modèles de message.

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 et certains éléments utilisés dans la configuration de TargetEndpoint.

Règles qui acceptent les modèles de messages

Policy	É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 <Set>: charge utile, ContentType, Verb, Version, Path, StatusCode, ReasonPhrase, Headers, QueryParams, FormParams Éléments enfants <Add>: en-têtes, QueryParams, FormParams Élément enfant <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.
GenerateJWT policy Vérifier une stratégie JWT	<AdditionalClaims><Claim> <AdditionalHeaders><Claim> * Ces éléments ne sont compatibles avec un modèle de message que lorsque type=map.
Règle LDAP	<SearchQuery>
Règle MessageLogging	<Syslog><Message> <File><Message>
Règle OASValidation	Élément <OASResource>
Règle RaiseFault	Éléments <Set>: charge utile, ContentType, Verbe, Version, Path, StatusCode, ReasonPhrase, Headers, QueryParams, FormParams Éléments <Add>: Headers, QueryParams et FormParams
Règle SAMLAssertion	<Template> * Seulement lorsque la règle a pour signature <GenerateSAMLAssertion>
Règle ServiceCallout	Éléments <Set>: charge utile, ContentType, Verb, Version, Path, StatusCode, ReasonPhrase, /Headers, QueryParams, FormParams Éléments <Add>: Headers, QueryParams et FormParams <HTTPTargetConnection>/<URL>: notez que la première partie de la chaîne doit être 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 d'accès	N/A

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 chaîne vide est renvoyée dans le résultat. Toutefois, vous pouvez spécifier des valeurs par défaut dans les modèles de message (valeurs remplacées si la variable n'est pas résolue). Consultez la section 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 de modèle 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. 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 utiliser d'accolades pour indiquer des 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 recommande d'utiliser la nouvelle syntaxe d'accolade, l'ancienne 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 des variables de chaîne.

Les fonctions des modèles 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. 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 réponse cible et à utiliser la fonction "Attribuer un message" pour l'ajouter à une réponse de proxy personnalisée (c'est-à-dire le renvoyer au client).

Voici la règle Extract Variables 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>

Maintenant, voici une stratégie "Attribuer un message" parfaitement valide qui ajoute la variable extraite à la charge utile de la réponse (la réponse 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 tous les guillemets ou autres caractères spéciaux figurant 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, ce qui génère un code JSON valide, comme vous le souhaitiez:

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

Un modèle de message est une fonctionnalité de substitution de chaîne dynamique que vous pouvez utiliser dans certaines règles et dans les définitions TargetEndpoint. Les fonctions de modèles de message vous permettent d'effectuer des opérations utiles telles que le hachage, la manipulation de chaînes, l'échappement de caractères et d'autres opérations 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 leurs sorties. Dans cette rubrique, nous partons du principe que vous connaissez bien les modèles de messages 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

Calculez une valeur de hachage et renvoyez la représentation de ce hachage sous forme de chaîne hexadécimale.

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

Appel de fonction :

sha256Hex('abc')

Result:

ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad

Appel de fonction :

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 la forme d'un valuer encodé 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

Appel de fonction :

sha256Base64('abc')

Result:

ungWv48Bz+pBQUDeXa4iI7ADYaOWF3qctBD/YfIAFa0=

Appel de fonction :

var str = 'abc';
sha256Base64(str)

Résultat :

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)	Convertit 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îne.
• start_index : index de départ dans 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 qui utilisent ces variables:

Expression de 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 des remplacements.
• regex : une 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 qui utilisent ces variables:

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

Ne remplace que la première occurrence de la correspondance d'expression régulière spécifiée 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 des remplacements.
• regex : une 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(chaîne)	La barre oblique inverse protège les guillemets doubles.
escapeXML(chaîne)	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(chaîne)	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(chaîne)	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)}

résultat:

"bread" & "butter"

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 mise en forme dans le fuseau horaire local.
timeFormatMs(format,str)	Renvoie la date mise en forme dans 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 de 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

Supposons les valeurs suivantes et le fuseau horaire local (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	Sortie
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

Aucun

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()}

génère un résultat semblable à celui-ci:

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 : une 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 : une variable de contexte.

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

Template	Var1	Var2	Var3	Résultat
{firstnonnull(var1,var2)}	Non définie	foo	N/A	foo
{firstnonnull(var1,var2)}	foo	bar	N/A	foo
{firstnonnull(var1,var2)}	foo	Non définie	N/A	foo
{firstnonnull(var1,var2,var3)}	foo	bar	baz	foo
{firstnonnull(var1,var2,var3)}	Non définie	bar	baz	bar
{firstnonnull(var1,var2,var3)}	Non définie	Non définie	baz	baz
{firstnonnull(var1,var2,var3)}	Non définie	Non définie	Non définie	null
{firstnonnull(var1)}	Non définie	N/A	N/A	null
{firstnonnull(var1)}	foo	N/A	N/A	foo
{firstnonnull(var1,var2)}	""	bar	N/A	""
{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 : une chaîne ou une variable 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"

De plus, 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 une valeur booléenne :

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

Dans ce 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']