Modelli di messaggio

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

Questo argomento descrive 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 la sostituzione di stringhe variabili in determinati elementi di criteri e <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 del flusso devono essere racchiusi tra parentesi graffe, mentre il testo non racchiuso tra parentesi graffe viene restituito come testo letterale.

Vedi anche Dove puoi utilizzare i modelli di messaggio?

Esempio

Ad esempio, la policy AssignMessage ti consente di utilizzare un modello di messaggio all'interno dell'elemento <Payload>:

<AssignMessage name="AM-set-payload-with-dynamic-content">
  <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 la variabile non può essere risolta, viene restituita una stringa vuota.

Esempio

Quando una quota viene superata, è buona norma restituire un messaggio significativo al chiamante. Questo pattern viene comunemente utilizzato con una "regola di errore" per fornire un output che fornisca al chiamante informazioni sulla violazione della quota. Nella seguente policy AssignMessage, i modelli di messaggio vengono utilizzati per compilare dinamicamente 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>

Nella policy AssignMessage, i seguenti elementi dell'elemento <Set> supportano i modelli di 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 viene eseguita questa norma:

• Gli elementi <Header> ricevono i valori delle variabili di flusso specificate.
• Il payload include un mix di testo letterale e variabili (client_id viene compilato in modo dinamico).
• <StatusCode> include solo testo letterale, ma questo elemento supporta anche i modelli di messaggi se vuoi utilizzarli.

Esempio

In una definizione di proxy <TargetEndpoint>, gli elementi secondari di <SSLInfo> supportano i modelli di messaggi. Seguendo lo stesso pattern utilizzato nelle norme, le variabili di flusso tra parentesi graffe vengono sostituite quando viene eseguito il 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 messaggio sono supportati in diverse policy, nonché in determinati elementi utilizzati nella configurazione TargetEndpoint.

Nota:puoi anche consultare la documentazione delle norme per scoprire quali norme e quali elementi <TargetEndpoint> supportano i modelli di messaggio.

Policy che accettano i modelli di messaggi

La tabella seguente elenca le norme e gli elementi/elementi secondari supportati:

Norme	Elementi/Elementi secondari
Norme AccessControl	<SourceAddress>, per l'attributo mask e l'indirizzo IP.
Norme AssignMessage	<Set> elementi secondari: Payload, ContentType, Verb, Version, Path, StatusCode, Headers, QueryParams, FormParams Elementi secondari <Add>: intestazioni, parametri di query, parametri del modulo Elemento secondario <AssignVariable>: <Template>
Criterio CORS	<AllowHeaders> <AllowMethods> <AllowOrigins> <ExposeHeaders>
Norme ExtractVariables	<JsonPath> Nota:il modello di messaggio non è accettato per <XMLPath>.
Norme GenerateJWS Norme VerifyJWS	<Payload> (solo norma GenerateJWS) <AdditionalHeaders><Claim> * Questi elementi supportano il modello di messaggio solo quando type=map.
Norme GenerateJWT Norme VerifyJWT	<AdditionalClaims><Claim> <AdditionalHeaders><Claim> * Questi elementi supportano il modello di messaggio solo quando type=map.
Norme HTTPModifier	Elementi secondari di <Set>: <ContentType> <Verb> <Version> <Path> <StatusCode> <Headers> <QueryParams> <FormParams> Elementi secondari di <Add>: <Headers> <QueryParams> <FormParams>
Norme MessageLogging	<CloudLogging><Message> <Syslog><Message> <File><Message>
Norme OASValidation	Elemento <OASResource>
Norme RaiseFault	<Set> elementi: <ContentType> <FormParams> <Headers> <QueryParams> <StatusCode> <Path> <Payload> <Verb> <Version> <Add> elementi: <FormParams> <Headers> <QueryParams>
Norme SAMLAssertion	<Template> * Solo quando la firma del criterio è <GenerateSAMLAssertion>
Norme ServiceCallout	<Set> elementi: <ContentType> <FormParams> <Headers> <QueryParams> <StatusCode> <Path> <Payload> <Verb> <Version> <Add> elementi: <FormParams> <Headers> <QueryParams> <HTTPTargetConnection>/<URL>: consulta la sezione Modelli di URL.

