Stai visualizzando la documentazione di Apigee Edge.
Vai alla
documentazione di Apigee X. informazioni
Questo argomento illustra come utilizzare i modelli di messaggio nei proxy API e fornisce un riferimento alla funzione.
Che cos'è un modello di messaggio?
Un modello di messaggio ti consente di eseguire una sostituzione di stringhe variabili in determinati elementi di criteri ed elementi TargetEndpoint. Questa funzionalità, se supportata, consente di compilare le stringhe in modo dinamico quando viene eseguito un proxy.
Puoi includere qualsiasi combinazione di riferimenti a variabili di flusso e testo letterale in un modello di messaggio. I nomi delle variabili di flusso devono essere racchiusi tra parentesi graffe, mentre qualsiasi testo che non sia tra parentesi graffe viene restituito come testo letterale.
Vedi anche Dove si possono utilizzare i modelli di messaggi?
Esempio
Ad esempio, il criterio Assegna messaggio consente di utilizzare un modello di messaggio all'interno dell'elemento <Payload>
:
<AssignMessage name="set-dynamic-content"> <AssignTo createNew="false" type="response"></AssignTo> <Set> <Payload contentType="application/json"> {"name":"Alert", "message":"You entered an invalid username: {user.name}"} </Payload> </Set> <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables> </AssignMessage>
Nell'esempio precedente, il valore della variabile di flusso user.name
(in parentesi graffe) verrà valutato e sostituito nella stringa del payload al runtime. Quindi, ad esempio, se user.name=jdoe
,
l'output del messaggio risultante nel payload sarà: You entered an invalid username: jdoe
.
Se non è possibile risolvere la variabile, viene restituita una stringa vuota.
Esempio
Quando si supera una quota, è buona norma restituire un messaggio significativo al chiamante. Questo pattern viene comunemente utilizzato con una "regola di errore" per fornire al chiamante informazioni sulla violazione della quota. Nel seguente criterio Assegna messaggio, i modelli di messaggi vengono utilizzati
per inserire in modo dinamico le informazioni sulle quote in diversi elementi XML:
<AssignMessage name='AM-QuotaViolationMessage'> <Description>message for quota exceeded</Description> <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables> <Set> <Headers> <Header name='X-Quota-Reset'>{ratelimit.Quota-1.expiry.time}</Header> <Header name='X-Quota-Allowed'>{ratelimit.Quota-1.allowed.count}</Header> <Header name='X-Quota-Available'>{ratelimit.Quota-1.available.count}</Header> </Headers> <Payload contentType='application/json'>{ "error" : { "message" : "you have exceeded your quota", "clientId" : "{request.queryparam.apikey}" } } </Payload> <StatusCode>429</StatusCode> <ReasonPhrase>Quota Exceeded</ReasonPhrase> </Set> </AssignMessage>
Nel criterio AttributionMessage, i seguenti elementi dell'elemento <Set>
supportano i modelli dei messaggi:
- Titolo
- QueryParam
- FormParam
- PayLoad
- Versione
- Verbo
- Percorso
- StatusCode
- ReasonPhrase
Anche in questo caso, tieni presente che le variabili di flusso in un modello di messaggio devono essere racchiuse tra parentesi graffe.
Quando questo criterio viene eseguito:
- Gli elementi Header ricevono i valori delle variabili di flusso specificate.
- Il payload include una combinazione di testo letterale e variabili (il valore
client_id
viene compilato dinamicamente). - I valori StatusCode e Reasonphrase includono solo testo letterale; tuttavia, questi elementi supportano anche i modelli dei messaggi, se vuoi utilizzarli.
Esempio
In una definizione di TargetEndpoint del proxy, gli elementi secondari di <SSLInfo>
supportano i modelli dei messaggi. Seguendo lo stesso pattern utilizzato nei criteri, le variabili di flusso nelle parentesi graffe vengono sostituite all'esecuzione del proxy.
<TargetEndpoint name="default"> … <HTTPTargetConnection> <SSLInfo> <Enabled>{myvars.ssl.enabled}</Enabled> <ClientAuthEnabled>{myvars.ssl.client.auth.enabled}</ClientAuthEnabled> <KeyStore>{myvars.ssl.keystore}</KeyStore> <KeyAlias>{myvars.ssl.keyAlias}</KeyAlias> <TrustStore>{myvars.ssl.trustStore}</TrustStore> </SSLInfo> </HTTPTargetConnection> … </TargetEndpoint>
Dove puoi utilizzare i modelli di messaggi?
I modelli di messaggi sono supportati in diversi criteri e in alcuni elementi utilizzati nella configurazione di TargetEndpoint.
Criteri che accettano modelli di messaggi
Norme | Elementi ed elementi secondari che supportano i modelli di messaggi |
---|---|
Criterio di AccessControl | <SourceAddress> , per l'attributo mask e l'indirizzo IP. |
Criterio AttributionMessage | Elementi secondari di <Set> : Payload, ContentType, Verb, Version, Path, StatusCode, Reasonphrase, Headers, QueryParams, FormParams
Elementi secondari di
Elemento secondario |
Norme sui callout per le estensioni |
<Input> |
Norma ExtractVariables | <JsonPath>
|
Generare criterio JWS Verificare criterio JWS |
<Payload> (solo criterio Genera JWS)
* Questi elementi supportano il modello di messaggio solo se type=map. |
Generare criterio JWT Verificare il criterio JWT |
<AdditionalClaims><Claim>
* Questi elementi supportano il modello di messaggio solo se type=map. |
Criteri LDAP | <SearchQuery> |
Criterio MessageLogging | <Syslog><Message>
|
Norme di OASValidation | Elemento
|
Criterio AlzaFault | Elementi <Set> : Payload, ContentType, Verb, Version, Path, StatusCode, ReasonPhrase, Headers, QueryParams, FormParams
Elementi |
Criterio SAMLAssertion | <Template>
* Solo se la firma delle norme è |
Norme sui callout di servizio | Elementi <Set> : Payload, ContentType, Verb, Version, Path, StatusCode, ReasonPhrase, /Headers, QueryParams, FormParams
Elementi
|
Elementi TargetEndpoint che accettano modelli di messaggi
Elementi HTTPTargetConnection | Elementi secondari che supportano i modelli di messaggi |
---|---|
SSLInfo | Abilitato, KeyAlias, KeyStore, TrustStore, ClientAuthEnabled, CLRStore |
LocalTargetConnection | ApiProxy, ProxyEndpoint |
Percorso | N/A |
Sintassi del modello di messaggio
Questa sezione illustra le regole da seguire per utilizzare i modelli di messaggi.
Utilizza le parentesi graffe per indicare le variabili
Racchiudi i nomi delle variabili tra parentesi graffe { }. Se la variabile non esiste, nell'output viene restituita una stringa vuota. Tuttavia, puoi specificare i valori predefiniti nei modelli di messaggio (valori che vengono sostituiti se la variabile non è risolta). Consulta Impostare i valori predefiniti nei modelli di messaggi.
Tieni presente che è consentito racchiudere l'intera stringa del modello di messaggio tra virgolette, ma è facoltativo. Ad esempio, i seguenti due modelli di messaggi sono equivalenti:
<Set> <Headers> <Header name="x-h1">"Hello {user.name}"</Header> <Header name="x-h1">Hello {user.name}</Header> </Headers> </Set>
Impostazione dei valori predefiniti nei modelli di messaggio
Se non è possibile risolvere una variabile basata su modelli, Edge sostituisce una stringa vuota. Tuttavia, puoi specificare un valore predefinito come segue:
<Header name="x-h1">Test message. id = {request.header.id:Unknown}</Header>
Nell'esempio precedente, se la variabile request.header.id
non può essere risolta, il suo valore viene sostituito da Unknown
. Ad esempio:
Test message. id = Unknown
Gli spazi non sono consentiti nelle espressioni di funzione
Gli spazi non sono consentiti in nessuna posizione nelle espressioni delle funzioni del modello di messaggio. Ad esempio:
Consentito:
{substring(alpha,0,4)} {createUuid()} {randomLong(10)}
Non consentiti:
{substring( alpha, 0, 4 )} { createUuid( ) } {randomLong( 10 )}
Sintassi precedente per i payload JSON
Nelle versioni Edge prima della release 16.08.17 di Cloud, non potevi utilizzare le parentesi graffe per indicare i riferimenti alle variabili all'interno dei payload JSON. Nelle versioni precedenti, dovevi utilizzare gli attributi variablePrefix
e variableSuffix
per specificare i caratteri di delimitazione e utilizzarli per aggregare i nomi delle variabili, in questo modo:
<Set> <Payload contentType="application/json" variablePrefix="@" variableSuffix="#"> {"name":"foo", "type":"@variable_name#"} </Payload> </Set>
Sebbene Apigee suggerisca di utilizzare la nuova sintassi delle parentesi graffe, quella precedente funziona ancora.
Utilizzare le funzioni per i modelli di messaggi
Edge fornisce un insieme di funzioni che puoi utilizzare all'interno dei modelli di messaggi per eseguire l'escape, codificare, eseguire l'hashing e formattare le variabili stringa.
Le funzioni per il modello di messaggio sono descritte in dettaglio in Riferimento alla funzione modello di messaggio.
Esempio: toLowerCase()
Utilizza la funzione toLowerCase()
integrata per trasformare una variabile stringa in minuscolo:
<AssignMessage name="AM-Set-Custom-Response"> <AssignTo createNew="false" type="response"/> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> <Set> <Headers> <Header name="x-h1">Test header: {toLowerCase(foo.bar:FOO)}</Header> </Headers> </Set> </AssignMessage>
Se la variabile di flusso foo.bar
si risolve, i suoi caratteri saranno tutti minuscoli.
Se foo.bar
non è risolto, il valore predefinito FOO
viene sostituito e convertito in caratteri minuscoli. Ad esempio:
Test header: foo
Esempio: escapeJSON()
Ecco un caso d'uso interessante: supponiamo che la tua app di backend restituisca una risposta JSON contenente caratteri di escape validi. Ad esempio:
{ "code": "INVALID", "user_message": "Invalid value for \"logonId\" check your input." }
Supponiamo poi di voler restituire questo messaggio al chiamante del client in un payload personalizzato. Il solito modo per farlo è estrarre il messaggio dal payload della risposta di destinazione e utilizzare Assegna messaggio per aggiungerlo a una risposta proxy personalizzata (ovvero, inviarlo al client).
Ecco il criterio Estrai variabili che estrae le informazioni user_message
in una variabile denominata standard.systemMessage
:
<ExtractVariables name="EV-BackendErrorResponse"> <DisplayName>EV-BackendErrorResponse</DisplayName> <JSONPayload> <Variable name="standard.systemMessage"> <JSONPath>$.user_message</JSONPath> </Variable> </JSONPayload> </ExtractVariables>
Ora, ecco un criterio Assegna messaggio perfettamente valido che aggiunge la variabile estratta al payload della risposta (la risposta proxy):
<AssignMessage name="AM-SetStandardFaultResponse"> <DisplayName>AM-SetStandardFaultResponse</DisplayName> <Set> <Payload contentType="application/json"> { "systemMessage": "{standard.systemMessage}" } </Payload> </Set> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> <AssignTo createNew="false" transport="http" type="response"/> </AssignMessage>
Purtroppo si è verificato un problema. Il criterio per l'estrazione delle variabili ha rimosso le virgolette di escape intorno a una parte del messaggio. Ciò significa che la risposta restituita al client è un JSON non valido. È evidente che non è quello che intendevi.
{ "systemMessage": "Invalid value for "logonId" check your input." }
Per risolvere questo problema, puoi modificare il criterio Assegna messaggio in modo che utilizzi una funzione del modello di messaggio che esegue automaticamente l'escape delle virgolette all'interno del file JSON. Questa funzione, escapeJSON()
, esegue l'escape di eventuali virgolette o altri caratteri speciali che si trovano in un'espressione JSON:
<AssignMessage name="AM-SetStandardFaultResponse"> <DisplayName>AM-SetStandardFaultResponse</DisplayName> <Set> <Payload contentType="application/json"> { "systemMessage": "{escapeJSON(standard.systemMessage)}" } </Payload> </Set> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> <AssignTo createNew="false" transport="http" type="response"/> </AssignMessage>
La funzione esegue l'escape delle virgolette incorporate, generando un JSON valido, che è esattamente ciò che volevi:
{ "systemMessage": "Invalid value for \"logonId\" check your input.", }
Un modello di messaggio è una funzionalità di sostituzione delle stringhe dinamica che puoi utilizzare in determinati criteri e nelle definizioni di TargetEndpoint. Le funzioni del modello di messaggio consentono di eseguire utili operazioni come l'hashing, la manipolazione delle stringhe, l'escape dei caratteri e altre all'interno di un modello di messaggio.
Ad esempio, nel seguente criterio AttributionMessage, la funzione toLowerCase()
viene utilizzata in un
modello di messaggio:
<AssignMessage name="AM-Set-Custom-Response"> <AssignTo createNew="false" type="response"/> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> <Set> <Headers> <Header name="x-h1">Test header: {Hello, toLowerCase(user.name)}</Header> </Headers> </Set> </AssignMessage>
Questo argomento descrive le funzioni del modello di messaggio, i relativi argomenti e gli output. Questo argomento presuppone che tu conosca i modelli di messaggi e i contesti in cui vengono utilizzati.
Funzioni hash
Calcola un valore hash e restituisci la rappresentazione stringa di quell'hash.
Funzioni hash esadecimali
Calcola un valore hash e restituisci la rappresentazione stringa di quell'hash sotto forma di numero esadecimale.
Sintassi
Funzione | Descrizione |
---|---|
md5Hex(string)
|
Calcola un hash MD5 espresso come numero esadecimale. |
sha1Hex(string)
|
Calcola un hash SHA1 espresso come numero esadecimale. |
sha256Hex(string)
|
Calcola un hash SHA256 espresso come numero esadecimale. |
sha384Hex(string)
|
Calcola un hash SHA384 espresso come numero esadecimale. |
sha512Hex(string)
|
Calcola un hash SHA512 espresso come numero esadecimale. |
Argomenti
string - Le funzioni hash prendono un singolo argomento stringa su cui viene calcolato l'algoritmo hash. L'argomento può essere una stringa letterale o una variabile di flusso stringa.
Esempi
Chiamata funzione:
sha256Hex('abc')
Risultato:
ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad
Chiamata funzione:
var str = 'abc'; sha256Hex(str)
Risultato:
ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad
Funzioni hash Base64
Calcola un valore hash e restituisci la rappresentazione stringa di quell'hash come valore codificato in Base64.
Sintassi
Funzione | Descrizione |
---|---|
md5Base64(string)
|
Calcola un hash MD5 espresso come valore codificato in Base64. |
sha1Base64(string)
|
Calcola un hash SHA1 espresso come valore codificato in Base64. |
sha256Base64(string)
|
Calcola un hash SHA256 espresso come valore codificato in Base64. |
sha384Base64(string)
|
Calcola un hash SHA384 espresso come valorer codificato in Base64. |
sha512Base64(string)
|
Calcola un hash SHA512 espresso come valore codificato in Base64. |
Argomenti
string - Le funzioni hash prendono un singolo argomento stringa su cui viene calcolato l'algoritmo hash. L'argomento può essere una stringa letterale o una variabile di flusso stringa.
Esempi
Chiamata funzione:
sha256Base64('abc')
Risultato:
ungWv48Bz+pBQUDeXa4iI7ADYaOWF3qctBD/YfIAFa0=
Chiamata funzione:
var str = 'abc'; sha256Base64(str)
Risultato:
ungWv48Bz+pBQUDeXa4iI7ADYaOWF3qctBD/YfIAFa0=
Funzioni di stringa
Eseguire operazioni sulle stringhe all'interno di un modello di messaggio.
Funzioni di codifica Base64
Codifica e decodifica le stringhe utilizzando lo schema di codifica Base64.
Sintassi
Funzione | Descrizione |
---|---|
encodeBase64(string)
|
Codifica una stringa utilizzando la codifica Base64. Ad esempio: encodeBase64(value) , quando value contiene
abc , la funzione restituisce la stringa: YWJj
|
decodeBase64(string)
|
Decodifica una stringa con codifica Base64. Ad esempio: decodeBase64(value) , quando value contiene
aGVsbG8sIHdvcmxk , la funzione restituisce la stringa hello, world .
|
Argomenti
string - La stringa da codificare o decodificare. Può essere una stringa letterale o una variabile di flusso stringa.
Esempio
<AssignMessage name="AM-Set-Custom-Response"> <AssignTo createNew="false" type="response"/> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> <Set> <Headers> <Header name="x-h1">Hello, {decodeBase64('d29ybGQK')}</Header> </Headers> </Set> </AssignMessage>
Funzioni di conversione delle richieste di assistenza
Converti una stringa in lettere tutte maiuscole o tutte minuscole.
Sintassi
Funzione | Descrizione |
---|---|
toUpperCase(string)
|
Convertire una stringa in lettere maiuscole. |
toLowerCase(string)
|
Convertire una stringa in minuscolo. |
Argomenti
string - La stringa da convertire. Può essere una stringa letterale o una variabile di flusso stringa.
Esempio
<AssignMessage name="AM-Set-Custom-Response"> <AssignTo createNew="false" type="response"/> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> <Set> <Headers> <Header name="x-h1">Hello, {toLowerCase(user.name)}</Header> </Headers> </Set> </AssignMessage>
Funzione sottostringa
Restituisce i caratteri compresi tra l'indice iniziale e finale della stringa specificata.
Sintassi
substring(str,start_index,end_index)
Argomenti
- str: una stringa letterale o variabile di flusso stringa.
- start_index - L'indice iniziale nella stringa.
- end_index - (Facoltativo) L'indice finale nella stringa. Se non viene specificato, l'indice finale è la fine della stringa.
Esempi
Per i seguenti esempi, supponiamo che esistano queste variabili di flusso:
Nome variabile | Valore |
---|---|
alpha
|
ABCDEFGHIJKLMNOPQRSTUVWXYZ |
seven
|
7 |
Ecco i risultati delle chiamate di funzione che utilizzano queste variabili:
Espressione del modello di messaggio | Risultato |
---|---|
{substring(alpha,22)}
|
WXYZ
|
hello {substring(alpha,22)}
|
hello WXYZ
|
{substring(alpha,-4)}
|
WXYZ
|
{substring(alpha,-8,-4)}
|
STUV
|
{substring(alpha,0,10)}
|
ABCDEFGHIJ
|
{substring(alpha,0,seven)}
|
ABCDEFG
|
Funzione Sostituisci tutto
Applica un'espressione regolare a una stringa e, per eventuali corrispondenze, sostituisce la corrispondenza con un valore sostitutivo.
Sintassi
replaceAll(string,regex,value)
Argomenti
- string: una stringa letterale o variabile di flusso stringa in cui eseguire sostituzioni.
- regex: un'espressione regolare.
- value - Il valore per sostituire tutte le corrispondenze regex all'interno della stringa.
Esempi
Per i seguenti esempi, supponiamo che esistano queste variabili di flusso:
Nome variabile | Valore |
---|---|
header
|
Bearer ABCDEFGHIJKLMNOPQRSTUVWXYZ-9993
|
regex1
|
"^Bearer "
|
replacement
|
"TOKEN: "
|
Ecco i risultati delle chiamate di funzione che utilizzano queste variabili:
Espressione del modello di messaggio | Risultato |
---|---|
{replaceAll(header,"9993",'')}
|
Bearer ABCDEFGHIJKLMNOPQRSTUVWXYZ-
|
{replaceAll(header,regex1,'')}
|
ABCDEFGHIJKLMNOPQRSTUVWXYZ-9993
|
{replaceAll(header,regex1,replacement)}
|
TOKEN: ABCDEFGHIJKLMNOPQRSTUVWXYZ-9993
|
Sostituisci prima funzione
Sostituisce solo la prima occorrenza della corrispondenza dell'espressione regolare specificata nella stringa.
Sintassi
replaceFirst(string,regex,value)
Argomenti
- string: una stringa letterale o variabile di flusso stringa in cui eseguire sostituzioni.
- regex: un'espressione regolare.
- value - Il valore da sostituire all'espressione regolare all'interno della stringa.
Carattere di escape e funzioni di codifica
Funzioni che eseguono l'escape o codificano i caratteri speciali in una stringa.
Sintassi
Funzione | Descrizione |
---|---|
escapeJSON(string) | Esegue l'escape delle virgolette doppie. |
escapeXML(stringa) | Sostituisce le parentesi angolari, l'apostrofo, le virgolette e la e commerciale con le rispettive entità XML. Da utilizzare per i documenti XML 1.0.
|
escapeXML11(stringa) | Funziona allo stesso modo di escapeXML, ma per le entità XML v1.1. Consulta le note sull'utilizzo riportate di seguito. |
encodeHTML(stringa) | Codifica l'apostrofo, le parentesi angolari e la e commerciale. |
Argomenti
string - La stringa da cui eseguire l'escape. Può essere una stringa letterale o una variabile di flusso stringa.
Note sull'utilizzo
XML 1.1 può rappresentare determinati caratteri di controllo, ma non può rappresentare il byte null o i punti di codice surrogati Unicode non associati, anche dopo l'escape. La funzione escapeXML11() rimuove i caratteri che non rientrano nei seguenti intervalli:
[#x1-#xD7FF] | [#xE000-#xFFFD] | [#x10000-#x10FFFF]
La funzione escapeXML11()
esegue l'escape dei caratteri nei seguenti intervalli:
[#x1-#x8] | [#xB-#xC] | [#xE-#x1F] | [#x7F-#x84] | [#x86-#x9F]
Esempi
Supponiamo che esista una variabile di flusso denominata food con questo valore: "bread" & "butter"
. Quindi, la funzione:
{escapeHTML(food)}
porta a:
"bread" & "butter"
Funzioni di formato dell'ora
Restituisce una rappresentazione stringa dell'ora nel formato UTC o nel fuso orario locale.
Sintassi
Funzione | Descrizione |
---|---|
timeFormat(format,str)
|
Restituisce la data formattata nel fuso orario locale. |
timeFormatMs(format,str)
|
Restituisce la data formattata nel fuso orario locale. |
timeFormatUTC(format,str)
|
Restituisce la data formattata nel fuso orario UTC. |
timeFormatUTCMs(format,str)
|
Restituisce la data formattata nel fuso orario UTC. |
Argomenti
- format - Una stringa di formato di data/ora. Può essere una stringa letterale o una variabile stringa.
- str - Una stringa o variabile di flusso stringa contenente un valore di tempo. Il valore può essere in millisecondi-since-epoch o millisecondi-since-epoch per timeFormatMs.
Esempi
Supponiamo che tu abbia i seguenti valori e che il fuso orario locale sia il Pacifico:
epoch_time_ms = 1494390266000
epoch_time = 1494390266
fmt1 = yyyy-MM-dd
fmt2 = yyyy-MM-dd HH-mm-ss
fmt3 = yyyyMMddHHmmss
Le funzioni restituiscono i seguenti risultati:
- key - (Obbligatorio) Specifica la chiave segreta, codificata come stringa, utilizzata per calcolare l'HMAC.
- valueToSign - (Obbligatorio) Specifica il messaggio da firmare. Deve essere una stringa.
- keyencoding: (facoltativo): la stringa della chiave secret verrà decodificata in base a questa codifica specificata. Valori validi:
hex
,base16
,base64
,utf-8
. Valore predefinito:utf-8
- outputencoding - (Facoltativo) Specifica l'algoritmo di codifica da utilizzare per l'output.
Valori validi:
hex
,base16
,base64
. I valori non fanno distinzione tra maiuscole e minuscole;hex
ebase16
sono sinonimi. Valore predefinito:base64
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
Esempi
In questo esempio viene utilizzato il criterio AssegnaMessage per calcolare un codice HMAC-256 e assegnarlo a una variabile di flusso:
<AssignMessage name='AM-HMAC-1'> <AssignVariable> <Name>valueToSign</Name> <Template>{request.header.apikey}.{request.header.date}</Template> </AssignVariable> <AssignVariable> <Name>hmac_value</Name> <Template>{hmacSha256(private.secretkey,valueToSign)}</Template> </AssignVariable> </AssignMessage>
Questo esempio illustra come generare un HMAC a cascata che possa essere utilizzato con il processo di firma di AWS Signature v4. L'esempio utilizza il criterioAssignMessage per generare i cinque livelli di HMAC a cascata utilizzati per calcolare una firma per AWS Signature v4:
<AssignMessage name='AM-HMAC-AWS-1'> <!-- 1 --> <AssignVariable> <Name>DateValue</Name> <Template>{timeFormatUTCMs('yyyyMMdd',system.timestamp)}</Template> </AssignVariable> <!-- 2 --> <AssignVariable> <Name>FirstKey</Name> <Template>AWS4{private.secret_aws_access_key}</Template> </AssignVariable> <!-- 3 --> <AssignVariable> <Name>DateKey</Name> <Template>{hmacSha256(FirstKey,DateValue,'utf-8','base16')}</Template> </AssignVariable> <!-- 4 --> <AssignVariable> <Name>DateRegionKey</Name> <Template>{hmacSha256(DateKey,aws_region,'base16','base16')}</Template> </AssignVariable> <!-- 5 --> <AssignVariable> <Name>DateRegionServiceKey</Name> <Template>{hmacSha256(DateRegionKey,aws_service,'base16','base16')}</Template> </AssignVariable> <!-- 6 --> <AssignVariable> <Name>SigningKey</Name> <Template>{hmacSha256(DateRegionServiceKey,'aws4_request','base16','base16')}</Template> </AssignVariable> <!-- 7 --> <AssignVariable> <Name>aws4_hmac_value</Name> <Template>{hmacSha256(SigningKey,stringToSign,'base16','base16')}</Template> </AssignVariable> </AssignMessage>
Altre funzioni
Crea funzione UUID
Genera e restituisce un UUID.
Sintassi
createUuid()
Argomenti
Nessuna.
Esempio
{createUuid()}
Risultato di esempio:
ec3ca9be-d1e1-4ef4-aee4-4a58f3130db8
Funzione generatore lungo casuale
Restituisce un numero intero lungo casuale.
Sintassi
randomLong(args)
Argomenti
- Se non vengono specificati argomenti, la funzione restituisce un numero intero lungo casuale, calcolato dalla classe SecureRandom di Java.
- Se è presente un argomento, viene considerato il valore minimo del calcolo.
- Se è presente un secondo argomento, viene considerato il valore massimo del calcolo.
Esempio
{random()}
il risultato sarà simile al seguente:
5211338197474042880
Generatore di testo regex
Genera una stringa di testo che corrisponde a una determinata espressione regolare.
Sintassi
xeger(regex)
Argomento
regex: un'espressione regolare.
Esempio
Questo esempio genera una stringa di sette cifre senza zero:
xeger('[1-9]{7}')
Risultato di esempio:
9857253
Funzione di coalescenza null
La funzione firstnonnull()
restituisce il valore dell'argomento non null all'estrema sinistra.
Sintassi
firstnonnull(var1,varn)
Argomento
var1: una variabile di contesto.
varn: una o più variabili di contesto. Puoi impostare l'argomento più a destra su una stringa per fornire un valore di riserva (un valore che verrà impostato se non viene impostato nessuno degli argomenti a sinistra).
Esempi
La tabella seguente illustra come utilizzare la funzione:
Modello | Var1 | Var2 | Var3 | Risultato |
---|---|---|---|---|
{firstnonnull(var1,var2)}
|
Non impostato | foo
|
N/A | foo
|
{firstnonnull(var1,var2)}
|
foo
|
bar
|
N/A | foo
|
{firstnonnull(var1,var2)}
|
foo
|
Non impostato | N/A | foo
|
{firstnonnull(var1,var2,var3)}
|
foo
|
bar
|
baz
|
foo
|
{firstnonnull(var1,var2,var3)}
|
Non impostato | bar
|
baz
|
bar
|
{firstnonnull(var1,var2,var3)}
|
Non impostato | Non impostato | baz
|
baz
|
{firstnonnull(var1,var2,var3)}
|
Non impostato | Non impostato | Non impostato | null
|
{firstnonnull(var1)}
|
Non impostato | N/A | N/A | null
|
{firstnonnull(var1)}
|
foo
|
N/A | N/A | foo
|
{firstnonnull(var1,var2)}
|
""
|
bar
|
N/A | ""
|
{firstnonnull(var1,var2,'fallback value')}
|
null
|
null
|
fallback value
|
fallback value
|
Funzione XPath
Applica un'espressione XPath a una variabile XML.
Sintassi
xpath(xpath_expression,xml_string,[datatype])
Argomenti
xpath_expression: un'espressione XPath.
xml_string: una variabile di flusso o una stringa contenente XML.
datatype - (Facoltativo) Specifica il tipo restituito desiderato della query. Può essere un set di nodi, un nodo, un numero, un booleano o una stringa. Il valore predefinito è nodeset. L'impostazione predefinita è in genere la scelta giusta.
Esempio 1
Supponiamo che queste variabili di contesto definiscano una stringa XML e un'espressione XPath:
xml = "<tag><tagid>250397</tagid><readerid>1</readerid><rssi>74</rssi><date>2019/06/15</date></tag>" xpath = "/tag/tagid"
Inoltre, la funzione xpath()
viene utilizzata in un criterio AssegnaMessage, come indicato di seguito:
<AssignMessage> <AssignVariable> <Name>extracted_tag</Name> <Template>{xpath(xpath,xml)}</Template> </AssignVariable> </AssignMessage><
La funzione restituisce il valore <tagid>250397</tagid>
. Questo valore viene inserito nella
variabile di contesto denominata extracted_tag
.
Esempio 2
Se vuoi solo il valore del nodo, utilizza la funzione text()
, come segue:
<AssignMessage> <AssignVariable> <Name>extracted_tag</Name> <Template>{xpath('/tag/tagid/text()',xml)}</Template> </AssignVariable> </AssignMessage>
Come risultato di questa operazione, la variabile di contesto extracted_tag
è impostata su
250397
Se sono selezionati più nodi, il risultato di xpath()
sarà costituito da tutti i valori della selezione, concatenati con una virgola.
Esempio 3: spazi dei nomi XML
Per specificare uno spazio dei nomi, aggiungi parametri aggiuntivi, ognuno con una stringa simile a prefix:namespaceuri
. Ad esempio, una funzione xpath()
che seleziona l'elemento figlio di un corpo SOAP potrebbe essere la seguente:
<AssignMessage> <AssignVariable> <Name>soapns</Name> <Value>soap:http://schemas.xmlsoap.org/soap/envelope/</Value> </AssignVariable> <AssignVariable> <Name>xpathexpression</Name> <Value>/soap:Envelope/soap:Body/*</Value> </AssignVariable> <AssignVariable> <Name>extracted_element</Name> <Template>{xpath(xpathexpression,xml,soapns)}</Template> </AssignVariable> </AssignMessage>
Per ulteriori spazi dei nomi, puoi aggiungere fino a 10 parametri aggiuntivi alla funzione xpath()
.
Puoi specificare una semplice espressione XPath come stringa racchiusa tra virgolette singole:
{xpath('/tag/tagid/text()',xml)}
Se l'espressione XPath include prefissi dello spazio dei nomi (e due punti), devi assegnare l'espressione XPath a una variabile e specificare il nome della variabile anziché direttamente l'espressione.
{xpath(xpathexpression,xml,ns1)}
Esempio 4: specifica del tipo restituito desiderato
Il terzo parametro facoltativo passato alla funzione xpath()
specifica il tipo restituito desiderato della query.
Alcune query XPath possono restituire valori numerici o booleani. Ad esempio, la funzione count()
restituisce un numero. Questa è una query XPath valida:
count(//Record/Fields/Pair)
Questa query valida restituisce un valore booleano:
count(//Record/Fields/Pair)>0
In questi casi richiama la funzione xpath()
con un terzo parametro che specifica tale tipo:
{xpath(expression,xml,'number')} {xpath(expression,xml,'boolean')}
Se il terzo parametro contiene i due punti, viene interpretato come argomento dello spazio dei nomi.
In caso contrario, viene considerato il tipo restituito desiderato. In questo caso, se il terzo parametro non è uno dei valori validi (senza distinzione tra maiuscole e minuscole), la funzione xpath()
restituisce per impostazione predefinita un set di nodi.
Funzione percorso JSON
Applica un'espressione Percorso JSON a una variabile JSON.
Sintassi
jsonPath(json-path,json-var,want-array)
Argomenti
- (Obbligatorio)
json-path
: (stringa) un'espressione di percorso JSON. - (Obbligatorio)
json-var
: (stringa) una variabile di flusso o una stringa contenente JSON. - (Facoltativo)
want-array
: (stringa) se questo parametro è impostato su'true'
e se il set di risultati è un array, vengono restituiti tutti gli elementi dell'array. Se impostato su un altro valore o se questo parametro viene omesso, viene restituito solo l'elemento zero di un array del set di risultati. Se il set di risultati non è un array, questo terzo parametro, se presente, viene ignorato.
Esempio 1
Se questo è il modello del messaggio:
The address is {jsonPath($.results[?(@.name == 'Mae West')].address.line1,the_json_variable)}
e the_json_variable
contiene:
{ "results" : [ { "address" : { "line1" : "18250 142ND AV NE", "city" : "Woodinville", "state" : "Washington", "zip" : "98072" }, "name" : "Fred Meyer" }, { "address" : { "line1" : "1060 West Addison Street", "city" : "Chicago", "state" : "Illinois", "zip" : "60613" }, "name" : "Mae West" } ] }
Il risultato della funzione è:
The address is 1060 West Addison Street
Tieni presente che in questo caso, il set di risultati è un singolo elemento (non un array di elementi). Se il set di risultati fosse un array, verrà restituito solo l'elemento zero di quell'array. Per restituire l'array completo, chiama la funzione con 'true'
come terzo parametro, come mostrato nell'esempio successivo.
Esempio 2
Se questo è il modello del messaggio:
{jsonPath($.config.quota[?(@.operation=='ManageOrder')].appname,the_json_variable,'true')}
e the_json_variable
contiene:
{ "results" : [ { "config": { "quota": [ { "appname": "A", "operation": "ManageOrder", "value": "900" }, { "appname": "B", "operation": "ManageOrder", "value": "1000" }, { "appname": "B", "operation": "SubmitOrder", "value": "800" } ] } } ] }
Il risultato della funzione è:
['A','B']