<ph type="x-smartling-placeholder"></ph>
Sie sehen die Dokumentation zu Apigee Edge.
Gehen Sie zur
Apigee X-Dokumentation. Weitere Informationen
In diesem Thema wird die Verwendung von Nachrichtenvorlagen in API-Proxys erläutert und eine Funktionsreferenz bereitgestellt.
Was ist eine Nachrichtenvorlage?
Mit einer Nachrichtenvorlage können Sie in bestimmten Richtlinien und TargetEndpoint-Elementen die Variablenstringersetzung durchführen. Mit diesem Feature können Sie Strings dynamisch ausfüllen, wenn ein Proxy ausgeführt wird.
Sie können eine beliebige Kombination aus Ablaufvariablenreferenzen und Literaltext in eine Nachrichtenvorlage einfügen. Namen von Ablaufvariablen müssen in geschweiften Klammern angegeben werden, wobei jeder Text in geschweiften Klammern als Literaltext ausgegeben wird.
Siehe auch Wo können Sie Nachrichtenvorlagen verwenden?
Beispiel
Mit der AssignMessage-Richtlinie können Sie beispielsweise eine Nachrichtenvorlage innerhalb des <Payload>
-Elements verwenden:
<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>
Im obigen Beispiel lautet der Wert der Flussvariablen user.name
(in geschweiften Klammern)
ausgewertet und zur Laufzeit in den Nutzlaststring ersetzt. Wenn z. B. user.name=jdoe
,
lautet die resultierende Nachrichtenausgabe in der Nutzlast: You entered an invalid username: jdoe
.
Wenn die Variable nicht aufgelöst werden kann, wird ein leerer String ausgegeben.
Beispiel
Wird ein Kontingent überschritten, empfiehlt es sich, dem Nutzer eine aussagekräftige Nachricht zurückzugeben. Dieses
Muster wird häufig in Verbindung mit einer "Fehlerregel" verwendet um dem Anrufer Informationen zur Verfügung zu stellen
zum Kontingentverstoß. In der folgenden Richtlinie „Nachricht zuweisen“ werden Nachrichtenvorlagen verwendet
um Kontingentinformationen dynamisch in mehrere XML-Elemente einzufügen:
<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>
In der AssignMessage-Richtlinie unterstützen die folgenden Elemente im <Set>
-Element Nachrichtenvorlagen:
- Header
- QueryParam
- FormParam
- PayLoad
- Version
- Verb
- Pfad
- StatusCode
- ReasonPhrase
Beachten Sie auch hier, dass Ablaufvariablen in einer Nachrichtenvorlage in geschweiften Klammern angegeben werden.
Wenn diese Richtlinie ausgeführt wird, geschieht Folgendes:
- Die Header-Elemente erhalten Werte der angegebenen Ablaufvariablen.
- Die Nutzlast enthält eine Mischung aus Literaltext und Variablen (
client_id
wird dynamisch ausgefüllt). - Der StatusCode und ReasonPhrase enthalten nur Literaltext. Diese Elemente unterstützen jedoch auch Nachrichtenvorlagen, falls Sie sie verwenden möchten.
Beispiel
In einer Proxy-TargetEndpoint-Definition unterstützen untergeordnete Elemente von <SSLInfo>
Nachrichtenvorlagen. Entsprechend dem in Richtlinien verwendeten Muster werden die Ablaufvariablen in geschweiften Klammern bei Ausführung des Proxys ersetzt.
<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>
Wo können Sie Nachrichtenvorlagen verwenden?
Nachrichtenvorlagen werden in mehreren Richtlinien sowie in bestimmten Elementen der TargetEndpoint-Konfiguration unterstützt.
Richtlinien, die Nachrichtenvorlagen akzeptieren
Richtlinie | Elemente und untergeordnete Elemente, die Nachrichtenvorlagen unterstützen |
---|---|
AccessControl-Richtlinie | <SourceAddress> für das Attribut mask und die IP-Adresse. |
AssignMessage-Richtlinie | Untergeordnete <Set> -Elemente: Payload, ContentType, Verb, Version, Path, StatusCode, ReasonPhrase, Headers, QueryParams, FormParams
Untergeordnete
Untergeordnetes |
ExtensionCallout-Richtlinie |
<Input> |
ExtractVariables-Richtlinie | <JsonPath>
|
GenerateJWS-Richtlinie VerifyJWS-Richtlinie |
<Payload> (nur GenerateJWS-Richtlinie)
*Diese Elemente unterstützen die Nachrichtenvorlage nur, wenn type=map angegeben ist. |
GenerateJWT-Richtlinie VerifyJWT-Richtlinie |
<AdditionalClaims><Claim>
*Diese Elemente unterstützen die Nachrichtenvorlage nur, wenn type=map angegeben ist. |
LDAP-Richtlinie | <SearchQuery> |
MessageLogging-Richtlinie | <Syslog><Message>
|
OASValidation-Richtlinie | Element
|
RaiseFault-Richtlinie | Untergeordnete <Set> -Elemente: Payload, ContentType, Verb, Version, Path, StatusCode, ReasonPhrase, Headers, QueryParams, FormParams
|
SAMLAssertion-Richtlinie | <Template>
*Nur, wenn die Richtliniensignatur |
ServiceCallout-Richtlinie | Untergeordnete <Set> -Elemente: Payload, ContentType, Verb, Version, Path, StatusCode, ReasonPhrase, /Headers, QueryParams, FormParams
|
TargetEndpoint-Elemente, die Nachrichtenvorlagen akzeptieren
HTTPTargetConnection-Elemente | Untergeordnete Elemente, die Nachrichtenvorlagen unterstützen |
---|---|
SSLInfo | Enabled, KeyAlias, KeyStore, TrustStore, ClientAuthEnabled, CLRStore |
LocalTargetConnection | ApiProxy, ProxyEndpoint |
Pfad | – |
Syntax der Nachrichtenvorlage
In diesem Abschnitt werden die Regeln erläutert, die Sie befolgen müssen, um Nachrichtenvorlagen zu verwenden.
Variablen mit geschweiften Variablen kennzeichnen
Setzen Sie Variablennamen in geschweifte Klammern { }. Existiert die Variable nicht, wird ein wird ein leerer String in der Ausgabe zurückgegeben. Sie können jedoch Standardwerte in der Nachricht Vorlagen (Werte, die ersetzt werden, wenn die Variable nicht aufgelöst ist). Weitere Informationen finden Sie unter Standardwerte in Nachrichtenvorlagen festlegen
Das Einfügen des gesamten Strings in Nachrichtenvorlagen in Anführungszeichen ist zulässig, aber optional. Die folgenden beiden Nachrichtenvorlagen sind beispielsweise äquivalent:
<Set> <Headers> <Header name="x-h1">"Hello {user.name}"</Header> <Header name="x-h1">Hello {user.name}</Header> </Headers> </Set>
Standardwerte in Nachrichtenvorlagen festlegen
Wenn eine Vorlagenvariable nicht aufgelöst werden kann, ersetzt Edge eine leere Zeichenfolge. Sie können jedoch wie folgt einen Standardwert festlegen:
<Header name="x-h1">Test message. id = {request.header.id:Unknown}</Header>
Wenn im obigen Beispiel die Variable request.header.id
nicht aufgelöst werden kann, dann wird ihr Wert
wird durch Unknown
ersetzt. Beispiel:
Test message. id = Unknown
Weitere Informationen finden Sie unter Leerzeichen sind in Funktionsausdrücken nicht zulässig.
Leerzeichen in Funktionsausdrücken von Nachrichtenvorlagen sind nicht zulässig. Beispiel:
Zulässig:
{substring(alpha,0,4)} {createUuid()} {randomLong(10)}
Nicht zulässig:
{substring( alpha, 0, 4 )} { createUuid( ) } {randomLong( 10 )}
Legacy-Syntax für JSON-Nutzlasten
In Edge-Versionen vor dem Cloud-Release 16.08.17 war Folgendes nicht möglich:
Verwenden Sie geschweifte Klammern, um Variablenverweise in JSON-Nutzlasten anzugeben. In diesen älteren Versionen mussten Sie die Attribute variablePrefix
und variableSuffix
verwenden, um Trennzeichen anzugeben und diese zum Zusammenfassen von Variablennamen zu verwenden:
<Set> <Payload contentType="application/json" variablePrefix="@" variableSuffix="#"> {"name":"foo", "type":"@variable_name#"} </Payload> </Set>
Obwohl Apigee die Verwendung der neueren Syntax mit geschweiften Klammern empfiehlt, funktioniert die ältere Syntax weiterhin.
Funktionen für Nachrichtenvorlagen verwenden
Edge bietet eine Reihe von Funktionen, die Sie in Nachrichtenvorlagen verwenden können, um und Zeichenfolgenvariablen formatieren.
Die Funktionen für Nachrichtenvorlagen werden in der Funktionsreferenz zu Nachrichtenvorlagen ausführlich beschrieben.
Beispiel: toLowerCase()
Verwenden Sie die integrierte toLowerCase()
-Funktion, um eine Stringvariable in Kleinbuchstaben zu transformieren:
<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>
Wenn die foo.bar
-Flussvariable aufgelöst wird, werden die Zeichen in Kleinbuchstaben geschrieben.
Wenn foo.bar
nicht aufgelöst wird, wird der Standardwert FOO
ersetzt und in Kleinbuchstaben umgewandelt. Beispiel:
Test header: foo
Beispiel: escapeJSON()
Hier ist ein interessanter Anwendungsfall: Angenommen, Ihre Back-End-App gibt eine JSON-Antwort zurück, die gültige Escape-Zeichen enthält. Beispiel:
{ "code": "INVALID", "user_message": "Invalid value for \"logonId\" check your input." }
Nehmen wir an, Sie möchten diese Nachricht in einer benutzerdefinierten Nutzlast an den Client-Aufrufer zurückgeben. Die übliche Methode besteht darin, die Nachricht aus der Zielantwortnutzlast zu extrahieren und sie mit AssignMessage einer benutzerdefinierten Proxy-Antwort hinzuzufügen (d. h. Sie an den Client zurückzusenden).
Hier ist die ExtractVariables-Richtlinie, die die user_message
-Informationen in eine Variable mit dem Namen standard.systemMessage
extrahiert:
<ExtractVariables name="EV-BackendErrorResponse"> <DisplayName>EV-BackendErrorResponse</DisplayName> <JSONPayload> <Variable name="standard.systemMessage"> <JSONPath>$.user_message</JSONPath> </Variable> </JSONPayload> </ExtractVariables>
Hier ist eine gültige AssignMessage-Richtlinie, die die extrahierte Variable der Antwortnutzlast (Proxy-Antwort) hinzufügt:
<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>
Leider ist ein Problem aufgetreten. Die Richtlinie zum Extrahieren von Variablen entfernte die maskierten Anführungszeichen um einen Teil der Nachricht. Das bedeutet, dass die an den Client zurückgegebene Antwort ein ungültiges JSON-Format hat. Das haben Sie nicht wirklich beabsichtigt!
{ "systemMessage": "Invalid value for "logonId" check your input." }
Sie können dieses Problem umgehen, indem Sie die AssignMessage-Richtlinie so ändern, dass sie eine Funktion für Nachrichtenvorlagen verwendet, die die Anführungszeichen im JSON automatisch maskiert. Die Funktion escapeJSON()
maskiert alle Anführungszeichen oder anderen Sonderzeichen, die in einem JSON-Ausdruck vorkommen:
<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>
Die Funktion maskiert die eingebetteten Anführungszeichen, was zu einem gültigen JSON-Code führt, der genau Ihren Erwartungen entspricht:
{ "systemMessage": "Invalid value for \"logonId\" check your input.", }
Eine Nachrichtenvorlage ist ein dynamisches Stringersetzungsfeature, das Sie in bestimmten Richtlinien und in TargetEndpoint-Definitionen verwenden können. Mit den Funktionen der Nachrichtenvorlage können Sie nützliche Vorgänge wie Hashing, Stringmanipulation, Zeichenmaskierung und anderes in einer Nachrichtenvorlage ausführen.
In der folgendenAssignMessage-Richtlinie wird die Funktion toLowerCase()
beispielsweise in einem
Nachrichtenvorlage:
<AssignMessage name="AM-Set-Custom-Response"> <AssignTo createNew="false" type="response"/> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> <Set> <Headers> <Header name="x-h1">Test header: {Hello, toLowerCase(user.name)}</Header> </Headers> </Set> </AssignMessage>
In diesem Thema werden die Funktionen der Nachrichtenvorlage, ihre Argumente und Ausgaben beschrieben. In diesem Thema wird davon ausgegangen, dass Sie mit der Nachrichtenfunktion Vorlagen und in welchen Kontexten sie verwendet werden.
Hash-Funktionen
Einen Hash-Wert berechnen und die Stringdarstellung dieses Hash-Werts zurückgeben.
Hexadezimal-Hash-Funktionen
Einen Hash-Wert berechnen und die Stringdarstellung dieses Hash-Werts als Hexadezimalzahl zurückgeben.
Syntax
Funktion | Beschreibung |
---|---|
md5Hex(string)
|
Berechnet einen MD5-Hash, ausgedrückt als Hexadezimalzahl. |
sha1Hex(string)
|
Berechnet einen SHA1-Hash, ausgedrückt als Hexadezimalzahl. |
sha256Hex(string)
|
Berechnet einen SHA256-Hash, ausgedrückt als Hexadezimalzahl. |
sha384Hex(string)
|
Berechnet einen SHA384-Hash, ausgedrückt als Hexadezimalzahl. |
sha512Hex(string)
|
Berechnet einen SHA512-Hash, ausgedrückt als Hexadezimalzahl. |
Argumente
string – Die Hash-Funktionen verwenden ein einzelnes Stringargument, auf dem der Hash-Algorithmus berechnet wird. Das Argument kann ein Literalstring oder eine Stringablaufvariable sein.
Beispiele
Funktionsaufruf:
sha256Hex('abc')
Ergebnis:
ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad
Funktionsaufruf:
var str = 'abc'; sha256Hex(str)
Ergebnis:
ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad
Base64-Hash-Funktionen
Berechnet einen Hash-Wert und die Stringdarstellung dieses Hash-Werts als Base64-codierten Wert.
Syntax
Funktion | Beschreibung |
---|---|
md5Base64(string)
|
Berechnet einen MD5-Hash, ausgedrückt als Base64-codierter Wert. |
sha1Base64(string)
|
Berechnet einen SHA1-Hash, ausgedrückt als Base64-codierter Wert. |
sha256Base64(string)
|
Berechnet einen SHA256-Hash, ausgedrückt als Base64-codierter Wert. |
sha384Base64(string)
|
Berechnet einen SHA384-Hash, ausgedrückt als Base64-codierter Wert. |
sha512Base64(string)
|
Berechnet einen SHA512-Hash, ausgedrückt als Base64-codierter Wert. |
Argumente
string – Die Hash-Funktionen verwenden ein einzelnes Stringargument, auf dem der Hash-Algorithmus berechnet wird. Das Argument kann ein Literalstring oder eine Stringablaufvariable sein.
Beispiele
Funktionsaufruf:
sha256Base64('abc')
Ergebnis:
ungWv48Bz+pBQUDeXa4iI7ADYaOWF3qctBD/YfIAFa0=
Funktionsaufruf:
var str = 'abc'; sha256Base64(str)
Ergebnis:
ungWv48Bz+pBQUDeXa4iI7ADYaOWF3qctBD/YfIAFa0=
Stringfunktionen
Vorgänge für Strings in einer Nachrichtenvorlage ausführen.
Base64-Codierungsfunktionen
Strings mit dem Base64-Codierungsschema codieren und decodieren.
Syntax
Funktion | Beschreibung |
---|---|
encodeBase64(string)
|
Codiert einen String mit Base64-Codierung. Beispiel: encodeBase64(value) , wenn value abc enthält, gibt die Funktion diesen String zurück: YWJj
|
decodeBase64(string)
|
Decodiert einen Base64-codierten String. Beispiel: decodeBase64(value) , wenn value aGVsbG8sIHdvcmxk enthält, gibt die Funktion diesen String zurück: hello, world .
|
Argumente
string – Der String, der codiert oder decodiert werden soll. Kann ein Literalstring oder eine Stringablaufvariable sein.
Beispiel
<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>
Case-Konvertierungsfunktionen
Wandelt einen String in Groß- oder Kleinbuchstaben um.
Syntax
Funktion | Beschreibung |
---|---|
toUpperCase(string)
|
Einen String in Großbuchstaben konvertieren. |
toLowerCase(string)
|
Einen String in Kleinbuchstaben konvertieren. |
Argumente
string – Der zu konvertierende String. Kann ein Literalstring oder eine Stringablaufvariable sein.
Beispiel
<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>
Teilstring-Funktion
Gibt die Zeichen zwischen dem Start- und Endindex des angegebenen Strings zurück.
Syntax
substring(str,start_index,end_index)
Argumente
- str – Ein Literalstring oder eine Stringablaufvariable.
- start_index – Der Startindex in den String.
- end_index: (Optional) Der Endindex im String. Wenn nicht angegeben, ist der Endindex das Ende des Strings.
Beispiele
In den folgenden Beispielen wird angenommen, dass diese Ablaufvariablen vorhanden sind:
Variablenname | Wert |
---|---|
alpha
|
ABCDEFGHIJKLMNOPQRSTUVWXYZ |
seven
|
7 |
Hier sind Ergebnisse von Funktionsaufrufen, die diese Variablen verwenden:
Ausdruck der Nachrichtenvorlage | Ergebnis |
---|---|
{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
|
Funktion "Alle ersetzen"
Wendet einen regulären Ausdruck auf einen String an und ersetzt bei Übereinstimmungen die Übereinstimmung durch einen Ersatzwert.
Syntax
replaceAll(string,regex,value)
Argumente
- string – Ein Literalstring oder eine Stringablaufvariable, in der Ersetzungen vorgenommen werden sollen.
- regex – Ein regulärer Ausdruck.
- value – Der Wert zum Ersetzen von Regex-Übereinstimmungen innerhalb des Strings.
Beispiele
In den folgenden Beispielen nehmen wir an, dass diese Ablaufvariablen vorhanden sind:
Variablenname | Wert |
---|---|
header
|
Bearer ABCDEFGHIJKLMNOPQRSTUVWXYZ-9993
|
regex1
|
"^Bearer "
|
replacement
|
"TOKEN: "
|
Hier sind Ergebnisse von Funktionsaufrufen, die diese Variablen verwenden:
Ausdruck der Nachrichtenvorlage | Ergebnis |
---|---|
{replaceAll(header,"9993",'')}
|
Bearer ABCDEFGHIJKLMNOPQRSTUVWXYZ-
|
{replaceAll(header,regex1,'')}
|
ABCDEFGHIJKLMNOPQRSTUVWXYZ-9993
|
{replaceAll(header,regex1,replacement)}
|
TOKEN: ABCDEFGHIJKLMNOPQRSTUVWXYZ-9993
|
Funktion "Erstes ersetzen"
Ersetzt nur das erste Vorkommen der angegebenen Übereinstimmung mit regulärem Ausdruck im String.
Syntax
replaceFirst(string,regex,value)
Argumente
- string – Ein Literalstring oder eine Stringablaufvariable, in der Ersetzungen vorgenommen werden sollen.
- regex – Ein regulärer Ausdruck.
- value – Der Wert zum Ersetzen von Regex-Übereinstimmungen innerhalb des Strings.
Zeichenmaskierung und Codierungsfunktionen
Funktionen, die Sonderzeichen in einem String maskieren oder codieren.
Syntax
Funktion | Beschreibung |
---|---|
escapeJSON(string) | Umgekehrte Schrägstriche doppelte Anführungszeichen. |
escapeXML(string) | Ersetzt spitze Klammern, Apostroph, doppelte Anführungszeichen und kaufmännische Und-Zeichen durch die entsprechenden XML-Entitäten. Für XML 1.0-Dokumente verwenden.
|
escapeXML11(string) | Funktioniert wie "EscapeXML", aber für XML-v1.1-Entitäten Siehe "Verwendungshinweise" unten. |
encodeHTML(string) | Codiert Apostrophe, spitze Klammern und Und-Zeichen. |
Argumente
string – Der zu maskierende String. Kann ein Literalstring oder eine Stringablaufvariable sein.
Verwendungshinweise
XML 1.1 kann bestimmte Steuerzeichen darstellen, aber es kann keine Nullbyte oder entkoppelte Unicode-Ersatz-Codepoints darstellen, selbst nach der Escape-Angabe. Mit der Funktion escapeXML11() werden Zeichen entfernt, die nicht in die folgenden Bereiche passen:
[#x1-#xD7FF] | [#xE000-#xFFFD] | [#x10000-#x10FFFF]
Mit der Funktion escapeXML11()
werden Zeichen in folgenden Bereichen maskiert:
[#x1-#x8] | [#xB-#xC] | [#xE-#x1F] | [#x7F-#x84] | [#x86-#x9F]
Beispiele
Angenommen, es gibt eine Ablaufvariable mit dem Namen food und diesem Wert: "bread" & "butter"
. Dann wird die Funktion:
{escapeHTML(food)}
führt dann zu:
"bread" & "butter"
Zeitformatfunktionen
Gibt eine Stringdarstellung der Uhrzeit in der lokalen Zeitzone oder in UTC zurück.
Syntax
Funktion | Beschreibung |
---|---|
timeFormat(format,str)
|
Gibt das Datum zurück, das in der lokalen Zeitzone formatiert ist. |
timeFormatMs(format,str)
|
Gibt das Datum zurück, das in der lokalen Zeitzone formatiert ist. |
timeFormatUTC(format,str)
|
Gibt das Datum im UTC-Format zurück. |
timeFormatUTCMs(format,str)
|
Gibt das Datum im UTC-Format zurück. |
Argumente
- format – Ein String im Datums-/Uhrzeitformat. Kann ein Literalstring oder eine Stringvariable sein.
- str – Ein String oder eine Stringablaufvariable, die einen Zeitwert enthält. Der Wert kann seconds-since-epoch oder milliseconds-since-epoch für timeFormatMs sein.
Beispiele
Es wird davon ausgegangen, dass die lokale Zeitzone "Pazifik" ist
epoch_time_ms = 1494390266000
epoch_time = 1494390266
fmt1 = yyyy-MM-dd
fmt2 = yyyy-MM-dd HH-mm-ss
fmt3 = yyyyMMddHHmmss
Die Funktionen geben folgende Ergebnisse zurück:
- key – (erforderlich) Gibt den geheimen Schlüssel an, der als String codiert ist. Er wird für die Berechnung des HMAC verwendet.
- valueToSign – (erforderlich) Gibt die zu signierende Nachricht an. Es sollte sich um einen String handeln.
- keyencoding (optional): Der geheime Schlüsselstring wird gemäß dieser angegebenen Codierung decodiert. Zulässige Werte:
hex
,base16
,base64
,utf-8
. Standardeinstellung:utf-8
- outputencoding – (optional) Gibt den Verschlüsselungsalgorithmus an, der für die Ausgabe zu verwenden ist.
Zulässige Werte:
hex
,base16
,base64
. Bei den Werten wird die Groß-/Kleinschreibung nicht berücksichtigt;hex
undbase16
sind Synonyme. Standardeinstellung:base64
Funktion | Ausgabe |
---|---|
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 |
HMAC-Berechnungsfunktionen
Die HMAC-Berechnungsfunktionen bieten eine Alternative zur Verwendung der HMAC-Richtlinie zur Berechnung eines HMAC. Die Funktionen sind nützlich, wenn Sie eine kaskadierte HMAC-Berechnung durchführen, da die Ausgabe eines HMAC als Schlüssel für einen zweiten HMAC verwendet wird.
Syntax
Funktion | Beschreibung |
---|---|
hmacSha224(key,valueToSign[,keyencoding[,outputencoding]])
|
Berechnet einen HMAC mit der SHA-224-Hash-Funktion. |
hmacSha256(key,valueToSign[,keyencoding[,outputencoding]])
|
Codiert einen HMAC mit der SHA-256-Hash-Funktion. |
hmacSha384(key,valueToSign[,keyencoding[,outputencoding]])
|
Codiert einen HMAC mit der SHA-384-Hash-Funktion. |
hmacSha512(key,valueToSign[,keyencoding[,outputencoding]])
|
Codiert einen HMAC mit der SHA-512-Hash-Funktion. |
hmacMd5(key,valueToSign[,keyencoding[,outputencoding]])
|
Codiert einen HMAC mit der MD5-Hash-Funktion. |
hmacSha1(key, valueToSign [,keyencoding[,outputencoding]])
|
Codiert einen HMAC mit dem SHA-1-Verschlüsselungsalgorithmus. |
Argumente
Beispiele
In diesem Beispiel wird die AssignMessage-Richtlinie verwendet, um einen HMAC-256 zu berechnen und einer Ablaufvariable zuzuweisen:
<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>
Dieses Beispiel zeigt, wie Sie einen kaskadierenden HMAC generieren, der mit dem Signaturprozess AWS Signatur v4 verwendet werden kann. Dieses Beispiel verwendet die AssignMessage-Richtlinie, um die fünf Ebenen des kaskadierten HMAC zu generieren, die zum Berechnen einer Signatur für AWS Signature v4 verwendet werden:
<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>
Weitere Funktionen
UUID-Funktion erstellen
Erzeugt eine UUID und gibt diese zurück.
Syntax
createUuid()
Argumente
–
Beispiel
{createUuid()}
Beispielergebnis:
ec3ca9be-d1e1-4ef4-aee4-4a58f3130db8
Zufalls-Long-Generatorfunktion
Gibt eine zufällige lange Ganzzahl zurück.
Syntax
randomLong(args)
Argumente
- Wenn keine Argumente angegeben sind, gibt die Funktion eine zufällige lange Ganzzahl zurück, wie sie von der Java SecureRandom-Klasse berechnet wurde.
- Wenn ein Argument vorhanden ist, wird es als Minimalwert der Berechnung behandelt.
- Wenn ein zweites Argument vorhanden ist, wird es als Maximalwert der Berechnung behandelt.
Beispiel
{random()}
führt in etwa zu folgendem Ergebnis:
5211338197474042880
Regex-Textgenerator
Generiert einen Textstring, der mit einem bestimmten regulären Ausdruck übereinstimmt.
Syntax
xeger(regex)
Argument
regex – Ein regulärer Ausdruck.
Beispiel
In diesem Beispiel wird ein siebenstelliger String ohne Nullen generiert:
xeger('[1-9]{7}')
Beispielergebnis:
9857253
Null-coalescing-Funktion
Die Funktion firstnonnull()
gibt den Wert des Arguments ganz links und ohne Null zurück.
Syntax
firstnonnull(var1,varn)
Argument
var1 – eine Kontextvariable.
varn: Eine oder mehrere Kontextvariablen. Sie können das Argument ganz rechts auf einen String setzen, um einen Fallback-Wert bereitzustellen. Dieser Wert wird festgelegt, wenn keines der linksseitigen Argumente festgelegt ist.
Beispiele
In der folgenden Tabelle wird die Verwendung der Funktion veranschaulicht:
Vorlage | Var1 | Var2 | Var3 | Ergebnis |
---|---|---|---|---|
{firstnonnull(var1,var2)}
|
Nicht definiert | foo
|
– | foo
|
{firstnonnull(var1,var2)}
|
foo
|
bar
|
– | foo
|
{firstnonnull(var1,var2)}
|
foo
|
Nicht definiert | – | foo
|
{firstnonnull(var1,var2,var3)}
|
foo
|
bar
|
baz
|
foo
|
{firstnonnull(var1,var2,var3)}
|
Nicht definiert | bar
|
baz
|
bar
|
{firstnonnull(var1,var2,var3)}
|
Nicht definiert | Nicht definiert | baz
|
baz
|
{firstnonnull(var1,var2,var3)}
|
Nicht definiert | Nicht definiert | Nicht definiert | null
|
{firstnonnull(var1)}
|
Nicht definiert | – | – | null
|
{firstnonnull(var1)}
|
foo
|
– | – | foo
|
{firstnonnull(var1,var2)}
|
""
|
bar
|
– | ""
|
{firstnonnull(var1,var2,'fallback value')}
|
null
|
null
|
fallback value
|
fallback value
|
XPath-Funktion
Wendet einen XPath-Ausdruck auf eine XML-Variable an.
Syntax
xpath(xpath_expression,xml_string,[datatype])
Argumente
xpath_expression: Ein XPath-Ausdruck.
xml_string – Eine Ablaufvariable oder ein String, der XML enthält.
datatype: Gibt an (optional). den gewünschten Rückgabetyp der Abfrage. Es kann ein Knotenset, ein Knoten, eine Zahl, ein boolescher Wert, ein String sein. Die Standardeinstellung ist nodeet. Die Standardeinstellung ist meistens die richtige Wahl.
Beispiel 1
Angenommen, diese Kontextvariablen definieren einen XML-String und einen XPath-Ausdruck:
xml = "<tag><tagid>250397</tagid><readerid>1</readerid><rssi>74</rssi><date>2019/06/15</date></tag>" xpath = "/tag/tagid"
Die Funktion xpath()
wird in einer AssignMessage-Richtlinie so verwendet:
<AssignMessage> <AssignVariable> <Name>extracted_tag</Name> <Template>{xpath(xpath,xml)}</Template> </AssignVariable> </AssignMessage><
Die Funktion gibt den Wert <tagid>250397</tagid>
zurück. Dieser Wert wird in der Kontextvariable extracted_tag
abgelegt.
Beispiel 2
Wenn Sie nur den Wert des Knotens benötigen, verwenden Sie die Funktion text()
so:
<AssignMessage> <AssignVariable> <Name>extracted_tag</Name> <Template>{xpath('/tag/tagid/text()',xml)}</Template> </AssignVariable> </AssignMessage>
Als Ergebnis für diesen Vorgang wird die Kontextvariable extracted_tag
auf 250397
gesetzt.
Wenn mehrere Knoten ausgewählt sind, entspricht das Ergebnis von xpath()
allen Werten der Auswahl, die mit einem Komma verkettet sind.
Beispiel 3: XML-Namespaces
Wenn Sie einen Namespace festlegen möchten, fügen Sie weitere Parameter mit jeweils einem String wie prefix:namespaceuri
hinzu. Eine xpath()
-Funktion, die das untergeordnete Element eines Apigee-Texts auswählt, könnte beispielsweise so aussehen:
<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>
Für zusätzliche Namespaces können Sie der Funktion xpath()
bis zu zehn zusätzliche Parameter hinzufügen.
Sie können einen einfachen XPath-Ausdruck als String in einfachen Anführungszeichen angeben:
{xpath('/tag/tagid/text()',xml)}
Wenn der XPath-Ausdruck Namespace-Präfixe (und Doppelpunkte) enthält, müssen Sie diesen XPath-Ausdruck einer Variable zuweisen und den Variablennamen anstelle des Ausdrucks direkt angeben.
{xpath(xpathexpression,xml,ns1)}
Beispiel 4: Gewünschten Rückgabetyp angeben
Der optionale dritte Parameter, der an die Funktion xpath()
übergeben wird, gibt den gewünschten Rückgabetyp der Abfrage an.
Bei einigen XPath-Abfragen können numerische oder boolesche Werte zurückgegeben werden. Beispiel: Die Funktion count()
gibt eine Zahl zurück. Dies ist eine gültige XPath-Abfrage:
count(//Record/Fields/Pair)
Diese gültige Abfrage gibt einen booleschen Wert zurück:
count(//Record/Fields/Pair)>0
Rufen Sie in diesen Fällen die Funktion xpath()
mit einem dritten Parameter auf, der diesen Typ angibt:
{xpath(expression,xml,'number')} {xpath(expression,xml,'boolean')}
Wenn der dritte Parameter einen Doppelpunkt enthält, wird er als Namespace-Argument interpretiert.
Andernfalls wird der gewünschte Rückgabetyp behandelt. Wenn der dritte Parameter keiner der gültigen Werte ist (Groß-/Kleinschreibung wird nicht berücksichtigt), gibt die xpath()
-Funktion standardmäßig eine Knotengruppe zurück.
JSON-Pfadfunktion
Wendet einen JSON-Pfadausdruck auf eine JSON-Variable an.
Syntax
jsonPath(json-path,json-var,want-array)
Argumente
- (Erforderlich)
json-path
: (String) Ein JSON-Pfadausdruck. - (Erforderlich)
json-var
: (String) Eine Flussvariable oder ein String, der JSON enthält. - (Optional)
want-array
: (String) Wenn dieser Parameter auf'true'
gesetzt ist und die Ergebnismenge ein Array ist, werden alle Arrayelemente zurückgegeben. Wenn ein anderer Wert festgelegt wurde oder dieser Parameter weggelassen wird, wird nur das 0. Element eines Ergebnissatzarrays zurückgegeben. Wenn die Ergebnismenge kein Array ist, wird dieser dritte Parameter, sofern vorhanden, ignoriert.
Beispiel 1
Wenn dies die Nachrichtenvorlage ist:
The address is {jsonPath($.results[?(@.name == 'Mae West')].address.line1,the_json_variable)}
und the_json_variable
Folgendes enthält:
{ "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" } ] }
Dann ist das Ergebnis der Funktion:
The address is 1060 West Addison Street
Beachten Sie, dass die Ergebnismenge in diesem Fall ein einzelnes Element (kein Array von Elementen) ist. Wenn der Ergebnissatz ein Array wäre, würde nur das nullte Element des Arrays zurückgegeben. Wenn Sie das vollständige Array zurückgeben möchten, rufen Sie die Funktion mit 'true'
als dritten Parameter auf, wie im nächsten Beispiel gezeigt.
Beispiel 2
Wenn dies die Nachrichtenvorlage ist:
{jsonPath($.config.quota[?(@.operation=='ManageOrder')].appname,the_json_variable,'true')}
und the_json_variable
Folgendes enthält:
{ "results" : [ { "config": { "quota": [ { "appname": "A", "operation": "ManageOrder", "value": "900" }, { "appname": "B", "operation": "ManageOrder", "value": "1000" }, { "appname": "B", "operation": "SubmitOrder", "value": "800" } ] } } ] }
Dann ist das Ergebnis der Funktion:
['A','B']