Nachrichtenvorlagen

Diese Seite gilt für Apigee und Apigee Hybrid.

Apigee Edge-Dokumentation aufrufen

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. Falls unterstützt, können Sie mit diesem Feature 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 wird der Wert der Flussvariable user.name in geschweiften Klammern ausgewertet und zur Laufzeit durch den Nutzlaststring ersetzt. Beispiel: Wenn user.name=jdoe, so ist 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 mit einer "Fehlerregelregel" verwendet, um dem Aufrufer Informationen zum Kontingentverstoß bereitzustellen. In der folgenden AssignMessage-Richtlinie werden Nachrichtenvorlagen verwendet, um Kontingentinformationen dynamisch in mehreren XML-Elementen 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>
  </Set>
</AssignMessage>

In der AssignMessage-Richtlinie unterstützen die folgenden Elemente im <Set>-Element Nachrichtenvorlagen:

  • <Header>
  • <QueryParam>
  • <FormParam>
  • <PayLoad>
  • <Version>
  • <Verb>
  • <Path>
  • <StatusCode>

Beachten Sie auch hier, dass Ablaufvariablen in einer Nachrichtenvorlage in geschweiften Klammern angegeben werden müssen.

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> enthält nur Literaltext. Dieses Element unterstützt jedoch auch Nachrichtenvorlagen, wenn Sie diese 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 verschiedenen Richtlinien sowie in bestimmten Elementen unterstützt, die in der TargetEndpoint-Konfiguration verwendet werden.

Richtlinien, die Nachrichtenvorlagen akzeptieren

In der folgenden Tabelle sind die Richtlinien und Informationen dazu aufgeführt, welche Elemente/untergeordneten Elemente unterstützt werden:

Richtlinie Elemente/Untergeordnete Elemente
AccessControl-Richtlinie <SourceAddress> für das Attribut mask und die IP-Adresse.
AssignMessage-Richtlinie Untergeordnete <Set>-Elemente: Payload, ContentType, Verb, Version, Path, StatusCode, Headers, QueryParams, FormParams

Untergeordnete <Add>-Elemente: Headers, QueryParams, FormParams

Untergeordnetes <AssignVariable>-Element: <Template>

CORS-Richtlinie

<AllowHeaders>

<AllowMethods>

<AllowOrigins>

<ExposeHeaders>
ExtractVariables-Richtlinie <JsonPath>
GenerateJWS-Richtlinie
VerifyJWS-Richtlinie

<Payload> (nur GenerateJWS-Richtlinie)

<AdditionalHeaders><Claim>

*Diese Elemente unterstützen die Nachrichtenvorlage nur, wenn type=map angegeben ist.
GenerateJWT-Richtlinie
VerifyJWT-Richtlinie		 <AdditionalClaims><Claim>

<AdditionalHeaders><Claim>

*Diese Elemente unterstützen die Nachrichtenvorlage nur, wenn type=map angegeben ist.
HTTPModifier-Richtlinie Untergeordnete <Set>-Elemente:
  • <ContentType>
  • <Verb>
  • <Version>
  • <Path>
  • <StatusCode>
  • <Headers>
  • <QueryParams>
  • <FormParams>

Untergeordnete <Add>-Elemente:

  • <Headers>
  • <QueryParams>
  • <FormParams>
MessageLogging-Richtlinie

<CloudLogging><Message>

<Syslog><Message>

<File><Message>
OASValidation-Richtlinie Element <OASResource>
RaiseFault-Richtlinie

<Set>-Elemente:

  • <ContentType>
  • <FormParams>
  • <Headers>
  • <QueryParams>
  • <StatusCode>
  • <Path>
  • <Payload>
  • <Verb>
  • <Version>

<Add>-Elemente:

  • <FormParams>
  • <Headers>
  • <QueryParams>
SAMLAssertion-Richtlinie <Template>