<TargetEndpoint> elementi che accettano i modelli di messaggio

<HTTPTargetConnection> elementi	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 informazioni sull'utilizzo, consulta la sezione Modelli di URL.

Sintassi del modello del messaggio

Questa sezione spiega 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 valori predefiniti nei modelli di messaggio (valori sostituiti se la variabile non viene risolta). Consulta Impostazione dei valori predefiniti nei modelli di messaggi.

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

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

Gli spazi non sono consentiti nelle espressioni di funzione

Gli spazi non sono consentiti in nessuna parte delle espressioni delle funzioni dei modelli di messaggi. Ad esempio:

Consentito:

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

Non consentito:

{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 puoi utilizzare:

{substring({timeFormat('yyyy-MM-dd','1494390266')},0,4)}

Racchiudere i valori letterali stringa nelle funzioni del modello tra virgolette singole

Quando fornisci stringhe letterali nelle funzioni, racchiudile tra virgolette singole anziché 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 e poi utilizza la variabile nel modello.

Impostazione dei valori predefiniti nei modelli di messaggio

Se una variabile basata su un modello non può essere risolta, Apigee sostituisce una stringa vuota. Tuttavia, puoi specificare un valore predefinito nel seguente modo:

<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 relativo valore 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 le 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 precedenti alla release 16.08.17 di Cloud, non era possibile 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 delimitatori e utilizzarli per racchiudere i nomi delle variabili, come segue:

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

Anche se Apigee consiglia di utilizzare la sintassi più recente con le parentesi graffe, la sintassi precedente funziona ancora.

Utilizzo delle funzioni dei modelli di messaggio

Apigee fornisce un insieme di funzioni che puoi utilizzare all'interno dei modelli di messaggio per eseguire l'escape, la codifica, l'hashing e la formattazione delle variabili stringa, come descritto di seguito.

Esempio: toLowerCase()

Utilizza la funzione integrata toLowerCase() 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 viene risolta, i relativi caratteri saranno tutti minuscoli. Se foo.bar non viene risolto, viene sostituito il valore predefinito FOO 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 che contenga 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 client in un payload personalizzato. Il modo solito per farlo è estrarre il messaggio dal payload della risposta di destinazione e utilizzare AssignMessage per aggiungerlo a una risposta proxy personalizzata (ovvero inviarlo di nuovo al client).

Ecco la norma 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>

Ecco ora una norma AssignMessage perfettamente valida che aggiunge la variabile estratta al payload della risposta (la risposta del proxy):

<AssignMessage name="AM-SetStandardFaultResponse">
  <DisplayName>AM-SetStandardFaultResponse</DisplayName>
  <Set>
    <Payload contentType="application/json">
     {
       "systemMessage": "{standard.systemMessage}"
     }
    </Payload>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <AssignTo>response</AssignTo>
</AssignMessage>

Purtroppo, si è verificato un problema. Il criterio ExtractVariables ha rimosso i caratteri di virgolette di escape intorno a una parte del messaggio. Ciò significa che la risposta restituita al client è JSON non valido. È palesemente falso.

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

Per risolvere questo problema, puoi modificare il criterio AssignMessage in modo che utilizzi una funzione di modello di messaggio che esegue l'escape delle virgolette all'interno del JSON. Questa funzione, escapeJSON(), esegue l'escape di eventuali virgolette o altri caratteri speciali che si verificano 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>response</AssignTo>
</AssignMessage>

La funzione esegue l'escape delle virgolette incorporate, generando un JSON valido, esattamente ciò 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 determinate norme e nelle definizioni di <TargetEndpoint>. Le funzioni dei modelli di messaggio consentono di eseguire operazioni utili come hashing, manipolazione di stringhe, escape di caratteri e altre all'interno di un modello di messaggio.

Ad esempio, nella seguente policy AssignMessage, la funzione toLowerCase() viene utilizzata in un modello di messaggio:

<AssignMessage name="AM-Set-Custom-Response">
  <AssignTo>response</AssignTo>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <Set>
   <Headers>
     <Header name="x-h1">Test header: Hello, {toLowerCase(user.name)}</Header>
   </Headers>
  </Set>
</AssignMessage>

Questa sezione descrive le funzioni dei modelli di messaggio, i relativi argomenti e gli 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 restituisce la rappresentazione stringa di questo hash.

Nota: gli spazi non sono consentiti in nessun punto delle espressioni delle funzioni. Consulta Gli spazi non sono consentiti nelle espressioni di funzione.

Funzioni hash esadecimali

Calcola un valore hash e restituisce la rappresentazione stringa di questo 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 accettano 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 di funzione:

sha256Hex('abc')

Risultato:

ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad

Chiamata di funzione:

var str = 'abc';
sha256Hex(str)

Risultato:

ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad

Funzioni hash Base64

Calcola un valore hash e restituisce la rappresentazione stringa di questo hash come valore codificato in Base64.

Sintassi

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

Argomenti

string: Le funzioni hash accettano 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 di funzione:

sha256Base64('abc')

Risultato:

ungWv48Bz+pBQUDeXa4iI7ADYaOWF3qctBD/YfIAFa0=

Chiamata di funzione:

var str = 'abc';
sha256Base64(str)

Risultato:

ungWv48Bz+pBQUDeXa4iI7ADYaOWF3qctBD/YfIAFa0=

Funzioni di stringa

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

Nota: gli spazi non sono consentiti in nessun punto delle espressioni delle funzioni. Consulta Gli spazi non sono consentiti nelle espressioni di funzione.

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

Nota: la codifica Base64 è diversa da Base64URL. Il tentativo di decodificare una stringa con codifica Base64URL produce una stringa vuota.

Funzioni di conversione delle maiuscole/minuscole

Converti una stringa in lettere tutte maiuscole o tutte minuscole.

Sintassi

Funzione	Descrizione
toUpperCase(string)	Converte una stringa in maiuscolo.
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 Substring

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 (racchiusa tra virgolette singole) o una variabile di flusso di stringhe.
• start_index: l'indice iniziale della stringa.
• end_index: (facoltativo) l'indice finale della stringa. Se non viene fornito, l'indice finale è la fine della stringa.

Esempi

Per gli esempi che seguono, supponiamo che esistano queste variabili di flusso:

Nome variabile	Valore
alpha	ABCDEFGHIJKLMNOPQRSTUVWXYZ
seven	7

Ecco i risultati delle chiamate di funzioni 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 ogni corrispondenza, la sostituisce con un valore di sostituzione.

Sintassi

replaceAll(string,regex,value)

Argomenti

• string: una stringa letterale (racchiusa tra virgolette singole) o una variabile di flusso di stringhe in cui effettuare le sostituzioni.
• regex: un'espressione regolare.
• value: il valore da sostituire a tutte le corrispondenze dell'espressione regolare all'interno della stringa.

Esempi

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

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

Ecco i risultati delle chiamate di funzioni 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 la 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 stringhe in cui effettuare le sostituzioni.
• regex: un'espressione regolare.
• value: il valore con cui sostituire le corrispondenze delle espressioni regolari all'interno della stringa.

Funzioni di codifica e escape dei caratteri

Funzioni che eseguono l'escape o la codifica di caratteri speciali in una stringa.

Nota: gli spazi non sono consentiti in nessun punto delle espressioni delle funzioni. Consulta Gli spazi non sono consentiti nelle espressioni di funzione.

Sintassi

Funzione	Descrizione
escapeJSON(string)	Esegue l'escape delle virgolette doppie con la barra rovesciata.
escapeXML(string)	Sostituisce le parentesi angolari, l'apostrofo, le virgolette doppie e le e commerciale con le rispettive entità XML. Utilizza per i documenti XML 1.0. Utilizza escapeXML per i documenti XML1.0 e escapeXML11 per i documenti XML 1.1.
escapeXML11(string)	Funziona allo stesso modo di escapeXML, ma per le entità XML v1.1. Vedi le note sull'utilizzo riportate di seguito.
encodeHTML(string)	Codifica l'apostrofo, le parentesi angolari e la e commerciale.

Argomenti

string: la stringa da 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 accoppiati, 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 della stringa dell'ora, formattata in formato UTC.

Note:

Gli spazi non sono consentiti in nessun punto delle espressioni delle funzioni. Vedi Gli spazi non sono consentiti nelle espressioni di funzione.

I due punti all'interno dei valori letterali della stringa di formato dell'ora (ad esempio "HH:mm:ss") interferiscono quando si impostano i valori predefiniti nei modelli di messaggio. Utilizza le variabili anziché i valori letterali per specificare i formati stringa che includono i due punti. Consulta Evitare l'utilizzo di caratteri speciali nei valori letterali stringa.

Sintassi

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

Argomenti

• format: una stringa di formato data/ora. Può essere una stringa letterale (racchiusa tra virgolette singole) o una variabile stringa. Utilizza una variabile anziché un valore letterale quando il formato include i due punti. Consulta la nota precedente in questa sezione.
• str: una variabile di stringa o flusso di stringhe contenente un valore di tempo. Il valore può essere in secondi trascorsi da epoca o millisecondi trascorsi da epoca per timeFormatMs.

Esempi

Supponiamo i seguenti valori 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 forniscono un'alternativa all'utilizzo del criterio HMAC per calcolare un HMAC. Le funzioni sono utili quando si esegue un calcolo HMAC in cascata, ad esempio quando l'output di un HMAC viene utilizzato come chiave per un secondo HMAC.

Nota: gli spazi non sono consentiti in nessun punto delle espressioni delle funzioni. Consulta Gli spazi non sono consentiti nelle espressioni di funzione.

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.

Nota sulla sicurezza: SHA-1 e MD-5 sono inclusi qui per completezza, ma Google consiglia agli utenti di non utilizzare questi hash. Google ha dimostrato per la prima volta attacchi di collisione contro SHA-1 nel 2017, e ne sconsiglia l'utilizzo. Anche il NIST consiglia di interrompere l'utilizzo di SHA-1. Il CMU Software Engineering Institute ha consigliato per la prima volta di evitare di utilizzare l'algoritmo MD5 in qualsiasi capacità nel 2008.

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 e base16 sono sinonimi. Valore predefinito: base64

Esempi

Questo esempio utilizza la policy AssignMessage 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 mostra come generare un HMAC a cascata che può essere utilizzato con il processo di firma AWS Signature v4. L'esempio utilizza il criterio AssignMessage per generare i cinque livelli di HMAC in cascata utilizzati per calcolare una firma per AWS Signature versione 4:

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

Nota: gli spazi non sono consentiti in nessun punto delle espressioni delle funzioni. Consulta Gli spazi non sono consentiti nelle espressioni di funzione.

Sintassi

createUuid()

Argomenti

Nessuno.

Esempio

{createUuid()}

Risultato di esempio:

ec3ca9be-d1e1-4ef4-aee4-4a58f3130db8

Funzione Generatore di numeri casuali lunghi

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 come il valore minimo del calcolo.
• Se è presente un secondo argomento, viene considerato come il valore massimo del calcolo.

Esempio

{randomLong()}

I risultati sono simili a questi:

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 più a sinistra non nullo.

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 nessuno degli argomenti a sinistra è impostato).

