Geschwindigkeitsmakros für Datenaktionen

Hinweis: Dieser Artikel gilt für die Datenaktionsintegrationen AWS Lambda, Genesys Cloud, Google, Microsoft Dynamics 365, Salesforce, Webdienste und Zendesk.

Mit den Integrationen für Datenaktionen können Sie benutzerdefinierte Aktionen erstellen. Diese benutzerdefinierten Aktionen umfassen Anfragekonfigurationen und Antwortkonfigurationen mit Vorlagen, die die Velocity Template Language verwenden. Diese Vorlagen unterstützen eine Reihe von Velocity-Makros.

Warnung: Jede Verwendung von Eingabe- oder Ausgabevariablen innerhalb von requestTemplate, successTemplate, oder requestUrlTemplateist zu vermeiden. Wenn Sie Variablen mit Sonderzeichen nicht richtig entschlüsseln, schlagen Ihre Datenaktionen bei der Ausführung fehl.
  • Verwenden esc.jsonEncode um Zeichenfolgen in JSON-Körpern zu maskieren. Sehen esc.jsonEncode .
  • Verwenden Sie esc.url() oder urlTool.optionalQueryParam(), um Pfad- oder Abfrageparameter für ein requestUrlTemplate oder requestTemplate zu entschlüsseln, wenn x-www.form-urlencoded Werte verwendet werden. Siehe String-escaping library und URL form encoding for data actions.

Velocity-Vorlagen sind für die folgenden Felder gültig:

  • requestUrlTemplate
  • Kopfzeilen
  • requestTemplate
  • successTemplate

Weitere Informationen finden Sie unter Erstellen einer benutzerdefinierten Aktion, Anforderungskonfiguration, und Antwortkonfiguration.

Hinweis: Formale vs. stille formale Notation

  • Formale Notation: ${Variable}

    Wenn die Variable null ist, gibt die formale Notation den Variablennamen aus.

  • Stille formale Notation: $!{Variable}

    Wenn die Variable null ist, gibt die stille Notation einen leeren String aus.

Mathematische Bibliothek

Präfix: mathe

Verwenden Sie diese Mathematikmakros, um eine grundlegende mathematische Operation durchzuführen. Weitere Informationen finden Sie unter Klasse MathTool in der Velocity-Dokumentation

Bibliothek zur Zeichenkettenabtrennung

Präfix: esc

Verwenden Sie EscapeTool, um Zeichenketten in Velocity-Vorlagen zu entschlüsseln. EscapeTool bietet Methoden zum Escapen von Ausgaben für Java, JSON, JavaScript, HTML, XML und SQL. EscapeTool bietet auch Methoden, um Zeichen der Velocity Template Language zu entkommen. Weitere Informationen finden Sie unter Klasse EscapeTool in der Velocity-Dokumentation

Insbesondere folgende Methoden sind sehr hilfreich:

  • $esc.urlFormEncode() : Verwenden Sie diese Methode, um Zeichen zu maskieren, um den Codierungsregeln für URL-Formulare zu entsprechen. Beachten Sie, dass die Leerzeichen bei dieser Methode als „+“ kodiert werden. Es wird höchstwahrscheinlich nicht für die URL-Vorlage verwendet. Siehe die $esc.uriEncode() Methode.
  • $esc.url(): Alias für die $esc.urlFormEncode() mit der gleichen Funktionalität.
  • $esc.uriEncode() : Verwenden Sie diese Methode, um Zeichen zu maskieren, um den URI-Regeln (z. B. der URL) zu entsprechen. Diese Methode sollte verwendet werden, um Zeichen in der URL-Vorlage zu maskieren. Beachten Sie, dass Leerzeichen bei dieser Methode als „%20“ kodiert werden.
  • $esc.jsonEncode() : Verwenden Sie diese Methode, um die reservierten JSON-Zeichen in der Ausgabe zu maskieren. Es ermöglicht die Speicherung von JSON in einer Zeichenfolgenform.
  • $esc.jsonString() : Alias für die $esc.jsonEncode() mit der gleichen Funktionalität.
  • $esc.jsonDecode() : Verwenden Sie diese Methode, um die reservierten Zeichen von JSON zu entschlüsseln, was zum ursprünglichen JSON führt.
  • $esc.d(): Verwenden Sie diese Methode, um ein Dollarzeichen ($) einzufügen.