*Nur, wenn die Richtliniensignatur <GenerateSAMLAssertion> ist
ServiceCallout-Richtlinie

<Set>-Elemente:

  • <ContentType>
  • <FormParams>
  • <Headers>
  • <QueryParams>
  • <StatusCode>
  • <Path>
  • <Payload>
  • <Verb>
  • <Version>

<Add>-Elemente:

  • <FormParams>
  • <Headers>
  • <QueryParams>

<HTTPTargetConnection>/<URL>: Siehe URL-Vorlagen.

<TargetEndpoint>-Elemente, die Nachrichtenvorlagen akzeptieren

<HTTPTargetConnection>-Elemente Untergeordnete Elemente, die Nachrichtenvorlagen unterstützen
<SSLInfo> <Enabled>, <KeyAlias>, <KeyStore>, <TrustStore>, <ClientAuthEnabled>, <CLRStore>
<LocalTargetConnection> <ApiProxy>, <ProxyEndpoint>, <Path>
<Path> –
<URL> Keine untergeordneten Elemente. Informationen zur Nutzung finden Sie unter URL-Vorlagen.

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

Variablennamen in geschweifte Klammern { } einschließen. Wenn die Variable nicht vorhanden ist, wird in der Ausgabe ein leerer String zurückgegeben. Sie können jedoch Standardwerte in Nachrichtenvorlagen angeben, die ersetzt werden, wenn die Variable nicht aufgelöst wurde. 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>

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 )}

Verschachtelte Funktionen werden nicht unterstützt

Das Aufrufen einer Funktion in einer anderen Funktion in einer Vorlage wird nicht unterstützt. Sie können beispielsweise Folgendes nicht verwenden: 

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

Stringliterale in Vorlagenfunktionen in einfache Anführungszeichen setzen

Wenn Sie in Funktionen Stringliterale angeben, setzen Sie sie in einfache Anführungszeichen statt in doppelte Anführungszeichen.

Beispiel: 
{replaceAll('BEARER: 1234','^Bearer ','TOKEN:')}

Verwendung von Sonderzeichen in Stringliteralen vermeiden

Vermeiden Sie Sonderzeichen wie „:“, „/“, „\“, „<“ oder „>“ in Stringliteralen. Diese Zeichen können Fehler verursachen. Wenn ein Stringliteral Sonderzeichen erfordert, weisen Sie den Wert einer Variablen mithilfe einer Python- oder JavaScript-Richtlinie zu und verwenden Sie dann die Variable in der Vorlage.

Standardwerte in Nachrichtenvorlagen festlegen

Wenn eine Vorlagenvariable nicht aufgelöst werden kann, ersetzt Apigee eine leere Zeichenfolge. So können Sie jedoch einen Standardwert angeben:

<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, wird der Wert durch Unknown ersetzt. Beispiel:

Test message. id = Unknown

URL-Vorlagen

Das URL-Element unterstützt Vorlagen mit derselben Syntax wie andere Elemente.

Dieses Beispiel zeigt eine mit Variablen erstellte URL:

<URL>{targeturl}</URL>

In diesem Beispiel wird ein Standardwert für das Protokoll gezeigt:

<URL>{protocol:https}://{site:google.com}/path</URL>

Legacy-Syntax für JSON-Nutzlasten

In Apigee-Versionen vor dem Cloud-Release 16.08.17 konnten Sie keine geschweiften Klammern verwenden, um Variablenreferenzen in JSON-Nutzlasten zu kennzeichnen. 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>

Apigee empfiehlt zwar, die neuere geschweifte Klammer zu verwenden, doch die ältere Syntax funktioniert weiterhin.

Funktionen für Nachrichtenvorlagen verwenden

Apigee bietet eine Reihe von Funktionen, die Sie in Nachrichtenvorlagen verwenden können, um Stringvariablen zu maskieren, zu codieren, zu hashen und zu formatieren, wie unten 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 ein interessanter Anwendungsfall: Angenommen, Ihre Back-End-App gibt eine JSON-Antwort mit gültigen Maskierungszeichen zurück. 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 mit AssignMessage zu 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>

