Macros de velocidad para acciones de datos

Nota: Este artículo se aplica a las integraciones de acciones de datos de AWS Lambda, Genesys Cloud, Google, Microsoft Dynamics 365, Salesforce, servicios web y Zendesk.

Las integraciones de acciones de datos le permiten crear acciones personalizadas. Estas acciones personalizadas incluyen configuraciones de solicitud y configuraciones de respuesta con plantillas que utilizan Velocity Template Language. Estas plantillas admiten una variedad de macros Velocity.

Advertencia: Escapa de cualquier uso de variables de entrada o salida dentro de requestTemplate, SuccessTemplate, o requestUrlTemplate. Si no se escapan correctamente las variables con caracteres especiales, las acciones de datos fallan en la ejecución.
  • Utilice esc.jsonEncode para escapar cadenas dentro de cuerpos JSON. Véase esc.jsonEncode.
  • Utilice esc.url() o urlTool.optionalQueryParam() para escapar de la ruta o de los parámetros de consulta de una requestUrlTemplate o requestTemplate si se utilizan x-www.form-urlencoded valores. Véase String-escaping library y URL form encoding for data actions.

Las plantillas de velocidad son válidas para los siguientes campos:

  • requestUrlTemplate
  • encabezados
  • requestTemplate
  • SuccessTemplate

Para más información, ver Crea una acción personalizada, Solicitar configuración, y Configuración de respuesta.

Nota: Notación formal formal versus silenciosa

  • Notación formal: $ {variable}

    Si la variable es nula, la notación formal genera el nombre de la variable.

  • Notación formal silenciosa: $!{variable}

    Si la variable es nula, la notación silenciosa produce una cadena vacía.

Biblioteca de matemáticas

Prefijo: Matemáticas

Utilice estas macros matemáticas para realizar una operación matemática básica. Para más información, ver Clase MathTool en la documentación de Velocity.

Biblioteca de escape de cadenas

Prefijo: Esc

Utilice EscapeTool para escapar de las cadenas en las plantillas de Velocity. EscapeTool proporciona métodos para escapar salidas para Java, JSON, JavaScript, HTML, XML y SQL. EscapeTool también proporciona métodos para escapar de los caracteres de Velocity Template Language. Para más información, ver Clase EscapeTool en la documentación de Velocity.

Los siguientes métodos en particular son muy útiles:

  • $esc.urlFormEncode(): Utilice este método para escapar caracteres y cumplir las normas de codificación de formularios URL. Tenga en cuenta que los espacios se codifican como "+" con este método. Lo más probable es que no se utilice para el urlTemplate. Véase el método $esc.uriEncode().
  • $ esc.url (): Alias para el $esc.urlFormEncode() con la misma funcionalidad.
  • $esc.uriEncode(): Utilice este método para escapar caracteres para cumplir con la URI, por ejemplo, la URL, reglas. Este método debe utilizarse para escapar caracteres en el urlTemplate. Tenga en cuenta que este método codifica los espacios como '%20'.
  • $esc.jsonEncode(): Utilice este método para escapar los caracteres reservados de JSON en la salida. Permite almacenar JSON en forma de cadena.
  • $esc.jsonString(): Alias para el $esc.jsonEncode() con la misma funcionalidad.
  • $esc.jsonDecode(): Utilice este método para eliminar los caracteres reservados de JSON y obtener el JSON original.
  • $ esc.d (): Utilice este método para incluir un signo de dólar ($).

La siguiente tabla muestra ejemplos de entradas y salidas de varias macros. 

Advertencia: No utilice codificación JavaScript. $ esc.javascript ($ entrada) puede crear JSON no válido que interrumpe una acción.

Macros Entradas Salidas
$ esc.java ($ entrada) El no't decir, "¡Parada!" El no't decir, \"¡Parada!\"
$ esc.html ($ entrada) "pan de molde" Y "manteca" "pan con mantequilla"
$ esc.xml ($ entrada) "pan de molde" Y "manteca" "pan con mantequilla"
$ esc.sql ($ entrada) McHale's Marina McHale''s Marina

$esc.urlFormEncode($input)

o

$ esc.url ($ entrada)

