Modèles de messages

Cette page s'applique à Apigee et à Apigee hybrid.

Consultez la documentation d'Apigee Edge.

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 <TargetEndpoint> et de règle. 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 placés entre accolades, et 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) est évaluée et remplacée par la chaîne de charge utile au moment de l'exécution. Ainsi, par exemple, si user.name=jdoe, le message de sortie obtenu 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 une sortie à l'appelant l'informant sur le dépassement des quotas. Dans la règle AssignMessage suivante, les modèles de messages sont utilisés pour renseigner dynamiquement les informations de quota 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>
  </Set>
</AssignMessage>

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

<Header>
<QueryParam>
<FormParam>
<PayLoad>
<Version>
<Verb>
<Path>
<StatusCode>

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).
L'élément <StatusCode> ne comporte que du texte littéral. Toutefois, cet élément est également compatible avec la modélisation des messages si vous souhaitez l'utiliser.

Exemple

Dans une définition de proxy <TargetEndpoint>, les éléments enfants de <SSLInfo> sont compatibles avec la modélisation des 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 messages sont compatibles avec plusieurs règles, ainsi qu'avec certains éléments utilisés dans la configuration TargetEndpoint.

Remarque : Vous pouvez également consulter la documentation de la règle pour connaître les règles et les éléments <TargetEndpoint> compatibles avec les modèles de messages.

Règles qui acceptent les modèles de messages

Le tableau suivant répertorie les règles et les éléments/éléments enfants compatibles :

Règle	Éléments/Éléments enfants
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, Headers, QueryParams, FormParams Éléments enfants de `<Add>` : Headers, QueryParams, FormParams Élément enfant de `<AssignVariable>` : `<Template>`
Règle CORS	`<AllowHeaders>` `<AllowMethods>` `<AllowOrigins>` `<ExposeHeaders>`
Règle ExtractVariables	`<JsonPath>` Remarque : Le modèle de message n'est pas accepté pour `<XMLPath>`.
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ègle HTTPModifier	Éléments enfants `<Set>` : `<ContentType>` `<Verb>` `<Version>` `<Path>` `<StatusCode>` `<Headers>` `<QueryParams>` `<FormParams>` Éléments enfants `<Add>` : `<Headers>` `<QueryParams>` `<FormParams>`
Règle MessageLogging	`<CloudLogging><Message>` `<Syslog><Message>` `<File><Message>`
Règle OASValidation	Élément `<OASResource>`
Règle RaiseFault	Éléments `<Set>` : `<ContentType>` `<FormParams>` `<Headers>` `<QueryParams>` `<StatusCode>` `<Path>` `<Payload>` `<Verb>` `<Version>` Éléments `<Add>` : `<FormParams>` `<Headers>` `<QueryParams>`
Règle SAMLAssertion	`<Template>` * Seulement lorsque la règle a pour signature `<GenerateSAMLAssertion>`
Règle ServiceCallout	Éléments `<Set>` : `<ContentType>` `<FormParams>` `<Headers>` `<QueryParams>` `<StatusCode>` `<Path>` `<Payload>` `<Verb>` `<Version>` Éléments `<Add>` : `<FormParams>` `<Headers>` `<QueryParams>` `<HTTPTargetConnection>/<URL>` : consultez la section Modèles d'URL.

Éléments `<TargetEndpoint>` qui acceptent les modèles de messages

Éléments `<HTTPTargetConnection>`	Éléments enfants compatibles avec les modèles de messages
`<SSLInfo>`	`<Enabled>`, `<KeyAlias>`, `<KeyStore>`, `<TrustStore>`, `<ClientAuthEnabled>`, `<CLRStore>`
`<LocalTargetConnection>`	`<ApiProxy>`, `<ProxyEndpoint>`, `<Path>`
`<Path>`	N/A
`<URL>`	Aucun élément enfant. Pour en savoir plus, consultez la section Modèle d'URL.

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 de variables entre accolades { }. Si la variable n'existe pas, une chaîne vide est renvoyée dans la sortie. Toutefois, vous pouvez spécifier des valeurs par défaut dans les modèles de messages (valeurs qui sont 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 messages.

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 messages suivants sont équivalents :

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

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

