Modelli di messaggio

Stai visualizzando la documentazione di Apigee Edge.
Vai alla documentazione di Apigee X. informazioni

Questo argomento illustra come utilizzare i modelli di messaggio nei proxy API e fornisce un riferimento alla funzione.

Che cos'è un modello di messaggio?

Un modello di messaggio ti consente di eseguire una sostituzione di stringhe variabili in determinati elementi di criteri ed elementi TargetEndpoint. Questa funzionalità, se supportata, consente di compilare le stringhe in modo dinamico quando viene eseguito un proxy.

Puoi includere qualsiasi combinazione di riferimenti a variabili di flusso e testo letterale in un modello di messaggio. I nomi delle variabili di flusso devono essere racchiusi tra parentesi graffe, mentre qualsiasi testo che non sia tra parentesi graffe viene restituito come testo letterale.

Vedi anche Dove si possono utilizzare i modelli di messaggi?

Esempio

Ad esempio, il criterio Assegna messaggio consente di utilizzare un modello di messaggio all'interno dell'elemento <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>

Nell'esempio precedente, il valore della variabile di flusso user.name (in parentesi graffe) verrà valutato e sostituito nella stringa del payload al runtime. Quindi, ad esempio, se user.name=jdoe, l'output del messaggio risultante nel payload sarà: You entered an invalid username: jdoe. Se non è possibile risolvere la variabile, viene restituita una stringa vuota.

Esempio

Quando si supera una quota, è buona norma restituire un messaggio significativo al chiamante. Questo pattern viene comunemente utilizzato con una "regola di errore" per fornire al chiamante informazioni sulla violazione della quota. Nel seguente criterio Assegna messaggio, i modelli di messaggi vengono utilizzati per inserire in modo dinamico le informazioni sulle quote in diversi elementi 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>

Nel criterio AttributionMessage, i seguenti elementi dell'elemento <Set> supportano i modelli dei messaggi:

  • Titolo
  • QueryParam
  • FormParam
  • PayLoad
  • Versione
  • Verbo
  • Percorso
  • StatusCode
  • ReasonPhrase

Anche in questo caso, tieni presente che le variabili di flusso in un modello di messaggio devono essere racchiuse tra parentesi graffe.

Quando questo criterio viene eseguito:

  • Gli elementi Header ricevono i valori delle variabili di flusso specificate.
  • Il payload include una combinazione di testo letterale e variabili (il valore client_id viene compilato dinamicamente).
  • I valori StatusCode e Reasonphrase includono solo testo letterale; tuttavia, questi elementi supportano anche i modelli dei messaggi, se vuoi utilizzarli.

Esempio

In una definizione di TargetEndpoint del proxy, gli elementi secondari di <SSLInfo> supportano i modelli dei messaggi. Seguendo lo stesso pattern utilizzato nei criteri, le variabili di flusso nelle parentesi graffe vengono sostituite all'esecuzione del proxy. 

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

Dove puoi utilizzare i modelli di messaggi?

I modelli di messaggi sono supportati in diversi criteri e in alcuni elementi utilizzati nella configurazione di TargetEndpoint.

Criteri che accettano modelli di messaggi

Norme Elementi ed elementi secondari che supportano i modelli di messaggi
Criterio di AccessControl <SourceAddress>, per l'attributo mask e l'indirizzo IP.
Criterio AttributionMessage Elementi secondari di <Set>: Payload, ContentType, Verb, Version, Path, StatusCode, Reasonphrase, Headers, QueryParams, FormParams

Elementi secondari di <Add>: Headers, QueryParams, FormParams

Elemento secondario <AssignVariable>: <Template>

Norme sui callout per le estensioni <Input>
Norma ExtractVariables <JsonPath>
Generare criterio JWS
Verificare criterio JWS 		<Payload> (solo criterio Genera JWS)

<AdditionalHeaders><Claim>

* Questi elementi supportano il modello di messaggio solo se type=map.