hola aqui y alla~ hola+aquí+%26+aquí~

$esc.uriEncode($entrada)

hola aqui y alla~ hello%20here%20%26%20there%7E
$ esc.dollar $
$ esc.hash #
$ esc.backslash \
$ esc.quote "
$ esc.singleQuote '
$ esc.exclamación !

encoding.base64

Base64 codifica las cadenas que usted proporciona. 

Ejemplo de plantilla

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

Resultados de ejemplo de plantilla

Entradas Plantillas resueltas

primero == gato

segundo == perro

El campo codificado es Y2F0IGFuZCBkb2c =

esc.jsonEncode

Cuando construya cuerpos JSON para peticiones POST, PUT y PATH, debe escapar los caracteres reservados en cualquier cadena. Esta macro escapa de las comillas y otros caracteres según las reglas de codificación JSON.

Nota: esc.jsonEncode trata los caracteres Unicode de forma diferente a como lo hace EscapeTool.javascript()

Ejemplo de plantilla

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

Ejemplo de codificación

Entrada Producción

{

"foo": "bar"

}

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

Nulo

Nulo

""(cadena vacía)

""(cadena vacía)

esc.jsonDecode

Cuando tenga una cadena codificada en JSON y desee obtener la forma JSON de la misma, puede utilizar la macro esc.jsonDecode(). Esta macro descomprime las comillas y otros caracteres basándose en las reglas de codificación de JSON.

Ejemplo de plantilla

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

Ejemplo de descodificación

Entrada Producción

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

{

"foo": "bar"

}

successTemplateUtils.firstFromArray

Esta macro extrae el primer elemento de la cadena de matriz JSON proporcionada y tiene dos parámetros. Se requiere el primer parámetro, que es la matriz de entrada para el valor extraído. El segundo parámetro, que especifica la respuesta que se devuelve cuando la matriz está vacía, es opcional y, por defecto, no devuelve nada. Si la matriz no está vacía, se ignora el segundo parámetro. 

Si la entrada para firstFromArray Si los datos se extraen a través de translationMap JSONPath, no es necesario ningún escape de cadena. En los siguientes ejemplos de plantillas, identificadores podría provenir de una entrada de translationMap, como "identificadores": "$ .idArray".

Ejemplos de plantillas y resultados