Esempi

La seguente tabella illustra come utilizzare la funzione:

Modello	Var1	Var2	Var3	Risultato
{firstnonnull(var1,var2)}	Non impostato	foo	N/D	foo
{firstnonnull(var1,var2)}	foo	bar	N/D	foo
{firstnonnull(var1,var2)}	foo	Non impostato	N/D	foo
{firstnonnull(var1,var2,var3)}	foo	bar	baz	foo
{firstnonnull(var1,var2,var3)}	Non impostato	bar	baz	bar
{firstnonnull(var1,var2,var3)}	Non impostato	Non impostato	baz	baz
{firstnonnull(var1,var2,var3)}	Non impostato	Non impostato	Non impostato	null
{firstnonnull(var1)}	Non impostato	N/D	N/D	null
{firstnonnull(var1)}	foo	N/D	N/D	foo
{firstnonnull(var1,var2)}	""	bar	N/D	""
{firstnonnull(var1,var2,'fallback value')}	null	null	fallback value	fallback value

Funzione XPath

Applica un'espressione XPath a una variabile XML.

Sintassi

xpath(xpath_expression,xml_string[,datatype])

Argomenti

xpath_expression: un'espressione XPath.

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

datatype: (facoltativo) specifica il tipo di ritorno desiderato della query. I valori validi sono nodeset, node, number, boolean o string. Il valore predefinito è nodeset. L'impostazione predefinita è in genere la scelta giusta.