Die folgende Tabelle zeigt Beispiele für die Ein- und Ausgänge verschiedener Makros. 

Warnung: Verwenden Sie keine JavaScript-Kodierung. $esc.javascript($input) kann ungültiges JSON erzeugen, das eine Aktion unterbricht

Makros Eingaben Ausgaben
$esc.java($input) Er sagte nicht't, "Stop!" Er hat'nicht gesagt, \"Stop! \"
$esc.html($Eingabe) "Brot" & "Butter" "Brot" und "Butter"
$esc.xml($Eingabe) "Brot" & "Butter" "Brot" und "Butter"
$esc.sql($input) McHale's Navy McHale''s Navy

$esc.urlFormEncode($input)

oder

$esc.url($input)

Hallo hier und da~ hallo+hier+%26+dort~

$esc.uriEncode($input)

Hallo hier und da~ Hallo%20hier%20%26%20dort%7E
$esc.dollar $
$esc.hash #
$esc.backslash \
$esc.quote "
$esc.singleQuote '
$esc.exclamation !

kodierung.base64

Base64 kodiert die von Ihnen bereitgestellten Zeichenketten. 

Vorlagenname

The encoded field is $encoding.base64(\"${first} and ${second}\")

Vorlage Beispielergebnisse

Eingaben Aufgelöste Vorlagen

erste == Katze

zweite == Hund

Das verschlüsselte Feld lautet Y2F0IGFuZCBkb2c=

esc.jsonEncode

Wenn Sie JSON-Körper für POST-, PUT- und PATH-Anfragen erstellen, müssen Sie reservierte Zeichen in allen Zeichenfolgen mit Escapezeichen versehen. Mit diesem Makro werden Anführungszeichen und andere Zeichen entsprechend den JSON-Kodierungsregeln umgangen.

Notiz : esc.jsonEncode behandelt Unicode-Zeichen anders als EscapeTool.javascript() tut. 

Vorlagenname

$esc.jsonEncode(${input.json})

Codierungsbeispiel

Eingabe Ausgabe

{

„foo“:“bar“

}

{\n\t\“foo\“:\“bar\“\n}

Null

Null

""(leerer String)

""(leerer String)

esc.jsonDecode

Wenn Sie eine JSON-codierte Zeichenfolge haben und eine JSON-Form davon haben möchten, können Sie die verwenden esc.jsonDecode() Makro. Dieses Makro entfernt Anführungszeichen und andere Zeichen basierend auf JSON-Codierungsregeln.

Vorlagenname

$esc.jsonDecode(${input.escapedjson})

Dekodierungsbeispiel

Eingabe Ausgabe

{\n\t\“foo\“:\“bar\“\n}

{

„foo“:“bar“

}

successTemplateUtils.firstFromArray

Dieses Makro extrahiert das erste Element aus dem angegebenen JSON-Array-String und hat zwei Parameter. Der erste Parameter, der das Eingabefeld für den extrahierten Wert darstellt, ist erforderlich. Der zweite Parameter, der die Antwort angibt, die zurückgegeben wird, wenn das Array leer ist, ist optional und gibt in der Standardeinstellung nichts zurück. Wenn das Array nicht leer ist, wird der zweite Parameter ignoriert. 

Wenn die Eingabe für firstFromArray Daten sind, die durch die translationMap JSONPath extrahiert wurden, dann ist kein String-Escaping erforderlich In den folgenden Vorlagenbeispielen könnte ids aus einem translationMap-Eintrag stammen, z. B. "ids" "$.idArray".

Beispiele für Vorlagen und Ergebnisse

Beispiele für Vorlagen Eingaben Aufgelöste Vorlagen
${successTemplateUtils.firstFromArray("${ids}")} ids == "[1, 2, 3]" 1
ids == "[{\"id\":1}, {\"id\":2}, {\"id\":3}, {\"id\":4}]" {\"id\":1}
ids == "[]"
ids == "" Diese Eingabe führt zu einem Fehler.
${successTemplateUtils.firstFromArray(\"${ids}\", \"{}\")} ids == "[1, 2, 3]" 1
ids == "[{\"id\":1}, {\"id\":2}, {\"id\":3}, {\"id\":4}]" {\"id\":1}
ids == "[]" {}
ids == "" Diese Eingabe führt zu einem Fehler.
${successTemplateUtils.firstFromArray(\"${ids}\", \"$esc.quote $esc.quote\")}* ids == "[1, 2, 3]" 1
ids == "[{\"id\":1}, {\"id\":2}, {\"id\":3}, {\"id\":4}]" {\"id\":1}
ids == "[]" „“
ids == "" Diese Eingabe führt zu einem Fehler.

* Dieses Beispiel verwendet EscapeTool, um Zeichen zu entschlüsseln. Weitere Informationen finden Sie unter String-escaping library.

successTemplateUtils.moveKeysIntoArrayOfObjects

Dieses Makro konvertiert Daten in ein Format, das mit Architect kompatibel ist, und hat zwei erforderliche Parameter. Der erste Parameter ist die Eingabe aus der ursprünglichen Antwort. Der zweite Parameter ist der Schlüsselname, den das Makro zu einem Objekt hinzufügt, und der Wert ist das dynamische Feld aus der ursprünglichen Antwort.

Hinweis: Wenn das Makro Daten nicht konvertieren kann, gibt die Datenaktion einen Fehler oder ein leeres Feld zurück.

Um die konvertierten Daten zurückzugeben, konfigurieren Sie die translationMap und successTemplate in Ihrer Datenaktion nach dem folgenden Beispiel.

Beispiel für eine Datenaktion

"config": {
  "request": {
    "requestUrlTemplate": "https://some.website.com/with/normalized/data",
    "requestType": "GET",
    "headers": {
    },
    "requestTemplateDefault": true
  },
  "response": {
    "translationMap": {
      "entitySegmentMembershipUps": "$.*.path.to.dynamic.key"
    },
    "translationMapDefaults": {},
    "successTemplate": "{\"segments\": ${successTemplateUtils.moveKeysIntoArrayOfObjects(${entitySegmentMembershipUps})},\"segmentId\")}}"
  }
}

In der ursprünglichen Antwort können Sie nicht auf die GUID zugreifen, da es sich um einen dynamischen Schlüssel handelt, der nicht korrekt geglättet werden kann.

Ursprünglich zurückgegebene Antwort

"segmentMembership": { 
  "ups": { 
    "a959c128-d6d9-4a42-a307-c5d278cfcbe2": { 
      "lastQualificationTime": "2020-11-16T03:23:31Z", 
      "status": "realized" 
    } 
  }
}

Das Makro verschiebt die ID in ein Objekt und gibt sie als segmentIdzurück. 

Antwort des Makros

"segments": [
  {
    "lastQualificationTime": "2020-11-16T03:23:31Z",
    "status": "realized",
    "segmentId": "a959c128-d6d9-4a42-a307-c5d278cfcbe2"
  }
]

urlTool.optionalQueryParam

Dieses Makro formatiert ein Schlüssel-Wert-Paar als Abfrageparameter, sofern der Wert nicht leer ist. Andernfalls gibt das Makro eine leere Zeichenkette zurück. Fügen Sie das kaufmännische Und (&) nicht in Ihre Vorlage ein; das Makro fügt das kaufmännische Und automatisch hinzu. Siehe die Ergebnisse der Vorlage.  Verwenden Sie das Makro nur nach mindestens einem erforderlichen Abfrageparameter. Im folgenden Vorlagenbeispiel lautet der erforderliche Abfrageparameter ${input.AMOUNT}.

Hinweis: Verwenden Sie die stille formale Notation: $!{Variable}.
Vorlagenname

amount=${input.AMOUNT}$urlTool.optionalQueryParam(\"description\", $!{input.DESCRIPTION})

Vorlage Beispielergebnisse

Eingaben Aufgelöste Vorlagen

input.AMOUNT == 30

input.DESCRIPTION == Kartoffeln

menge=30&Beschreibung=Kartoffeln

input.AMOUNT == 30

input.DESCRIPTION == ""

betrag=30

Java-String-Methoden-Makros

Verwenden Sie Java-String-Methoden in Velocity-Templates, um String-Variablen zu manipulieren, z. B. um die Groß-/Kleinschreibung eines Wertes zu ändern oder einen Wert aus einem String zu extrahieren. Weitere Informationen finden Sie unter Class String in der Java 17-Dokumentation.

Im folgenden Beispiel wird die toUpperCase() Die Methode wandelt den Zeichenfolgenwert der Variablen $a in Großbuchstaben um. Die Methode split() zerlegt die Variable $b in ein Array von Strings Die Variable $d verkettet die Werte der Variablen $a, der Variablen $b und des ersten Elements im Array der Variablen $c.

Vorlagenname

#set($a = ${input1.string1} )
#set($a = $a.toUpperCase() )
#set($b = ${input1.string2} )
#set($c = $b.split("\+") )
#set($d = "We are using ""${a}"" ""${b}"" ""$c[1]"" to render this." )
$d

Vorlage Beispielergebnisse

Eingaben Aufgelöste Vorlagen

input.string1 = Wert1

input.string2 = Wert1+Wert2

Wir verwenden "VALUE1" "value1+value2" "value2" , um dies darzustellen.

Microsoft Dynamics 365

msdynamics.fieldSearchFilter

Dieses Makro erstellt einen Suchfilter mit einem Wert und einer Liste von Feldern, die Sie durchsuchen möchten. Das Makro vergleicht den Wert mit jedem der Felder in der Liste.

Vorlagenname

$msdynamics.fieldSearchFilter(\"$input.EMAIL_ADDRESS\", [\"emailaddress1\", \"emailadress2\"]

Vorlage Beispielergebnisse

Eingaben Aufgelöste Vorlagen
input.EMAIL_ADDRESS = TestMail@example.com emailaddress1 eq 'TestMail@example.com' oder emailaddress2 eq 'TestMail@example.com'

msdynamics.phoneNumberFilter

Dieses Makro erstellt einen Suchfilter für eine Telefonnummer und eine Liste von Feldern, die Sie durchsuchen möchten. Das Makro entfernt nicht unterstützte Zeichen und alle nicht-zifferigen Werte, wie z. B. + und Klammern, aus der Telefonnummer und fügt "oder" zwischen die einzelnen Felder ein. Dieser Suchfilter ist nützlich, um eine Telefonnummer mit mehreren Telefonnummern in einem Kontodatensatz zu vergleichen.

Vorlagenname

$msdynamics.phoneNumberFilter(\"$input.PHONE_NUMBER\", [\"telephone1\", \"telephone2\"])

Vorlage Beispielergebnisse

Eingaben Aufgelöste Vorlagen
input.PHONE_NUMBER = +1 (555) 555-0123 telefon1 eq '+1 (555) 555-0123' oder Telefon2 eq '+1 (555) 555-0123' oder Telefon1 eq '15555550123' oder Telefon2 eq '15555550123'

Salesforce-Makros

salesforce.escReserved

Mit diesem Makro werden reservierte Zeichen von Salesforce SOQL/SOSL-Abfragen in einer URL umgangen. Salesforce behält sich die folgenden Zeichen vor: ? & | ! { } [ ] ( ) ^ ~ * : \ " ' + -. Dieses Makro stellt sicher, dass die Zeichen korrekt escaped werden. Weitere Informationen finden Sie unter FIND {SearchQuery} in der Salesforce-Dokumentation

Vorlagenname

FIND {$salesforce.escReserved(${input.PHONE_NUMBER})} IN PHONE FIELDS

Vorlage Beispielergebnisse

Eingaben Aufgelöste Vorlagen
input.PHONE_NUMBER == (555) 555-5555 SUCHE {\(555\) 555\-5555} IN TELEFONFELDERN

Weitere Informationen finden Sie unter Über benutzerdefinierte Aktionen für Integrationen.

Weitere Informationen zu den Integrationen finden Sie unter Über die Integrationen von Datenaktionen.