Les fonctions imbriquées ne sont pas acceptées.

Il n'est pas possible d'appeler une fonction dans une autre fonction d'un modèle. Par exemple, vous ne pouvez pas utiliser :

{substring({timeFormat('yyyy-MM-dd','1494390266')},0,4)}

Placer les littéraux de chaîne entre guillemets simples dans les fonctions de modèle

Lorsque vous fournissez des littéraux de chaîne dans des fonctions, placez-les entre guillemets simples plutôt que doubles.

Par exemple,

{replaceAll('BEARER: 1234','^Bearer ','TOKEN:')}

Éviter d'utiliser des caractères spéciaux dans les littéraux de chaîne

Évitez les caractères spéciaux, tels que ":", "/", "", "<" ou ">", dans les littéraux de chaîne. Ces caractères peuvent entraîner des erreurs. Si un littéral de chaîne nécessite des caractères spéciaux, attribuez la valeur à une variable à l'aide d'une règle Python ou JavaScript, puis utilisez la variable dans le modèle.

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, Apigee la remplace par 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. Par exemple :

Test message. id = Unknown

Modèles d'URL

L'élément URL est compatible avec la modélisation selon la même syntaxe que les autres éléments.

Cet exemple présente une URL créée à l'aide de variables :

<URL>{targeturl}</URL>

Cet exemple illustre une valeur par défaut pour le protocole :

<URL>{protocol:https}://{site:google.com}/path</URL>

Ancienne syntaxe des charges utiles JSON

Dans les versions d'Apigee antérieures à cloud 16.08.17, il n'était pas possible d'utiliser les accolades pour désigner des références 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 nouvelle syntaxe avec accolades, l'ancienne syntaxe fonctionne toujours.

Utiliser les fonctions de modélisation de messages

Apigee fournit un ensemble de fonctions que vous pouvez utiliser dans les modèles de messages pour échapper, encoder, hacher et formater des variables de chaîne, comme décrit ci-dessous.

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. Par 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. Pour ce faire, le moyen habituel consiste à extraire le message de la charge utile de la réponse cible et à utiliser AssignMessage pour l'ajouter à une réponse de proxy personnalisée (c'est-à-dire à renvoyer le message 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. La fonction escapeJSON() permet d'échapper les guillemets ou d'autres caractères spéciaux présents 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 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èle de message vous permettent d'effectuer des opérations utiles telles que le hachage, la manipulation de chaînes, l'échappement des caractères et d'autres encore 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>

Cette section décrit les fonctions du modèle de message, leurs arguments et leurs sorties. Dans cette rubrique, nous partons du principe que vous connaissez 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

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é. L'argument peut être une chaîne littérale (entre guillemets simples) ou une variable de flux de chaînes.

Exemples

Appel de fonction :

sha256Hex('abc')

Résultat :

ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad

Appel de fonction :

var str = 'abc';
sha256Hex(str)

Résultat :

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

Exemples

Appel de fonction :

sha256Base64('abc')

Result:

ungWv48Bz+pBQUDeXa4iI7ADYaOWF3qctBD/YfIAFa0=

Appel de fonction :

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

string : chaîne à encoder ou décoder. Il peut s'agir d'une chaîne littérale (entre guillemets simples) 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)`	Convertit une chaîne en minuscules.

Arguments

string : chaîne à convertir. Il peut s'agir d'une chaîne littérale (entre guillemets simples) 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 (entre guillemets simples) ou variable de flux de chaînes.
start_index : index de départ dans la chaîne.
end_index (facultatif) : index de fin dans 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 (entre guillemets simples) ou variable de flux de chaînes 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 (entre guillemets simples) ou variable de flux de chaînes 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, les apostrophes, les guillemets doubles et les esperluettes par leurs entités XML respectives. À utiliser pour les documents XML 1.0. Utilisez escapeXML avec les documents XML 1.0 et escapeXML 11 avec les documents XML 1.1.
`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