Ejemplos de plantillas Entradas Plantillas resueltas
$ {successTemplateUtils.firstFromArray ("$ {ids}")} ids == "[1, 2, 3]" 1
ids == "[{\"identificación\": 1}, {\"identificación\": 2}, {\"identificación\": 3}, {\"identificación\": 4}]" {\"identificación\": 1}
ids == "[]"
ids == "" Esta entrada da como resultado un error.
$ {successTemplateUtils.firstFromArray (\"$ {ids} \", \"{}\")} ids == "[1, 2, 3]" 1
ids == "[{\"identificación\": 1}, {\"identificación\": 2}, {\"identificación\": 3}, {\"identificación\": 4}]" {\"identificación\": 1}
ids == "[]" {}
ids == "" Esta entrada da como resultado un error.
$ {successTemplateUtils.firstFromArray (\"$ {ids} \", \"$ esc.quote $ esc.quote \")} * ids == "[1, 2, 3]" 1
ids == "[{\"identificación\": 1}, {\"identificación\": 2}, {\"identificación\": 3}, {\"identificación\": 4}]" {\"identificación\": 1}
ids == "[]" ""
ids == "" Esta entrada da como resultado un error.

* Este ejemplo de plantilla utiliza EscapeTool para escapar caracteres. Para más información, ver Biblioteca de escape de cadenas.

successTemplateUtils.moveKeysIntoArrayOfObjects

Esta macro convierte los datos a un formato compatible con Architect y tiene dos parámetros obligatorios. El primer parámetro es la entrada de la respuesta original. El segundo parámetro es el nombre de la clave que la macro agrega a un objeto y el valor es el campo dinámico de la respuesta original.

Nota: Si la macro no puede convertir datos, la acción de datos devuelve un error o una matriz vacía.

Para devolver los datos convertidos, configure el traducciónMapa y SuccessTemplate en su acción de datos basada en el siguiente ejemplo.

Ejemplo de acción de datos

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

En la respuesta original, no puede acceder al GUID porque es una clave dinámica y no se puede aplanar correctamente.

Respuesta original devuelta

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

La macro mueve el ID a un objeto y lo devuelve como segmentoId

Macro devolvió la respuesta

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

urlTool.optionalQueryParam

Esta macro formatea un par clave-valor como parámetro de consulta, a menos que el valor esté vacío. De lo contrario, la macro devuelve una cadena vacía. No incluya el ampersand (&) en su plantilla; la macro agrega automáticamente el ampersand. Consulte los resultados del ejemplo de plantilla.  Utilice la macro solo después de al menos un parámetro de consulta obligatorio. En el siguiente ejemplo de plantilla, el parámetro de consulta requerido es $ {input.AMOUNT}.

Nota: Utilice notación formal silenciosa: $!{variable}.
Ejemplo de plantilla

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

Resultados de ejemplo de plantilla

Entradas Plantillas resueltas

input.AMOUNT == 30

input.DESCRIPTION == patatas

cantidad = 30 & descripción = patatas

input.AMOUNT == 30

input.DESCRIPTION == ""

cantidad = 30

Macros del método de cadena de Java

Utilice métodos de cadena de Java en las plantillas de Velocity para manipular variables de cadena, como cambiar el caso de un valor o extraer un valor de una cadena. Para más información, consulte Class String en la documentación de Java 17.

En el siguiente ejemplo, el método toUpperCase() convierte el valor de cadena de la variable $a a mayúsculas. los separar() El método divide la variable $ b en una matriz de cadenas. La variable $ d concatena valores de la variable $ a, la variable $ b y el primer elemento de la matriz para la variable $ c.

Ejemplo de plantilla

#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

Resultados de ejemplo de plantilla

Entradas Plantillas resueltas

input.string1 = value1

input.string2 = value1 + value2

Estamos usando "VALUE1" "valor1 + valor2" "valor2" para hacer esto.

Macros de Microsoft Dynamics

msdynamics.fieldSearchFilter

Esta macro crea un filtro de búsqueda dado un valor y una lista de campos que desea buscar. La macro compara el valor con cada uno de los campos de la lista.

Ejemplo de plantilla

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

Resultados de ejemplo de plantilla

Entradas Plantillas resueltas
input.EMAIL_ADDRESS = TestMail@example.com emailaddress1 eq 'TestMail@example.com' o emailaddress2 eq 'TestMail@example.com'

msdynamics.phoneNumberFilter

Esta macro crea un filtro de búsqueda dado un número de teléfono y una lista de campos que desea buscar. La macro elimina los caracteres no admitidos y cualquier valor que no sea un dígito, como + y paréntesis, del número de teléfono y agrega "o" entre cada campo. Este filtro de búsqueda es útil para comparar un número de teléfono con varios números de teléfono en un registro de cuenta.

Ejemplo de plantilla

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

Resultados de ejemplo de plantilla

Entradas Plantillas resueltas
input.PHONE_NUMBER = +1 (555) 555-0123 teléfono1 eq '+1 (555) 555-0123' o teléfono2 eq '+1 (555) 555-0123' o teléfono1 eq '15555550123' o teléfono2 eq '15555550123'

Macros de Salesforce

salesforce.escReservado

Esta macro escapa los caracteres reservados de las consultas de Salesforce SOQL / SOSL realizadas en una URL. Salesforce se reserva los siguientes caracteres: ? & | ! { } [ ] ( ) ^ ~ * : \ " ' + -. Esta macro asegura que los personajes se escapen correctamente. Para más información, ver ENCONTRAR {SearchQuery} en la documentación de Salesforce.

Ejemplo de plantilla

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

Resultados de ejemplo de plantilla

Entradas Plantillas resueltas
input.PHONE_NUMBER == (555) 555-5555 ENCONTRAR {\ (555 \) 555 \ -5555} EN CAMPOS DE TELÉFONO

Para más información, ver Acerca de las acciones personalizadas para integraciones.

Para obtener más información sobre las integraciones, consulte Acerca de las integraciones de acciones de datos.