Modelli di messaggio

Stai visualizzando la documentazione di Apigee Edge.
Vai alla documentazione di Apigee X. info

Questo argomento spiega 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 ti consente di eseguire la sostituzione di stringhe variabili in determinati elementi di criteri e TargetEndpoint. Questa funzionalità, se supportata, ti consente di compilare le stringhe in modo dinamico quando viene eseguito un proxy.

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

Vedi anche Dove puoi utilizzare i modelli di messaggio?

Esempio

Ad esempio, il criterio Assegna messaggio ti consente di utilizzare un modello di messaggio all'interno dell'elemento <Payload>:

<AssignMessage name="set-dynamic-content">
  <AssignTo createNew="false" type="response"></AssignTo>
  <Set>
    <Payload contentType="application/json">
      {"name":"Alert", "message":"You entered an invalid username: {user.name}"}
    </Payload>
  </Set>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
</AssignMessage>

Nell'esempio precedente, il valore della variabile di flusso user.name (tra parentesi graffe) verrà valutato e sostituito nella stringa del payload in fase di runtime. 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 visualizzata una stringa vuota.

Esempio

Quando una quota viene superata, è buona norma restituire un messaggio significativo all'utente che chiama. Questo schema viene utilizzato comunemente con una "regola di errore" per fornire un output che fornisca all'utente chiamante informazioni sulla violazione della quota. Nel seguente criterio Assegna messaggio, 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>
    <ReasonPhrase>Quota Exceeded</ReasonPhrase>
  </Set>
</AssignMessage>

Nel criterio AssignMessage, i seguenti elementi dell'elemento <Set> supportano la creazione di modelli di messaggi:

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

Tieni presente che le variabili di flusso in un modello di messaggio devono essere racchiuse tra parentesi graffe.

Quando viene eseguito questo criterio:

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

Esempio

In una definizione di TargetEndpoint proxy, gli elementi secondari di <SSLInfo> supportano la creazione di modelli di messaggi. Seguendo lo stesso schema utilizzato nei criteri, 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 messaggi sono supportati in diversi criteri, nonché in alcuni elementi utilizzati nella configurazione di TargetEndpoint.

Norme che accettano modelli di messaggi

Elementi TargetEndpoint che accettano modelli di messaggio

Sintassi del modello di messaggio

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

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 che vengono sostituiti se la variabile non è risolta). Consulta Impostare i valori predefiniti nei modelli di messaggio.

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

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

Impostazione dei valori predefiniti nei modelli di messaggio

Se non è possibile risolvere una variabile basata su modello, Edge sostituisce una stringa vuota. Tuttavia, puoi specificare un valore predefinito come segue:

<Header name="x-h1">Test message. id = {request.header.id:Unknown}</Header>

Nell'esempio precedente, se la variabile request.header.id non può essere risolta, il relativo 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 nelle espressioni delle funzioni del modello di messaggio. Ad esempio:

Consentito:

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

Non consentito:

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

Sintassi precedente per i payload JSON

Nelle versioni di Edge precedenti alla release Cloud del 16/08/17, non era possibile utilizzare le parentesi graffe per indicare i riferimenti alle variabili all'interno dei payload JSON. In queste versioni precedenti, dovevi utilizzare gli attributi variablePrefix e variableSuffix per specificare i caratteri di delimitazione e utilizzarli per inserire i nomi delle variabili, come segue:

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

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

Utilizzo delle funzioni dei modelli di messaggio

Edge fornisce un insieme di funzioni che puoi utilizzare all'interno dei modelli di messaggio per eseguire escape, codifica, hashing e formattazione delle variabili stringa.

Le funzioni dei modelli di messaggio sono descritte in dettaglio in Riferimento per le funzioni dei modelli di messaggio.

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 in minuscolo. Se foo.bar non è risolto, il valore predefinito FOO viene sostituito e converitto 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 all'utente chiamante del client in un payload personalizzato. Il modo usuale per farlo è estrarre il messaggio dal payload della risposta di destinazione e utilizzare Assegna messaggio per aggiungerlo a una risposta proxy personalizzata (ovvero per rispedirlo al client).

Ecco il criterio Estrazione variabili che estrae le informazioni su user_message in una variabile denominata standard.systemMessage:

<ExtractVariables name="EV-BackendErrorResponse">
    <DisplayName>EV-BackendErrorResponse</DisplayName>
    <JSONPayload>
        <Variable name="standard.systemMessage">
            <JSONPath>$.user_message</JSONPath>
        </Variable>
    </JSONPayload>
</ExtractVariables>

Ecco un criterio Assegna messaggio perfettamente valido che aggiunge la variabile estratta al payload della risposta (la risposta del proxy):

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

Purtroppo, si è verificato un problema. Il criterio Estrazione variabili ha rimosso i caratteri di citazione con escape intorno a una parte del messaggio. Ciò significa che la risposta restituita al client è JSON non valido. Chiaramente non è quello che volevi.

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