Generare criterio JWT
Verificare il criterio JWT 		<AdditionalClaims><Claim>

<AdditionalHeaders><Claim>

* Questi elementi supportano il modello di messaggio solo se type=map.

Criteri LDAP <SearchQuery>
Criterio MessageLogging <Syslog><Message>

<File><Message>
Norme di OASValidation Elemento <OASResource>
Criterio AlzaFault Elementi <Set>: Payload, ContentType, Verb, Version, Path, StatusCode, ReasonPhrase, Headers, QueryParams, FormParams

Elementi <Add>: Headers, QueryParams, FormParams

Criterio SAMLAssertion <Template>

* Solo se la firma delle norme è <GenerateSAMLAssertion>
Norme sui callout di servizio Elementi <Set>: Payload, ContentType, Verb, Version, Path, StatusCode, ReasonPhrase, /Headers, QueryParams, FormParams

Elementi <Add>: Headers, QueryParams, FormParams

<HTTPTargetConnection>/<URL>: tieni presente che la prima parte della stringa deve essere http o https.

Elementi TargetEndpoint che accettano modelli di messaggi

Elementi HTTPTargetConnection Elementi secondari che supportano i modelli di messaggi
SSLInfo Abilitato, KeyAlias, KeyStore, TrustStore, ClientAuthEnabled, CLRStore
LocalTargetConnection ApiProxy, ProxyEndpoint
Percorso N/A

Sintassi del modello di messaggio

Questa sezione illustra le regole da seguire per utilizzare i modelli di messaggi.

Utilizza le parentesi graffe per indicare le variabili

Racchiudi i nomi delle variabili tra parentesi graffe { }. Se la variabile non esiste, nell'output viene restituita una stringa vuota. Tuttavia, puoi specificare i valori predefiniti nei modelli di messaggio (valori che vengono sostituiti se la variabile non è risolta). Consulta Impostare i valori predefiniti nei modelli di messaggi.

Tieni presente che è consentito racchiudere l'intera stringa del modello di messaggio tra virgolette, ma è facoltativo. Ad esempio, i seguenti due modelli di messaggi sono equivalenti:

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

Impostazione dei valori predefiniti nei modelli di messaggio

Se non è possibile risolvere una variabile basata su modelli, Edge sostituisce una stringa vuota. Tuttavia, puoi specificare un valore predefinito come segue: 

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

Nell'esempio precedente, se la variabile request.header.id non può essere risolta, il suo valore viene sostituito da Unknown. Ad esempio:

Test message. id = Unknown

Gli spazi non sono consentiti nelle espressioni di funzione

Gli spazi non sono consentiti in nessuna posizione nelle espressioni delle funzioni del modello di messaggio. Ad esempio:

Consentito: 

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

Non consentiti: 

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

Sintassi precedente per i payload JSON

Nelle versioni Edge prima della release 16.08.17 di Cloud, non potevi utilizzare le parentesi graffe per indicare i riferimenti alle variabili all'interno dei payload JSON. Nelle versioni precedenti, dovevi utilizzare gli attributi variablePrefix e variableSuffix per specificare i caratteri di delimitazione e utilizzarli per aggregare i nomi delle variabili, in questo modo:

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

Sebbene Apigee suggerisca di utilizzare la nuova sintassi delle parentesi graffe, quella precedente funziona ancora.

Utilizzare le funzioni per i modelli di messaggi

Edge fornisce un insieme di funzioni che puoi utilizzare all'interno dei modelli di messaggi per eseguire l'escape, codificare, eseguire l'hashing e formattare le variabili stringa.

Le funzioni per il modello di messaggio sono descritte in dettaglio in Riferimento alla funzione modello di messaggio.

Esempio: toLowerCase()

Utilizza la funzione toLowerCase() integrata per trasformare una variabile stringa in minuscolo:

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

