Modelli di messaggio

Stai visualizzando la documentazione di Apigee Edge.
Vai alla sezione Documentazione di Apigee X. Informazioni

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

Che cos'è un modello di messaggio?

Un modello di messaggio consente di eseguire la sostituzione di stringhe variabili in determinati elementi di criteri e TargetEndpoint. Questa funzionalità, se supportata, consente di compilare le stringhe in modo dinamico durante l'esecuzione di un proxy.

In un modello di messaggio puoi includere qualsiasi combinazione di riferimenti alle variabili di flusso e testo letterale. I nomi delle variabili di flusso devono essere racchiusi tra parentesi graffe, mentre qualsiasi testo non compreso tra parentesi graffe viene restituito come testo letterale.

Vedi anche Dove puoi utilizzare i modelli di messaggio?

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 (tra parentesi graffe) sarà valutate e sostituite nella stringa del payload in fase di runtime. 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 generata una stringa vuota.

Esempio

Quando viene superata una quota, è buona norma restituire un messaggio significativo al chiamante. Questo Il pattern è comunemente usato con una "regola di errore" per fornire un output per fornire informazioni al chiamante sulla violazione della quota. Nel criterio Assegna messaggio di seguito vengono usati i modelli di messaggio. per compilare le informazioni sulla quota in modo dinamico 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 AssegnaMessage, i seguenti elementi in <Set> modelli messaggi di supporto elementi:

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

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

Quando viene eseguito questo criterio:

• Gli elementi Header ricevono i valori delle variabili di flusso specificate.
• Il payload include una combinazione di testo letterale e variabili (il campo client_id viene compilato in modo dinamico).
• StatusCode e ReasonPhrase includono solo testo letterale; Tuttavia, questi elementi supportano anche la creazione di modelli di messaggi, se vuoi utilizzarli.

Esempio

In una definizione di TargetEndpoint del proxy, gli elementi figlio di <SSLInfo> supportano i modelli dei messaggi. Seguendo lo stesso pattern utilizzato nei criteri, le variabili di flusso tra 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 messaggio?

I modelli di messaggio sono supportati da diversi criteri e da 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 AccessControl	<SourceAddress>, per l'attributo mask e il valore Indirizzo IP.
CriterioAssignMessage	Elementi secondari di <Set>: Payload, ContentType, Verb, Version, Path, StatusCode, ReasonPhrase, Headers, QueryParams, FormParams Elementi secondari di <Add>: Headers, QueryParams, FormParams <AssignVariable> Elemento secondario: <Template>
Norme sui callout estensioni	<Input>
Criterio ETL (ExtractVariables)	<JsonPath>
Criterio di generazione JWS Verifica JWS	<Payload> (solo per il criterio GenerateJWS) <AdditionalHeaders><Claim> * Questi elementi supportano il modello di messaggio solo se type=map.
Criterio di generazione JWT VerifyJWT policy (Verifica criterio JWT)	<AdditionalClaims><Claim> <AdditionalHeaders><Claim> * Questi elementi supportano il modello di messaggio solo se type=map.
Criterio LDAP	<SearchQuery>
Criterio MessageLogging	<Syslog><Message> <File><Message>
Norme di OASValidation	<OASResource> elemento
Criterio RaiseFault	Elementi <Set>: Payload, ContentType, Verb, Version, Path, StatusCode, ReasonPhrase, Headers, QueryParams, FormParams Elementi <Add>: Headers, QueryParams, FormParams
Criterio SAMLAssertion	<Template> * Solo quando la firma del criterio è <GenerateSAMLAssertion>
Norme relative a ServiceCallout	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/D

Sintassi del modello di messaggio

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

Utilizza parentesi graffe per indicare le variabili

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

Tieni presente che racchiudere tra virgolette l'intera stringa del modello di messaggio è consentito, ma facoltativo. Ad esempio, i seguenti due modelli di messaggio 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 messaggi

Se non è possibile risolvere una variabile basata su modello, 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, allora il suo valore è sostituito da Unknown. Ad esempio:

Test message. id = Unknown

Gli spazi non sono consentiti nelle espressioni di funzione

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

Consentiti:

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

Non consentiti:

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

Sintassi legacy per i payload JSON

Nelle versioni Edge prima della release 16.08.17 di Cloud, non utilizzare parentesi graffe per indicare i riferimenti alle variabili all'interno dei payload JSON. In queste versioni precedenti, è necessario utilizzare gli attributi variablePrefix e variableSuffix per specificare delimitatori 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>