Ein Problem ist aufgetreten. Die ExtractVariables-Richtlinie entfernt die maskierten Anführungszeichen um einen Teil der Nachricht. Das bedeutet, dass die an den Client zurückgegebene Antwort eine ungültige JSON-Antwort ist. 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. Diese Funktion, escapeJSON(), maskiert alle Anführungszeichen oder anderen Sonderzeichen in einem JSON-Ausdruck: 

<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-Format führt, also zum gewünschten Ergebnis:

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

Eine Nachrichtenvorlage ist ein dynamisches Feature zur Stringersetzung, 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 folgenden AssignMessage-Richtlinie wird beispielsweise die Funktion toLowerCase() in einer Nachrichtenvorlage verwendet:

<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 Abschnitt werden die Funktionen der Nachrichtenvorlage sowie deren Argumente und Ausgaben beschrieben. In diesem Thema wird davon ausgegangen, dass Sie mit Nachrichtenvorlagen und den Kontexten vertraut sind, in denen 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 (in einfachen Anführungszeichen) 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 (in einfachen Anführungszeichen) 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 (in einfachen Anführungszeichen) 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) Wandelt einen String in Großbuchstaben um.
toLowerCase(string) Wandelt einen String in Kleinbuchstaben um.

Argumente

string: Der String, der umgewandelt werden soll. Kann ein Literalstring (in einfachen Anführungszeichen) 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 (in einfachen Anführungszeichen) oder eine Stringablaufvariable.
  • start_index: Der Startindex im 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 (in einfachen Anführungszeichen) 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 (in einfachen Anführungszeichen) 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, Apostrophe, doppelte Anführungszeichen und 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 (in einfachen Anführungszeichen) oder eine Stringablaufvariable sein.

Verwendungshinweise

XML 1.1 kann bestimmte Steuerzeichen darstellen, jedoch nicht nach der Maskierung die Nullbyte bzw. nicht gekoppelten Unicode-Ersatzpunkte darstellen. 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". Die Funktion:

{escapeHTML(food)}

Ergebnisse in:

&quot;bread&quot; &amp; &quot;butter&quot;

Zeitformatfunktionen

Gibt eine Stringdarstellung der Uhrzeit in UTC zurück.

Syntax

Funktion Beschreibung
timeFormat(format,str)

Gibt das Datum im UTC-Format zurück.

DEPRECATED: Gibt das Datum zurück, das in der lokalen Zeitzone formatiert ist.
timeFormatMs(format,str)

Gibt das Datum im UTC-Format zurück.

DEPRECATED: 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 mit einem Datums-/Uhrzeitformat. Kann ein Literalstring (in einfachen Anführungszeichen) oder eine Stringvariable sein. Verwenden Sie eine Variable anstelle eines Literals, wenn das Format einen Doppelpunkt enthält. Siehe den vorherigen Hinweis in diesem Abschnitt.
  • 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:

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

  • 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 und base16 sind Synonyme. Standardeinstellung: base64

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, die von der Java SecureRandom-Klasse berechnet wird.
  • 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

{randomLong()}

Die Ausgabe sieht in etwa so aus:

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

datatype: (Optional) Gibt den gewünschten Rückgabetyp der Abfrage an. Gültige Werte sind nodeset, node, number, boolean oder string. Der Standardwert ist nodeset. 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: 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.

Anstatt einen XPath-Ausdruck mit Sonderzeichen als Stringliteral anzugeben, verwenden Sie eine Variable, um diesen String in die Funktion aufzunehmen. Weitere Informationen finden Sie unter Vermeiden von Sonderzeichen in Stringliteralen.

{xpath(xpathexpression,xml,ns1)}

Beispiel 3: 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 den 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']