Se la variabile di flusso foo.bar si risolve, i suoi caratteri saranno tutti minuscoli. Se foo.bar non è risolto, il valore predefinito FOO viene sostituito e convertito in caratteri minuscoli. Ad esempio: 

Test header: foo

Esempio: escapeJSON()

Ecco un caso d'uso interessante: supponiamo che la tua app di backend restituisca una risposta JSON contenente caratteri di escape validi. Ad esempio: 

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

Supponiamo poi di voler restituire questo messaggio al chiamante del client in un payload personalizzato. Il solito modo per farlo è estrarre il messaggio dal payload della risposta di destinazione e utilizzare Assegna messaggio per aggiungerlo a una risposta proxy personalizzata (ovvero, inviarlo al client).

Ecco il criterio Estrai variabili che estrae le informazioni user_message in una variabile denominata standard.systemMessage: 

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

Ora, ecco un criterio Assegna messaggio perfettamente valido che aggiunge la variabile estratta al payload della risposta (la risposta 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>


Purtroppo si è verificato un problema. Il criterio per l'estrazione delle variabili ha rimosso le virgolette di escape intorno a una parte del messaggio. Ciò significa che la risposta restituita al client è un JSON non valido. È evidente che non è quello che intendevi. 

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

Per risolvere questo problema, puoi modificare il criterio Assegna messaggio in modo che utilizzi una funzione del modello di messaggio che esegue automaticamente l'escape delle virgolette all'interno del file JSON. Questa funzione, escapeJSON(), esegue l'escape di eventuali virgolette o altri caratteri speciali che si trovano in un'espressione 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 funzione esegue l'escape delle virgolette incorporate, generando un JSON valido, che è esattamente ciò che volevi: 

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

Un modello di messaggio è una funzionalità di sostituzione delle stringhe dinamica che puoi utilizzare in determinati criteri e nelle definizioni di TargetEndpoint. Le funzioni del modello di messaggio consentono di eseguire utili operazioni come l'hashing, la manipolazione delle stringhe, l'escape dei caratteri e altre all'interno di un modello di messaggio.

Ad esempio, nel seguente criterio AttributionMessage, la funzione toLowerCase() viene utilizzata in un modello di messaggio:

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

Questo argomento descrive le funzioni del modello di messaggio, i relativi argomenti e gli output. Questo argomento presuppone che tu conosca i modelli di messaggi e i contesti in cui vengono utilizzati.

Funzioni hash

Calcola un valore hash e restituisci la rappresentazione stringa di quell'hash.

Funzioni hash esadecimali

Calcola un valore hash e restituisci la rappresentazione stringa di quell'hash sotto forma di numero esadecimale.

Sintassi

Funzione Descrizione
md5Hex(string) Calcola un hash MD5 espresso come numero esadecimale.
sha1Hex(string) Calcola un hash SHA1 espresso come numero esadecimale.
sha256Hex(string) Calcola un hash SHA256 espresso come numero esadecimale.
sha384Hex(string) Calcola un hash SHA384 espresso come numero esadecimale.
sha512Hex(string) Calcola un hash SHA512 espresso come numero esadecimale.

Argomenti

string - Le funzioni hash prendono un singolo argomento stringa su cui viene calcolato l'algoritmo hash. L'argomento può essere una stringa letterale o una variabile di flusso stringa.

Esempi

Chiamata funzione: 

sha256Hex('abc')

Risultato: 

ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad

Chiamata funzione: 

var str = 'abc';
sha256Hex(str)

Risultato: 

ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad

Funzioni hash Base64

Calcola un valore hash e restituisci la rappresentazione stringa di quell'hash come valore codificato in Base64.

Sintassi

Funzione Descrizione
md5Base64(string) Calcola un hash MD5 espresso come valore codificato in Base64.
sha1Base64(string) Calcola un hash SHA1 espresso come valore codificato in Base64.
sha256Base64(string) Calcola un hash SHA256 espresso come valore codificato in Base64.
sha384Base64(string) Calcola un hash SHA384 espresso come valorer codificato in Base64.
sha512Base64(string) Calcola un hash SHA512 espresso come valore codificato in Base64.

Argomenti

string - Le funzioni hash prendono un singolo argomento stringa su cui viene calcolato l'algoritmo hash. L'argomento può essere una stringa letterale o una variabile di flusso stringa.

Esempi

Chiamata funzione: 

sha256Base64('abc')

Risultato: 

ungWv48Bz+pBQUDeXa4iI7ADYaOWF3qctBD/YfIAFa0=

Chiamata funzione: 

var str = 'abc';
sha256Base64(str)

Risultato: 

ungWv48Bz+pBQUDeXa4iI7ADYaOWF3qctBD/YfIAFa0=

Funzioni di stringa

Eseguire operazioni sulle stringhe all'interno di un modello di messaggio.

Funzioni di codifica Base64

Codifica e decodifica le stringhe utilizzando lo schema di codifica Base64.

Sintassi

Funzione Descrizione
encodeBase64(string) Codifica una stringa utilizzando la codifica Base64. Ad esempio: encodeBase64(value), quando value contiene abc, la funzione restituisce la stringa: YWJj
decodeBase64(string) Decodifica una stringa con codifica Base64. Ad esempio: decodeBase64(value), quando value contiene aGVsbG8sIHdvcmxk, la funzione restituisce la stringa hello, world.

Argomenti

string - La stringa da codificare o decodificare. Può essere una stringa letterale o una variabile di flusso stringa.

Esempio

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

Funzioni di conversione delle richieste di assistenza

Converti una stringa in lettere tutte maiuscole o tutte minuscole.

Sintassi

Funzione Descrizione
toUpperCase(string) Convertire una stringa in lettere maiuscole.
toLowerCase(string) Convertire una stringa in minuscolo.


Argomenti

string - La stringa da convertire. Può essere una stringa letterale o una variabile di flusso stringa.

Esempio

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

Funzione sottostringa

Restituisce i caratteri compresi tra l'indice iniziale e finale della stringa specificata.

Sintassi

substring(str,start_index,end_index)

Argomenti

  • str: una stringa letterale o variabile di flusso stringa.
  • start_index - L'indice iniziale nella stringa.
  • end_index - (Facoltativo) L'indice finale nella stringa. Se non viene specificato, l'indice finale è la fine della stringa.

Esempi

Per i seguenti esempi, supponiamo che esistano queste variabili di flusso:

Nome variabile Valore
alpha ABCDEFGHIJKLMNOPQRSTUVWXYZ
seven 7


Ecco i risultati delle chiamate di funzione che utilizzano queste variabili:

Espressione del modello di messaggio Risultato
{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

Funzione Sostituisci tutto

Applica un'espressione regolare a una stringa e, per eventuali corrispondenze, sostituisce la corrispondenza con un valore sostitutivo.

Sintassi

replaceAll(string,regex,value)

Argomenti

  • string: una stringa letterale o variabile di flusso stringa in cui eseguire sostituzioni.
  • regex: un'espressione regolare.
  • value - Il valore per sostituire tutte le corrispondenze regex all'interno della stringa.

Esempi

Per i seguenti esempi, supponiamo che esistano queste variabili di flusso:

Nome variabile Valore
header Bearer ABCDEFGHIJKLMNOPQRSTUVWXYZ-9993
regex1 "^Bearer "
replacement "TOKEN: "

Ecco i risultati delle chiamate di funzione che utilizzano queste variabili:

Espressione del modello di messaggio Risultato
{replaceAll(header,"9993",'')} Bearer ABCDEFGHIJKLMNOPQRSTUVWXYZ-
{replaceAll(header,regex1,'')} ABCDEFGHIJKLMNOPQRSTUVWXYZ-9993
{replaceAll(header,regex1,replacement)} TOKEN: ABCDEFGHIJKLMNOPQRSTUVWXYZ-9993

Sostituisci prima funzione

Sostituisce solo la prima occorrenza della corrispondenza dell'espressione regolare specificata nella stringa.

Sintassi

replaceFirst(string,regex,value)

Argomenti

  • string: una stringa letterale o variabile di flusso stringa in cui eseguire sostituzioni.
  • regex: un'espressione regolare.
  • value - Il valore da sostituire all'espressione regolare all'interno della stringa.

Carattere di escape e funzioni di codifica

Funzioni che eseguono l'escape o codificano i caratteri speciali in una stringa.

Sintassi

Funzione Descrizione
escapeJSON(string) Esegue l'escape delle virgolette doppie.
escapeXML(stringa) Sostituisce le parentesi angolari, l'apostrofo, le virgolette e la e commerciale con le rispettive entità XML. Da utilizzare per i documenti XML 1.0.

escapeXML11(stringa) Funziona allo stesso modo di escapeXML, ma per le entità XML v1.1. Consulta le note sull'utilizzo riportate di seguito.
encodeHTML(stringa) Codifica l'apostrofo, le parentesi angolari e la e commerciale.

Argomenti

string - La stringa da cui eseguire l'escape. Può essere una stringa letterale o una variabile di flusso stringa.

Note sull'utilizzo

XML 1.1 può rappresentare determinati caratteri di controllo, ma non può rappresentare il byte null o i punti di codice surrogati Unicode non associati, anche dopo l'escape. La funzione escapeXML11() rimuove i caratteri che non rientrano nei seguenti intervalli: 

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

La funzione escapeXML11() esegue l'escape dei caratteri nei seguenti intervalli: 

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

Esempi

Supponiamo che esista una variabile di flusso denominata food con questo valore: "bread" & "butter". Quindi, la funzione: 

{escapeHTML(food)}

porta a:

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

Funzioni di formato dell'ora

Restituisce una rappresentazione stringa dell'ora nel formato UTC o nel fuso orario locale.

Sintassi

Funzione Descrizione
timeFormat(format,str) Restituisce la data formattata nel fuso orario locale.
timeFormatMs(format,str) Restituisce la data formattata nel fuso orario locale.
timeFormatUTC(format,str) Restituisce la data formattata nel fuso orario UTC.
timeFormatUTCMs(format,str) Restituisce la data formattata nel fuso orario UTC.

Argomenti

  • format - Una stringa di formato di data/ora. Può essere una stringa letterale o una variabile stringa.
  • str - Una stringa o variabile di flusso stringa contenente un valore di tempo. Il valore può essere in millisecondi-since-epoch o millisecondi-since-epoch per timeFormatMs.

Esempi

Supponiamo che tu abbia i seguenti valori e che il fuso orario locale sia il Pacifico:

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

Le funzioni restituiscono i seguenti risultati:

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

    Funzioni di calcolo HMAC

    Le funzioni di calcolo HMAC forniscono un'alternativa all'utilizzo del criterio HMAC per calcolare un HMAC. Le funzioni sono utili quando si esegue un calcolo HMAC a cascata, come quando l'output di un HMAC viene utilizzato come chiave per un secondo HMAC.

    Sintassi

    Funzione Descrizione
    hmacSha224(key,valueToSign[,keyencoding[,outputencoding]]) Calcola un HMAC con la funzione hash SHA-224.
    hmacSha256(key,valueToSign[,keyencoding[,outputencoding]]) Codifica un HMAC con la funzione hash SHA-256.
    hmacSha384(key,valueToSign[,keyencoding[,outputencoding]]) Codifica un HMAC con la funzione hash SHA-384.
    hmacSha512(key,valueToSign[,keyencoding[,outputencoding]]) Codifica un HMAC con la funzione hash SHA-512.
    hmacMd5(key,valueToSign[,keyencoding[,outputencoding]]) Codifica un HMAC con la funzione hash MD5.
    hmacSha1(key, valueToSign [,keyencoding[,outputencoding]]) Codifica un HMAC con l'algoritmo di crittografia SHA-1.

    Argomenti

    • key - (Obbligatorio) Specifica la chiave segreta, codificata come stringa, utilizzata per calcolare l'HMAC.
    • valueToSign - (Obbligatorio) Specifica il messaggio da firmare. Deve essere una stringa.
    • keyencoding: (facoltativo): la stringa della chiave secret verrà decodificata in base a questa codifica specificata. Valori validi: hex, base16, base64, utf-8. Valore predefinito: utf-8
    • outputencoding - (Facoltativo) Specifica l'algoritmo di codifica da utilizzare per l'output. Valori validi: hex, base16, base64. I valori non fanno distinzione tra maiuscole e minuscole; hex e base16 sono sinonimi. Valore predefinito: base64

    Esempi

    In questo esempio viene utilizzato il criterio AssegnaMessage per calcolare un codice HMAC-256 e assegnarlo a una variabile di flusso: 

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

    Questo esempio illustra come generare un HMAC a cascata che possa essere utilizzato con il processo di firma di AWS Signature v4. L'esempio utilizza il criterioAssignMessage per generare i cinque livelli di HMAC a cascata utilizzati per calcolare una firma per 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>

    Altre funzioni

    Crea funzione UUID

    Genera e restituisce un UUID.

    Sintassi

    createUuid()

    Argomenti

    Nessuna.

    Esempio

    {createUuid()}

    Risultato di esempio: 

    ec3ca9be-d1e1-4ef4-aee4-4a58f3130db8

    Funzione generatore lungo casuale

    Restituisce un numero intero lungo casuale.

    Sintassi

    randomLong(args)

    Argomenti

    • Se non vengono specificati argomenti, la funzione restituisce un numero intero lungo casuale, calcolato dalla classe SecureRandom di Java.
    • Se è presente un argomento, viene considerato il valore minimo del calcolo.
    • Se è presente un secondo argomento, viene considerato il valore massimo del calcolo.

    Esempio

    {random()}

    il risultato sarà simile al seguente: 

    5211338197474042880

    Generatore di testo regex

    Genera una stringa di testo che corrisponde a una determinata espressione regolare.

    Sintassi

    xeger(regex)

    Argomento

    regex: un'espressione regolare.

    Esempio

    Questo esempio genera una stringa di sette cifre senza zero: 

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

    Risultato di esempio: 

    9857253

    Funzione di coalescenza null

    La funzione firstnonnull() restituisce il valore dell'argomento non null all'estrema sinistra.

    Sintassi

    firstnonnull(var1,varn)

    Argomento

    var1: una variabile di contesto.

    varn: una o più variabili di contesto. Puoi impostare l'argomento più a destra su una stringa per fornire un valore di riserva (un valore che verrà impostato se non viene impostato nessuno degli argomenti a sinistra).

    Esempi

    La tabella seguente illustra come utilizzare la funzione:

    Modello Var1 Var2 Var3 Risultato
    {firstnonnull(var1,var2)} Non impostato foo N/A foo
    {firstnonnull(var1,var2)} foo bar N/A foo
    {firstnonnull(var1,var2)} foo Non impostato N/A foo
    {firstnonnull(var1,var2,var3)} foo bar baz foo
    {firstnonnull(var1,var2,var3)} Non impostato bar baz bar
    {firstnonnull(var1,var2,var3)} Non impostato Non impostato baz baz
    {firstnonnull(var1,var2,var3)} Non impostato Non impostato Non impostato null
    {firstnonnull(var1)} Non impostato 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

    Funzione XPath

    Applica un'espressione XPath a una variabile XML.

    Sintassi

    xpath(xpath_expression,xml_string,[datatype])

    Argomenti

    xpath_expression: un'espressione XPath.

    xml_string: una variabile di flusso o una stringa contenente XML.

    datatype - (Facoltativo) Specifica il tipo restituito desiderato della query. Può essere un set di nodi, un nodo, un numero, un booleano o una stringa. Il valore predefinito è nodeset. L'impostazione predefinita è in genere la scelta giusta.

    Esempio 1

    Supponiamo che queste variabili di contesto definiscano una stringa XML e un'espressione XPath: 

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

    Inoltre, la funzione xpath() viene utilizzata in un criterio AssegnaMessage, come indicato di seguito: 

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

    La funzione restituisce il valore <tagid>250397</tagid>. Questo valore viene inserito nella variabile di contesto denominata extracted_tag.

    Esempio 2

    Se vuoi solo il valore del nodo, utilizza la funzione text(), come segue:

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

    Come risultato di questa operazione, la variabile di contesto extracted_tag è impostata su 250397

    Se sono selezionati più nodi, il risultato di xpath() sarà costituito da tutti i valori della selezione, concatenati con una virgola.

    Esempio 3: spazi dei nomi XML

    Per specificare uno spazio dei nomi, aggiungi parametri aggiuntivi, ognuno con una stringa simile a prefix:namespaceuri. Ad esempio, una funzione xpath() che seleziona l'elemento figlio di un corpo SOAP potrebbe essere la seguente: 

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

    Per ulteriori spazi dei nomi, puoi aggiungere fino a 10 parametri aggiuntivi alla funzione xpath().

    Puoi specificare una semplice espressione XPath come stringa racchiusa tra virgolette singole:

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

    Se l'espressione XPath include prefissi dello spazio dei nomi (e due punti), devi assegnare l'espressione XPath a una variabile e specificare il nome della variabile anziché direttamente l'espressione.

    {xpath(xpathexpression,xml,ns1)}

    Esempio 4: specifica del tipo restituito desiderato

    Il terzo parametro facoltativo passato alla funzione xpath() specifica il tipo restituito desiderato della query.

    Alcune query XPath possono restituire valori numerici o booleani. Ad esempio, la funzione count() restituisce un numero. Questa è una query XPath valida: 

    count(//Record/Fields/Pair)

    Questa query valida restituisce un valore booleano: 

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

    In questi casi richiama la funzione xpath() con un terzo parametro che specifica tale tipo: 

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

    Se il terzo parametro contiene i due punti, viene interpretato come argomento dello spazio dei nomi. In caso contrario, viene considerato il tipo restituito desiderato. In questo caso, se il terzo parametro non è uno dei valori validi (senza distinzione tra maiuscole e minuscole), la funzione xpath() restituisce per impostazione predefinita un set di nodi.

    Funzione percorso JSON

    Applica un'espressione Percorso JSON a una variabile JSON.

    Sintassi

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

    Argomenti

    • (Obbligatorio) json-path: (stringa) un'espressione di percorso JSON.
    • (Obbligatorio) json-var: (stringa) una variabile di flusso o una stringa contenente JSON.
    • (Facoltativo) want-array: (stringa) se questo parametro è impostato su 'true' e se il set di risultati è un array, vengono restituiti tutti gli elementi dell'array. Se impostato su un altro valore o se questo parametro viene omesso, viene restituito solo l'elemento zero di un array del set di risultati. Se il set di risultati non è un array, questo terzo parametro, se presente, viene ignorato.

    Esempio 1

    Se questo è il modello del messaggio:

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

    e the_json_variable contiene:

    {
  "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"
    }
  ]
}

    Il risultato della funzione è:

    The address is 1060 West Addison Street

    Tieni presente che in questo caso, il set di risultati è un singolo elemento (non un array di elementi). Se il set di risultati fosse un array, verrà restituito solo l'elemento zero di quell'array. Per restituire l'array completo, chiama la funzione con 'true' come terzo parametro, come mostrato nell'esempio successivo.

    Esempio 2

    Se questo è il modello del messaggio:

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

    e the_json_variable contiene:

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

    Il risultato della funzione è:

    ['A','B']