Questa pagina si applica ad Apigee e Apigee hybrid.
Visualizza la documentazione di Apigee Edge.
Questo argomento illustra come utilizzare i modelli di messaggio nei proxy API e fornisce un riferimento alle funzioni.
Che cos'è un modello di messaggio?
Un modello di messaggio consente di eseguire una sostituzione di stringhe variabili in determinati criteri e 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 alle variabili di flusso e testo letterale in un modello di messaggio. I nomi delle variabili di flusso devono essere racchiusi tra parentesi graffe, mentre il testo che non è tra parentesi graffe viene restituito come testo letterale.
Vedi anche Dove puoi utilizzare i modelli di messaggio?
Esempio
Ad esempio, il criterioAssignMessage 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) verrà valutato e sostituito nella stringa del payload in fase di 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 insieme a una "regola di errore" per fornire un output al chiamante sulla violazione della quota. Nel seguente criterioAssignMessage, i modelli di messaggio 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> </Set> </AssignMessage>
Nel criterioAssignMessage, i seguenti elementi nell'elemento <Set>
supportano i modelli dei messaggi:
<Header>
<QueryParam>
<FormParam>
<PayLoad>
<Version>
<Verb>
<Path>
<StatusCode>
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 parametro
client_id
viene compilato dinamicamente). <StatusCode>
include solo testo letterale; tuttavia, questo elemento supporta anche i modelli dei messaggi, se vuoi utilizzarlo.
Esempio
In una definizione di <TargetEndpoint>
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 quando il proxy viene eseguito.
<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 messaggio sono supportati da diversi criteri e da alcuni elementi utilizzati nella configurazione di TargetEndpoint.
Criteri che accettano modelli di messaggi
Nella tabella seguente sono elencati i criteri e gli elementi/elementi secondari supportati:
Norme | Elementi/elementi secondari |
---|---|
Criterio di AccessControl | <SourceAddress> , per l'attributo mask e l'indirizzo IP. |
CriterioAssignMessage | Elementi secondari di <Set> : Payload, ContentType, Verb, Version, Path, StatusCode, Headers, QueryParams, FormParams
Elementi secondari di
|
Criterio CORS | |
Criterio ExtractVariables | <JsonPath>
|
Criterio GeneraJWS Criterio VerificationJWS |
* Questi elementi supportano i modelli di messaggi solo se type=map. |
Criterio GeneraJWT Criterio VerificationJWT |
<AdditionalClaims><Claim>
* Questi elementi supportano i modelli di messaggi solo se type=map. |
Criterio HTTPModifier | <Set> elementi secondari:
|
Norme di MessageLogging |
|
Norme di OASValidation | elemento
|
Criterio RaiseFault |
Elementi
Elementi
|
Criterio SAMLAssertion | <Template>
* Solo se la firma del criterio è |
Norme sui callout di servizio |
Elementi
Elementi
|
<TargetEndpoint>
elementi che accettano modelli di messaggi
<HTTPTargetConnection> elemento |
Elementi secondari che supportano i modelli di messaggi |
---|---|
<SSLInfo> |
<Enabled> , <KeyAlias> , <KeyStore> ,
<TrustStore> , <ClientAuthEnabled> ,
<CLRStore>
|
<LocalTargetConnection> |
<ApiProxy> , <ProxyEndpoint> , <Path> |
<Path> |
N/D |
<URL> |
Nessun elemento secondario. Per l'utilizzo, consulta la sezione Modelli di URL. |
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 da sostituire se la variabile non è stata risolta). Consulta la pagina relativa all'impostazione dei 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>
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:
Consentiti:
{substring(alpha,0,4)} {createUuid()} {randomLong(10)}
Non consentiti:
{substring( alpha, 0, 4 )} { createUuid( ) } {randomLong( 10 )}
Le funzioni nidificate non sono supportate
Non è possibile richiamare una funzione all'interno di un'altra funzione in un modello. Ad esempio, non puoi utilizzare:
{substring({timeFormat('yyyy-MM-dd','1494390266')},0,4)}
Racchiudi i valori letterali stringa nelle funzioni del modello tra virgolette singole
Quando fornisci valori letterali stringa nelle funzioni, racchiudili tra virgolette singole anziché virgolette doppie.
Ad esempio:{replaceAll('BEARER: 1234','^Bearer ','TOKEN:')}
Evita di utilizzare caratteri speciali nei valori letterali stringa
Evita i caratteri speciali, come ':', '/', '\', '<' o '>', nei valori letterali stringa. Questi caratteri possono causare errori. Se un valore letterale stringa richiede caratteri speciali, assegna il valore a una variabile utilizzando un criterio Python o JavaScript, quindi utilizza la variabile nel modello.
L'impostazione di valori predefiniti nei modelli di messaggi
Se non è possibile risolvere una variabile basata su modelli, Apigee 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
Modelli URL
L'elemento URL
supporta i modelli che seguono la stessa sintassi degli altri elementi.
Questo esempio mostra un URL creato utilizzando le variabili:
<URL>{targeturl}</URL>
Questo esempio mostra un valore predefinito per il protocollo:
<URL>{protocol:https}://{site:google.com}/path</URL>
Sintassi precedente per i payload JSON
Nelle versioni di Apigee prima del rilascio di Cloud 16.08.17, non era possibile utilizzare parentesi graffe per indicare i riferimenti 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 mandare a capo i nomi delle variabili, ad esempio:
<Set> <Payload contentType="application/json" variablePrefix="@" variableSuffix="#"> {"name":"foo","type":"@variable_name#"} </Payload> </Set>
Anche se Apigee consiglia di utilizzare la più recente sintassi di parentesi graffe, la sintassi precedente continua a funzionare.
Utilizzo delle funzioni per i modelli di messaggi
Apigee offre 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 di stringa, come descritto di seguito.
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 viene 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 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 AssegnaMessage per aggiungerlo a una risposta proxy personalizzata (ovvero, inviarlo al client).
Questo è il criterio ExtractVariables 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 criterioAssignMessage perfettamente valido che aggiunge la variabile estratta al payload di 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 ExtractVariables ha rimosso le virgolette con caratteri 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 di AttributionMessage in modo da utilizzare una funzione per il modello di messaggio che esegue l'escape delle virgolette all'interno del file JSON. Questa funzione, escapeJSON()
, esegue l'escape delle virgolette o di 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 sottopone a escape le virgolette incorporate, generando un JSON valido, che è esattamente quello che volevi:
{ "systemMessage": "Invalid value for \"logonId\" check your input.", }
Un modello di messaggio è una funzionalità di sostituzione dinamica delle stringhe che puoi utilizzare in determinati criteri e
nelle definizioni di <TargetEndpoint>
. Le funzioni del modello di messaggio consentono di eseguire operazioni utili come hashing, manipolazione delle stringhe, 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>
Questa sezione descrive le funzioni del modello di messaggio, i relativi argomenti e output. Questo argomento presuppone che tu abbia familiarità con 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 esadecimale
Calcola un valore hash e restituisci la rappresentazione 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 viene calcolato l'algoritmo hash. L'argomento può essere una stringa letterale
(racchiusa tra virgolette singole) 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 valorere 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
(racchiusa tra virgolette singole) 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 codificata 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
(racchiusa tra virgolette singole) 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)
|
Converte una stringa in lettere maiuscole. |
toLowerCase(string)
|
Converte una stringa in minuscolo. |
Argomenti
string
: la stringa da convertire. Può essere una stringa letterale
(racchiusa tra virgolette singole) 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 di sottostringa
Restituisce i caratteri tra l'indice iniziale e quello finale della stringa specificata.
Sintassi
substring(str,start_index,end_index)
Argomenti
str
: una stringa letterale (racchiusa tra virgolette singole) o una 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, in caso di corrispondenze, sostituisce la corrispondenza con un valore sostitutivo.
Sintassi
replaceAll(string,regex,value)
Argomenti
- string: una stringa letterale (racchiusa tra virgolette singole) o una variabile di flusso della 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 (racchiusa tra virgolette singole) o una variabile di flusso di stringa in cui eseguire sostituzioni.regex
: un'espressione regolare.value
: il valore da sostituire alle corrispondenze con un'espressione regolare all'interno della stringa.
Carattere di escape e funzioni di codifica
Funzioni che codificano o eseguono l'escape dei caratteri speciali in una stringa.
Sintassi
Funzione | Descrizione |
---|---|
escapeJSON(string)
|
Esegue l'escape delle virgolette. |
escapeXML(string)
|
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(string) |
Funziona allo stesso modo di escapeXML, ma per le entità XML v1.1. Consulta le note sull'utilizzo di seguito. |
encodeHTML(string)
|
Codifica l'apostrofo, le parentesi angolari e la e commerciale. |
Argomenti
string
: la stringa in cui eseguire l'escape. Può essere una stringa letterale
(racchiusa tra virgolette singole)
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)}
Risultati in:
"bread" & "butter"
Funzioni di formato dell'ora
Restituisce una rappresentazione stringa dell'ora nel formato UTC.
Sintassi
Funzione | Descrizione |
---|---|
timeFormat(format,str)
|
Restituisce la data formattata in UTC. DEPRECATED: restituisce la data nel fuso orario locale. |
timeFormatMs(format,str)
|
Restituisce la data formattata in UTC. DEPRECATED: restituisce la data nel fuso orario locale. |
timeFormatUTC(format,str)
|
Restituisce la data formattata in UTC. |
timeFormatUTCMs(format,str)
|
Restituisce la data formattata in UTC. |
Argomenti
format
: una stringa di formato di data/ora. Può essere una stringa letterale (racchiusa tra virgolette singole) o una variabile stringa. Utilizza una variabile anziché un valore letterale se il formato include i due punti. Vedi la nota precedente in questa sezione.str
: una variabile di flusso stringa o stringa contenente un valore di tempo. Il valore può essere in seconds-since-epoch o millisecondi-since-epoch per timeFormatMs.
Esempi
Supponi i seguenti valori e supponiamo 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 segreta 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
ebase16
sono sinonimi. Valore predefinito:base64
Esempi
Questo esempio utilizza il criterio AttributionMessage 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 può essere utilizzato con il processo di firma AWS Signature v4. L'esempio utilizza il criterio AttributionMessage 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
Nessuno.
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 Java SecureRandom.
- Se è presente un argomento, viene considerato il valore minimo del calcolo.
- Se è presente un secondo argomento, viene considerato il valore massimo del calcolo.
Esempio
{randomLong()}
I risultati saranno simili 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 null
La funzione firstnonnull()
restituisce il valore dell'argomento non null più a 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 impostata | foo
|
N/D | foo
|
{firstnonnull(var1,var2)}
|
foo
|
bar
|
N/D | foo
|
{firstnonnull(var1,var2)}
|
foo
|
Non impostata | N/D | foo
|
{firstnonnull(var1,var2,var3)}
|
foo
|
bar
|
baz
|
foo
|
{firstnonnull(var1,var2,var3)}
|
Non impostata | bar
|
baz
|
bar
|
{firstnonnull(var1,var2,var3)}
|
Non impostata | Non impostata | baz
|
baz
|
{firstnonnull(var1,var2,var3)}
|
Non impostata | Non impostata | Non impostata | null
|
{firstnonnull(var1)}
|
Non impostata | N/D | N/A | null
|
{firstnonnull(var1)}
|
foo
|
N/A | N/A | 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 restituito della query. I valori validi sono nodeset
, node
, number
, boolean
o string
. Il valore predefinito è nodeset
. In genere 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"
Inoltre, 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 nella
variabile di contesto denominata extracted_tag
.
Esempio 2: spazi dei nomi XML
Per specificare uno spazio dei nomi, aggiungi ulteriori parametri, ognuno dei quali è una stringa simile a prefix:namespaceuri
. Ad esempio, una funzione xpath()
che seleziona l'elemento secondario 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 alla funzione xpath()
.
Anziché specificare espressioni XPath con caratteri speciali come valore letterale stringa, utilizza una variabile per includere questa stringa nella funzione. Per maggiori dettagli, consulta Evitare di utilizzare caratteri speciali nei valori letterali stringa.
{xpath(xpathexpression,xml,ns1)}
Esempio 3: 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 quel tipo:
{xpath(expression,xml,'number')} {xpath(expression,xml,'boolean')}
Se il terzo parametro contiene i due punti, viene interpretato come un 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 questo parametro è impostato su'true'
e se il set di risultati è un array, vengono restituiti tutti gli elementi dell'array. Se impostato su qualsiasi 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 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, il set di risultati è un singolo elemento (non un array di elementi). Se
il set di risultati fosse un array, verrà restituito solo il valore zero dell'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 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']