Per risolvere il problema, puoi modificare il criterio Assegna messaggio in modo da utilizzare una funzione di modello di messaggio che inserisca i caratteri di escape nelle virgolette all'interno del JSON. Questa funzione, escapeJSON(), esegue la fuga 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 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 di stringhe dinamiche che puoi utilizzare in determinati criteri e nelle definizioni di TargetEndpoint. Le funzioni dei modelli di messaggio ti consentono di eseguire operazioni utili come hashing, manipolazione di stringhe, escape di caratteri e altre all'interno di un modello di messaggio.

Ad esempio, nel seguente criterio AssignMessage, 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 dei modelli di messaggio, i relativi argomenti e gli output. Questo argomento presuppone che tu abbia familiarità con i modelli di messaggio e i contesti in cui vengono utilizzati.

Funzioni hash

Calcola un valore hash e restituisce la rappresentazione stringa dell'hash.

Funzioni hash esadecimali

Calcola un valore hash e restituisce la rappresentazione di stringa dell'hash come numero esadecimale.

Sintassi

Argomenti

stringa: le funzioni hash accettano un singolo argomento stringa su cui viene calcolato l'algoritmo hash. L'argomento può essere una stringa letterale o una variabile di flusso di stringhe.

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 dell'hash come valore codificato in Base64.

Sintassi

Argomenti

stringa: le funzioni hash accettano un singolo argomento stringa su cui viene calcolato l'algoritmo hash. L'argomento può essere una stringa letterale o una variabile di flusso di stringhe.

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.

Funzioni di codifica Base64

Codifica e decodifica le stringhe utilizzando lo schema di codifica Base64.

Sintassi

Argomenti

string: la stringa da codificare o decodificare. Può essere una stringa letterale o una variabile di flusso di stringhe.

Esempio

<AssignMessage name="AM-Set-Custom-Response">
    <AssignTo createNew="false" type="response"/>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <Set>
       <Headers>
         <Header name="x-h1">Hello, {decodeBase64('d29ybGQK')}</Header>
       </Headers>
    </Set>
</AssignMessage>

Funzioni di conversione delle maiuscole/minuscole

Converte una stringa in lettere tutte maiuscole o tutte minuscole.

Sintassi

Argomenti

string: la stringa da convertire. Può essere una stringa letterale o una variabile di flusso di stringhe.

Esempio

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

Funzione 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 o una variabile di flusso di stringhe.
• start_index: l'indice iniziale della stringa.
• end_index: (facoltativo) l'indice di fine nella stringa. Se non specificato, l'indice finale è la fine della stringa.

Esempi

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

Ecco i risultati delle chiamate di funzioni che utilizzano queste variabili:

Funzione Sostituisci tutto

Applica un'espressione regolare a una stringa e, per eventuali corrispondenze, sostituisce la corrispondenza con un valore di sostituzione.

Sintassi

replaceAll(string,regex,value)

Argomenti

• string: una stringa letterale o una variabile di flusso di stringhe in cui apportare le sostituzioni.
• regex: un'espressione regolare.
• value: il valore da sostituire a tutte le corrispondenze di regex all'interno della stringa.

Esempi

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

Ecco i risultati delle chiamate di funzioni che utilizzano queste variabili:

Funzione Sostituisci primo

Sostituisce solo la prima occorrenza della corrispondenza dell'espressione regolare specificata nella stringa.

Sintassi

replaceFirst(string,regex,value)

Argomenti

• string: una stringa letterale o una variabile di flusso di stringhe in cui apportare le sostituzioni.
• regex: un'espressione regolare.
• value: il valore da sostituire alle corrispondenze regex all'interno della stringa.

Funzioni di escape e codifica dei caratteri

Funzioni che eseguono il codice di escape o codificano i caratteri speciali in una stringa.

Sintassi

Argomenti

string: la stringa da eseguire con escape. Può essere una stringa letterale o una variabile di flusso di stringhe.

Note sull'utilizzo

XML 1.1 può rappresentare determinati caratteri di controllo, ma non può rappresentare il byte nullo o i punti di codice Unicode senza accoppiamento, 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'interpretazione letterale dei caratteri nei seguenti intervalli:

[#x1-#x8] | [#xB-#xC] | [#xE-#x1F] | [#x7F-#x84] | [#x86-#x9F]

Esempi

Supponiamo che esista una variabile di flusso denominata cibo con questo valore: "bread" & "butter". Poi, la funzione:

{escapeHTML(food)}

genera:

Funzioni per il formato dell'ora

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

Sintassi

Argomenti

• format: una stringa di formato data/ora. Può essere una stringa letterale o una variabile stringa.
• str: una variabile di flusso di stringhe o stringa contenente un valore di tempo. Il valore può essere espresso in secondi dall'epoca o in millisecondi dall'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 offrono un'alternativa all'utilizzo del criterio HMAC per calcolare un HMAC. Le funzioni sono utili per eseguire un calcolo HMAC a cascata, ad esempio quando l'output di un HMAC viene utilizzato come chiave per un secondo HMAC.

Sintassi

Funzione	Descrizione
hmacSha224(key,valueToSign[,keyencoding[,outputencoding]])	Calcola un HMAC con la funzione hash SHA-224.
hmacSha256(key,valueToSign[,keyencoding[,outputencoding]])	Codifica un HMAC con la funzione hash SHA-256.
hmacSha384(key,valueToSign[,keyencoding[,outputencoding]])	Codifica un HMAC con la funzione hash SHA-384.
hmacSha512(key,valueToSign[,keyencoding[,outputencoding]])	Codifica un HMAC con la funzione hash SHA-512.
hmacMd5(key,valueToSign[,keyencoding[,outputencoding]])	Codifica un HMAC con la funzione hash MD5.
hmacSha1(key, valueToSign [,keyencoding[,outputencoding]])	Codifica un HMAC con l'algoritmo di crittografia SHA-1.

Argomenti

• key - (obbligatorio) Specifica la chiave segreta, codificata come stringa, utilizzata per calcolare l'HMAC.
• valueToSign: (obbligatorio) specifica il messaggio da firmare. Deve essere una stringa.
• keyencoding: (facoltativo) la stringa della chiave segreta verrà decodificata in base a questa codifica specificata. Valori validi: hex, base16, base64, utf-8. Valore predefinito: utf-8
• outputencoding: (facoltativo) specifica l'algoritmo di codifica da utilizzare per l'output. Valori validi: hex, base16, base64. I valori non fanno distinzione tra maiuscole e minuscole; hex e base16 sono sinonimi. Valore predefinito: base64

Esempi

Questo esempio utilizza il criterio Assegna messaggio 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 la procedura 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 la versione 4 della firma AWS:

<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

Creare una funzione UUID

Genera e restituisce un UUID.

Sintassi

createUuid()

Argomenti

Nessuno.

Esempio

{createUuid()}

Risultato di esempio:

ec3ca9be-d1e1-4ef4-aee4-4a58f3130db8

Funzione Generatore di numeri lunghi casuali

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

{random()}

genera un risultato 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 con valori null

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

Sintassi

firstnonnull(var1,varn)

Argomento

var1: una variabile di contesto.

var_n: una o più variabili di contesto. Puoi impostare l'argomento più a destra su una stringa per fornire un valore alternativo (un valore che verrà impostato se non è impostato nessuno degli argomenti a sinistra).

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 o una stringa del flusso contenente XML.

datatype: (Facoltativo) specifica il tipo di ritorno della query desiderato. Può essere nodeset, node, number, boolean, string. Il valore predefinito è nodeset. In genere, l'impostazione predefinita è la scelta giusta.

Esempio 1

Supponiamo che queste variabili di contesto definiscano una stringa XML e un'espressione XPath:

xml = "<tag><tagid>250397</tagid><readerid>1</readerid><rssi>74</rssi><date>2019/06/15</date></tag>"
xpath = "/tag/tagid"

La funzione xpath() viene utilizzata in un criterio 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 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>

A seguito di questa operazione, la variabile di contesto extracted_tag viene impostata su 250397

Se sono selezionati più nodi, il risultato di xpath() è 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, ciascuno una stringa simile a prefix:namespaceuri. Ad esempio, una funzione xpath() che seleziona l'elemento secondario di un corpo SOAP potrebbe essere simile alla 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 un'espressione XPath semplice 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é l'espressione direttamente.

{xpath(xpathexpression,xml,ns1)}

Esempio 4: specifica il tipo di reso desiderato

Il terzo parametro facoltativo passato alla funzione xpath() specifica il tipo di valore restituito 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 due punti, viene interpretato come argomento dello spazio dei nomi. In caso contrario, viene trattato come il tipo di ritorno desiderato. In questo caso, se il terzo parametro non è uno dei valori validi (ignorando le maiuscole), la funzione xpath() restituisce per impostazione predefinita un insieme di nodi.

Funzione Percorso JSON

Applica un'espressione JSON Path 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 o una stringa del flusso contenente JSON.
• (Facoltativo) want-array: (stringa) se questo parametro è impostato su want-array e se il set di risultati è un array, vengono restituiti tutti gli elementi dell'array.'true' Se impostato su un altro valore o se questo parammetro 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 si tratta del modello di messaggio:

The address is {jsonPath($.results[?(@.name == 'Mae West')].address.line1,the_json_variable)}

e the_json_variable contiene:

{
  "results" : [
    {
      "address" : {
        "line1" : "18250 142ND AV NE",
        "city" : "Woodinville",
        "state" : "Washington",
        "zip" : "98072"
      },
      "name" : "Fred Meyer"
    },
    {
      "address" : {
        "line1" : "1060 West Addison Street",
        "city" : "Chicago",
        "state" : "Illinois",
        "zip" : "60613"
      },
      "name" : "Mae West"
    }
  ]
} 

Il risultato della funzione è:

The address is 1060 West Addison Street

Tieni presente che in questo caso il set di risultati è un singolo elemento (non un array di elementi). Se il set di risultati fosse un array, verrà restituito solo l'elemento zero dell'array. Per restituire l'array completo, chiama la funzione con 'true' come terzo parametro, come mostrato nell'esempio successivo.

Esempio 2

Se si tratta del 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']