La funzione restituisce una stringa vuota se l'espressione non corrisponde.

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"

La funzione xpath() viene utilizzata in una norma AssignMessage, 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 parametri aggiuntivi, 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 simile a questa:

<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 gli spazi dei nomi aggiuntivi, puoi aggiungere fino a 10 parametri alla funzione xpath().

Anziché specificare espressioni XPath con caratteri speciali come stringa letterale, utilizza una variabile per includere la stringa nella funzione. Per maggiori dettagli, consulta Evitare di utilizzare caratteri speciali nei valori letterali stringa.

{xpath(xpathexpression,xml,ns1)}

Esempio 3: specificare un tipo di reso desiderato

Il terzo parametro facoltativo passato alla funzione xpath() specifica il tipo di ritorno 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 il 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 di ritorno 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 insieme di nodi.

Funzione percorso JSON

Valuta un'espressione JSONPath rispetto a una variabile JSON.

Sintassi

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

Argomenti

• (Obbligatorio) json-path: (stringa) un'espressione JSONPath.
• (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 il primo elemento di un array di risultati. Se il set di risultati non è un array, questo terzo parametro, se presente, viene ignorato.

Puoi utilizzare le variabili per qualsiasi argomento. Se utilizzi stringhe fisse, racchiudile tra virgolette singole.

La funzione restituisce una stringa vuota se l'espressione non corrisponde.

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

Il valore restituito per questa query jsonPath sarà un array contenente un singolo elemento. La funzione jsonPath in Apigee per impostazione predefinita presuppone che tu voglia un singolo valore, da utilizzare nell'interpolazione delle stringhe. Pertanto, Apigee restituisce solo il primo elemento dell'array. Per richiedere 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:

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

In questo caso, il terzo parametro della funzione è impostato su true, pertanto la funzione jsonPath restituisce l'intero array, nella sintassi dell'array JSON, anziché l'elemento zero.

Esempio 3

Se the_json_variable contiene:

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

e the_query contiene:

$.config.quota[?(@.operation=="ManageOrder")].appname

Il risultato del modello di messaggio: {jsonPath(the_query,the_json_variable,true)} è ["A","B"]

L'utilizzo di una variabile per la query consente di creare una query in fase di runtime, utilizzando dati dinamici. Puoi farlo con l'elemento <AssignVariable> all'interno del criterio AssignMessage.

Ad esempio, supponendo che la variabile operationname contenga il valore ManageOrder, il seguente criterio imposterà the_query sulla query mostrata sopra.

<AssignMessage>
    <AssignVariable>
      <Name>the_query</Name>
      <Template>$.config.quota[?(@.operation=="{operationname}")].appname</Template>
    </AssignVariable>
  </AssignMessage>