Anche se Apigee consiglia di utilizzare la nuova sintassi con parentesi graffe, quella precedente continua a funzionare.

Utilizzo delle funzioni per i modelli di messaggi

Edge offre un insieme di funzioni che puoi utilizzare all'interno dei modelli di messaggio per eseguire l'escape, la codifica, l'hashing e formattare le variabili stringa.

Le funzioni del modello di messaggio sono descritte in dettaglio in Modello di messaggio funzione di riferimento.

Esempio: toLowerCase()

Usa 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 il problema foo.bar non viene risolto, viene sostituito il valore predefinito FOO. convertite 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 di voler restituire questo messaggio al chiamante del client in un payload personalizzato. In genere, puoi estrarre il messaggio dal payload della risposta di destinazione e utilizzare l'opzione 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>

Ecco un criterio Assegna messaggio perfettamente valido che aggiunge la variabile estratta al payload della risposta (la risposta del 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 Estrai variabili ha rimosso le virgolette di escape presenti in una parte del messaggio. Ciò significa che la risposta restituita al client è in formato JSON non valido. È chiaro 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 di modello di messaggio che esegua automaticamente l'interpretazione letterale delle virgolette all'interno del file JSON. La funzione escapeJSON() esegue l'escape di eventuali virgolette o altri caratteri speciali presenti all'interno di 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 quello che volevi:

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

Un messaggio modello è una funzionalità di sostituzione delle stringhe dinamica che puoi usare in alcuni criteri nelle definizioni di TargetEndpoint. Le funzioni dei modelli di messaggi ti consentono di eseguire operazioni utili come hashing, manipolazione delle stringhe, escape di caratteri e altro ancora all'interno di un modello di messaggio.

Ad esempio, nel seguente criterio AssegnaMessage, la funzione toLowerCase() viene utilizzata in una 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 output. Questo argomento presuppone con cui hai familiarità con messaggi modelli e i contesti in cui vengono utilizzati.

Funzioni hash

Calcola un valore hash e restituisce la rappresentazione in formato stringa di quell'hash.

Funzioni hash esadecimali

Calcola un valore hash e restituisce la rappresentazione in formato stringa di quell'hash come 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 che viene calcolato dall'algoritmo hash. L'argomento può essere una stringa letterale o una variabile di flusso di stringhe.

Esempi

Chiamata funzione:

sha256Hex('abc')

Risultato:

ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad

Chiamata funzione:

var str = 'abc';
sha256Hex(str)

Risultato:

ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad

Funzioni hash Base64

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

Sintassi

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

Argomenti

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

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 blocca abc, la funzione restituisce la stringa: YWJj
decodeBase64(string)	Decodifica una stringa codificata in Base64. Ad esempio: decodeBase64(value) quando value blocchi 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 di stringhe.

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)	Converti una stringa in lettere maiuscole.
toLowerCase(string)	Converti una stringa in minuscolo.

Argomenti

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

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 quello finale della stringa specificata.

Sintassi

substring(str,start_index,end_index)

Argomenti

• str - Una stringa letterale o variabile di flusso di 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 qualsiasi corrispondenza, sostituisce la corrispondenza con un valore sostitutivo.

Sintassi

replaceAll(string,regex,value)

Argomenti

• string - Una stringa letterale o variabile di flusso di stringa in cui effettuare le sostituzioni.
• regex - Un'espressione regolare.
• valore - Il valore da sostituire a 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 di espressione regolare specificata nella stringa.

Sintassi

replaceFirst(string,regex,value)

Argomenti

• string - Una stringa letterale o variabile di flusso di stringa in cui effettuare le sostituzioni.
• regex - Un'espressione regolare.
• valore - Il valore da sostituire all'espressione regolare all'interno della stringa.

Caratteri di escape e funzioni di codifica

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

Sintassi

Funzione	Descrizione
escapeJSON(stringa)	Barra inversa consente di evitare le virgolette doppie.
escapeXML(stringa)	Sostituisce le parentesi angolari, l'apostrofo, le virgolette doppie e la e commerciale con le rispettive entità XML. Da utilizzare per i documenti XML 1.0.
escapeXML11(stringa)	Funziona come escapeXML, ma per le entità XML v1.1. Consulta le note sull'utilizzo riportate di seguito.
encodeHTML(string)	Codifica apostrofo, parentesi angolari ed e commerciale.

