Questa pagina si applica a Apigee e Apigee ibridi.
Visualizza
documentazione di Apigee Edge.
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 criteri ed elementi <TargetEndpoint>
. Questa funzionalità, se supportata,
consente di compilare le stringhe in modo dinamico quando viene eseguito un proxy.
In un messaggio puoi includere qualsiasi combinazione di riferimenti alle variabili di flusso e testo letterale modello. 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 messaggi modelli?
Esempio
Ad esempio, il criterioAssignMessage ti consente di utilizzare un modello di messaggio nel
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. 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 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 seguente criterioAssignMessage vengono utilizzati 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> </Set> </AssignMessage>
Nel criterioAssignMessage, vengono applicati i seguenti elementi in <Set>
modelli messaggi di supporto elementi:
<Header>
<QueryParam>
<FormParam>
<PayLoad>
<Version>
<Verb>
<Path>
<StatusCode>
Anche in questo caso, le variabili di flusso in un modello di messaggio devono essere racchiuse tra tag 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 valore
client_id
è vengono compilati in modo dinamico). <StatusCode>
include solo testo letterale; Tuttavia, questo elemento supporta anche i modelli dei messaggi se vuoi usare li annotino.
Esempio
In una definizione del proxy <TargetEndpoint>
, gli elementi secondari di
Modelli dei messaggi di assistenza <SSLInfo>
. Seguindo lo stesso schema usato in
di flusso, le variabili di flusso tra parentesi graffe vengono sostituite durante l'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 utilizzata 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 AccessControl | <SourceAddress> , per l'attributo mask e il valore
Indirizzo IP. |
CriterioAssignMessage | Elementi secondari di <Set> : Payload, ContentType, Verb, Version, Path, StatusCode, Headers, QueryParams, FormParams
Elementi secondari di
|
Criterio CORS | |
Criterio ETL (ExtractVariables) | <JsonPath>
|
Criterio GenerationJWS Criterio VerifyJWS |
* Questi elementi supportano il modello di messaggio solo se type=map. |
Criterio Genera JWT Criterio JWT |
<AdditionalClaims><Claim>
* Questi elementi supportano il modello di messaggio solo se type=map. |
Criterio HTTPModifier | <Set> elementi secondari:
|
Criterio MessageLogging |
|
Norme di OASValidation | elemento
|
Criterio RaiseFault |
|
Criterio SAMLAssertion | <Template>
* Solo quando la firma del criterio è |
Norme relative a ServiceCallout |
|
<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. Consulta la sezione Modelli di URL per informazioni sull'utilizzo. |
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 nel messaggio modelli.
Tieni presente che racchiudere tra virgolette l'intera stringa del modello di messaggio è consentito, ma facoltativo. Per
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>
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 )}
Le funzioni nidificate non sono supportate
La chiamata di una funzione all'interno di un'altra funzione in un modello non è supportata. Ad esempio, non possono utilizzare:
{substring({timeFormat('yyyy-MM-dd','1494390266')},0,4)}
Racchiudi i valori letterali delle stringhe nelle funzioni del modello tra virgolette singole
Quando fornisci valori letterali di stringa nelle funzioni, racchiudili tra virgolette singole anziché doppie.
Ad esempio:{replaceAll('BEARER: 1234','^Bearer ','TOKEN:')}
Evita di utilizzare caratteri speciali nei valori letterali stringa
Evita caratteri speciali, ad esempio ":", "/", "\", "<" 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 Python o JavaScript, quindi usa la variabile nel modello.
Impostazione dei valori predefiniti nel messaggio modelli
Se una variabile basata su modelli non può essere risolta, Apigee sostituisce una stringa vuota. Tuttavia, puoi specifica 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
viene sostituito da Unknown
. Ad esempio:
Test message. id = Unknown
Modelli di URL
L'elemento URL
supporta i modelli seguendo la stessa sintassi degli altri elementi.
Questo esempio mostra un URL creato utilizzando variabili:
<URL>{targeturl}</URL>
Questo esempio mostra un valore predefinito per il protocollo:
<URL>{protocol:https}://{site:google.com}/path</URL>
Sintassi legacy per i payload JSON
Nelle versioni di Apigee 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 funziona.
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 escape, codificare, eseguire l'hashing e formattare le variabili stringa, come descritto di seguito.
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 che contiene 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. Il solito per farlo è estrarre il messaggio dal payload della risposta di destinazione e usare per aggiungerlo a una risposta del proxy personalizzata (ovvero, inviarla al client).
Ecco il criterio ExtractVariables che estrae le informazioni user_message
in una
variabile chiamata 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 alla 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 ExtractVariables ha rimosso la citazione con caratteri di escape intorno a una parte del messaggio. Ciò significa che la risposta restituita al client JSON non valido. È chiaro che non è quello che intendevi.
{ "systemMessage": "Invalid value for "logonId" check your input." }
Per risolvere questo problema, puoi modificare il criterioAssignMessage in modo da utilizzare un parametro
funzione di modello di messaggio che esegue automaticamente l'escape delle virgolette all'interno del file JSON. Questo
funzione, escapeJSON()
, fa precedere da 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 desiderato:
{ "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 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 criterioAssignMessage, la funzione toLowerCase()
è
utilizzati 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>
In questa sezione vengono descritte le funzioni del modello di messaggio, i relativi argomenti e output. Questo argomento presuppone che hai familiarità con i modelli di messaggi 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 l'algoritmo hash
viene calcolata. L'argomento può essere una stringa letterale
(racchiuse tra virgolette singole) o un 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
(racchiuse tra virgolette singole) 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
(racchiuse tra virgolette singole) o un 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)
|
Converte una stringa in lettere maiuscole. |
toLowerCase(string)
|
Converte una stringa in minuscolo. |
Argomenti
string
: la stringa da convertire. Può essere una stringa letterale
(racchiuse tra virgolette singole) o un 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 (racchiusi tra virgolette singole) o flusso di stringhe .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 (racchiusi tra virgolette singole) o flusso di stringhe 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 (racchiusi tra virgolette singole) o flusso di stringhe in cui effettuare le sostituzioni.regex
: un'espressione regolare.value
: il valore con cui sostituire le corrispondenze regex 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(string)
|
Barra inversa consente di evitare le virgolette doppie. |
escapeXML(string)
|
Sostituisce le parentesi angolari, l'apostrofo, le virgolette doppie e la e commerciale con il rispettivo codice XML le entità. Da utilizzare per i documenti XML 1.0. |
escapeXML11(string) |
Funziona come escapeXML, ma per le entità XML v1.1. Leggi 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
(racchiuse tra virgolette singole)
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
punti di codice surrogati Unicode non associati, anche dopo l'escape. 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)}
Risultati in:
"bread" & "butter"
Funzioni di formato dell'ora
Restituisce una rappresentazione stringa dell'ora, formattata nel fuso orario UTC.
Sintassi
Funzione | Descrizione |
---|---|
timeFormat(format,str)
|
Restituisce la data formattata nel fuso orario UTC. DEPRECATED: restituisce la data formattata nell'ora locale nella zona di destinazione. |
timeFormatMs(format,str)
|
Restituisce la data formattata nel fuso orario UTC. DEPRECATED: restituisce la data formattata nell'ora locale nella zona di destinazione. |
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 in formato data/ora. Può essere una stringa letterale (racchiuse tra virgolette singole) o una stringa . Utilizza una variabile anziché un valore letterale se il formato include i due punti. Vedi la nota precedente in questa sezione.str
: una stringa o una variabile di flusso stringa contenente un valore temporale. Il valore può essere 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
ebase16
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 la firma AWS 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 dal 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
{randomLong()}
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.
varn
: 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/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 o una stringa di flusso contenente XML.
datatype
: (facoltativo) specifica il tipo di ritorno desiderato della query. Valori validi
sono nodeset
, node
, number
, boolean
o
string
. 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: 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.
Anziché specificare espressioni XPath con caratteri speciali come valore letterale stringa, utilizza un'espressione per includere la stringa nella funzione. Consulta Evita di utilizzare caratteri speciali nei valori letterali stringa per i dettagli.
{xpath(xpathexpression,xml,ns1)}
Esempio 3: 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 che
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.
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']