string : chaîne à échapper. Il peut s'agir d'une chaîne littérale (entre guillemets simples) 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". Alors, la fonction :

{escapeHTML(food)}

Résultats dans :

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

Fonctions de format horaire

Renvoie une chaîne représentant l'heure, au format UTC.

Syntaxe

Fonction	Description
`timeFormat(format,str)`	Renvoie la date au format UTC. `DEPRECATED` : Renvoie la date formatée selon le fuseau horaire local.
`timeFormatMs(format,str)`	Renvoie la date au format UTC. `DEPRECATED` : 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 de date/heure. Il peut s'agir d'une chaîne littérale (entre guillemets simples) ou d'une variable de chaîne. Utilisez une variable plutôt qu'un littéral lorsque le format inclut un caractère deux-points. Reportez-vous à la remarque précédente de cette section.
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	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

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

{randomLong()}

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 :

Fonction Null-coalescing

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

Syntaxe

firstnonnull(var1,var_n)

Argument

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

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	ND	`null`
`{firstnonnull(var1)}`	`foo`	ND	ND	`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 de flux ou chaîne contenant du XML.

datatype (facultatif) : spécifie le type renvoyé par la requête. Les valeurs valides sont nodeset, node, number, boolean et string. La valeur par défaut est 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 : 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().

Plutôt que de spécifier des expressions XPath avec des caractères spéciaux dans un littéral de chaîne, utilisez une variable pour inclure cette chaîne dans la fonction. Pour plus d'informations, consultez la section Évitez d'utiliser des caractères spéciaux dans les littéraux de chaîne.

{xpath(xpathexpression,xml,ns1)}

Exemple 3 : 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 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']

Modèles de messages

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

Exemple

Exemple

Exemple

Où utiliser des modèles de message ?

Règles qui acceptent les modèles de messages

Éléments <TargetEndpoint> qui acceptent les modèles de messages

Syntaxe des modèles de messages

Utiliser des accolades pour désigner les variables

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

Les fonctions imbriquées ne sont pas acceptées.

Placer les littéraux de chaîne entre guillemets simples dans les fonctions de modèle

Éviter d'utiliser des caractères spéciaux dans les littéraux de chaîne

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

Modèles d'URL

Ancienne syntaxe des charges utiles JSON

Utiliser les fonctions de modélisation de messages

Example : toLowerCase()

Example : escapeJSON()

Fonctions de hachage

Fonctions de hachage hexadécimal

Syntaxe

Arguments

Exemples

Fonctions de hachage en Base64

Syntaxe

Arguments

Exemples

Fonctions de chaîne

Fonctions d'encodage en Base64

Syntaxe

Arguments

Exemple

Fonctions de conversion de cas

Syntaxe

Arguments

Exemple

Fonction Substring

Syntaxe

Arguments

Exemples

Fonction Replace All

Syntaxe

Arguments

Exemples

Fonction Replace First

Syntaxe

Arguments

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

Syntaxe

Arguments

Remarques sur l'utilisation

Exemples

Fonctions de format horaire

Syntaxe

Arguments

Exemples

Fonctions de calcul HMAC

Syntaxe

Arguments

Exemples

Autres fonctions

Fonction Create UUID

Syntaxe

Arguments

Exemple

Fonction Random Long Generator

Syntaxe

Arguments

Exemple

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

Syntaxe

Argument

Exemple

Fonction Null-coalescing

Syntaxe

Argument

Exemples

Fonction XPath

Éléments `<TargetEndpoint>` qui acceptent les modèles de messages