Argomenti

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

Note sull'utilizzo

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

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

La funzione escapeXML11() applica una sequenza di escape ai caratteri negli intervalli seguenti:

[#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:

"bread" & "butter"

Funzioni di formato dell'ora

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

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 con il formato data/ora. Può essere una stringa letterale o una variabile stringa.
• str - Una stringa o variabile di flusso stringa contenente un valore temporale. Il valore può essere espresso in secondi da epoca o millisecondi da epoca per timeFormatMs.

Esempi

Supponi che i seguenti valori siano i seguenti e che il fuso orario locale sia quello del 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 offrono un'alternativa all'utilizzo del criterio HMAC per calcolare di un HMAC. Le funzioni sono utili quando si esegue un calcolo HMAC a cascata, ad esempio 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 segreta verrà decodificata in base a questa specificata per la codifica. Valori validi: hex, base16, base64, utf-8. Predefinita: 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. Predefinita: base64

Esempi

In questo esempio viene utilizzato il criterioAssignMessage per calcolare un 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 può essere utilizzato con Procedura di firma della firma AWS v4. L'esempio utilizza il criterioAssignMessage per generare i cinque livelli di HMAC a cascata utilizzato 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

Nessuno.

Esempio

{createUuid()}

Esempio di risultato:

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 Java SecureRandom.
• Se è presente un argomento, questo viene considerato come 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 zeri:

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

Risultato di esempio:

9857253

Funzione di coalescenza nulla

La funzione firstnonnull() restituisce il valore dell'argomento non nullo più a sinistra.

Sintassi

firstnonnull(var1,varn)

Argomento

var1: una variabile di contesto.

var_n: una o più variabili di contesto. Puoi impostare l'opzione più a destra a una stringa per fornire un valore di fallback (un valore che verrà impostato se nessuno dei vengono impostati gli argomenti sinistri).

Esempi

La tabella seguente illustra come utilizzare la funzione:

Modello	Var1	Var2	Var3	Risultato
{firstnonnull(var1,var2)}	Non impostato	foo	N/D	foo
{firstnonnull(var1,var2)}	foo	bar	N/D	foo
{firstnonnull(var1,var2)}	foo	Non impostato	N/D	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/D	N/D	null
{firstnonnull(var1)}	foo	N/D	N/D	foo
{firstnonnull(var1,var2)}	""	bar	N/D	""
{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 di ritorno desiderato della query. Può essere set di nodi, nodo, numero, booleano, stringa. Il valore predefinito è nodeset. Di solito l'impostazione predefinita è 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"

E la funzione xpath() viene utilizzata in un criterioAssignMessage, come segue:

<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 nel 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 vengono selezionati più nodi, il risultato di xpath() è tutti i valori della selezione, concatenata con una virgola.

Esempio 3: spazi dei nomi XML

Per specificare uno spazio dei nomi, aggiungi altri parametri, ognuno con una stringa simile prefix:namespaceuri. Ad esempio, una funzione xpath() che seleziona l'elemento figlio di un corpo SOAP potrebbe essere simile al 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 altri spazi dei nomi, puoi aggiungere fino a 10 parametri aggiuntivi al xpath() personalizzata.

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

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

Se l'espressione XPath include prefissi (e due punti), devi assegnare l'espressione XPath a una variabile e specifica il nome della variabile anziché l'espressione strato Add.

{xpath(xpathexpression,xml,ns1)}

Esempio 4: specifica di un tipo restituito desiderato

Il terzo parametro facoltativo passato alla funzione xpath() specifica il ritorno desiderato tipo di 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 quel 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 di 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 o una stringa di flusso contenente JSON.
• (Facoltativo) want-array: (stringa) se è impostato su 'true' e se il set di risultati è un array, tutti gli elementi dell'array vengono restituito. Se impostato su qualsiasi altro valore o se viene omesso, viene restituito solo viene restituito l'elemento zero di una matrice di risultati. Se il set di risultati non è un array, questo terzo parametro, se presente, viene ignorato.

di Gemini Advanced.

Esempio 1

Se questo è il modello di 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, l'insieme di risultati è un singolo elemento (non un array di elementi). Se se i risultati fossero una matrice, veniva restituito solo il valore zero dell'array. Da restituire l'array completo, chiama la funzione con 'true' come terzo parametro, come mostrato in nel prossimo esempio.

Esempio 2

Se questo è il modello di 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']