Configuración de respuesta para acciones de datos
Puede crear acciones personalizadas para las integraciones de acciones de datos. Una acción personalizada incluye una solicitud y una respuesta en su configuración. Para más información, ver Crea una acción personalizada.
Este artículo explica las partes de la respuesta. Para obtener información sobre solicitudes, consulte Solicitar configuración.
Las acciones personalizadas utilizan mapas de traducción y plantillas de éxito para convertir respuestas sin procesar de servicios web remotos o su función AWS Lambda en respuestas resueltas que se ajustan a los esquemas de éxito definidos. Estas plantillas de éxito admiten el uso de macros. Para más información, ver Macros de velocidad para acciones de datos.
Respuestas crudas
Cuando se ejecuta una acción para las integraciones de acciones de datos, la respuesta completa se denomina respuesta sin procesar. Sin embargo, las respuestas sin procesar no coinciden necesariamente con el formato definido en el esquema de éxito para una acción. Si la respuesta sin procesar no coincide, puede usar mapas de traducción y plantillas de éxito para reformatear los datos.
Mapas de traducción
Los mapas de traducción contienen pares clave-valor que asignan nombres de propiedad a los valores (u objetos) devueltos a partir de la evaluación de las expresiones JSONPath.
Valores predeterminados del mapa de traducción
Los valores predeterminados del mapa de traducción contienen pares clave-valor que establecen las claves del mapa de traducción en un valor predeterminado. El valor predeterminado se usa si la expresión JSONPath configurada en el mapa de traducción no resuelve un valor. Los valores nulos no vuelven a los valores predeterminados.
Plantillas de éxito
Las plantillas de éxito utilizan la notación variable del lenguaje de plantillas de Velocity. Las plantillas correctas utilizan el nombre de propiedad de los mapas de traducción para insertar datos devueltos por las expresiones JSONPath. En general, todos los datos de las plantillas correctas se tratan como literales en la salida. Elementos dentro de ${} son referencias a valores del mapa de traducción. Para más información, ver El proyecto Apache Velocity documentación.
Respuestas resueltas
Las plantillas de éxito crean respuestas resueltas que deben ajustarse a los esquemas de éxito. De lo contrario, se producirán errores.
Esquemas de éxito
Los esquemas de éxito definen el formato requerido de la respuesta de una acción.
Casos de uso
A menudo, desea utilizar un mapa de traducción y una plantilla de éxito para convertir respuestas sin procesar en las siguientes situaciones:
- Tu respuesta sin procesar contiene varios objetos. Se deben devolver varios objetos como miembros de otro objeto para que la salida resuelta coincida con el esquema de éxito.
- Su respuesta sin procesar contiene valores o tipos de conversión, como matrices, que desea traducir a valores discretos.
- Solo desea devolver un subconjunto específico de datos.
- Quiere garantizar el orden de los atributos devueltos.
Si la respuesta del tercero coincide con el esquema de éxito, entonces desea devolver la respuesta sin procesar sin ninguna manipulación. En este caso, utilice la plantilla de solicitud predeterminada. Si no se proporciona ningún otro valor, la plantilla de solicitud predeterminada utiliza el rawResult valor de contexto. Luego, la plantilla de éxito pasa todo el resultado sin utilizar un mapa de traducción para extraer valores.
${rawResult}
Ejemplo de acción GetContactByPhoneNumber de Salesforce
Respuesta cruda
A continuación, se muestra un ejemplo de respuesta sin procesar de Salesforce cuando se ejecuta la acción Salesforce GetContactByPhoneNumber.
{
"searchRecords": [
{
"attributes": {
"type": "Contact",
"url": "/services/data/v37.0/sobjects/Contact/003G000001LrjlTIAR"
},
"Email": null,
"FirstName": "Jack",
"HomePhone": null,
"Phone": "(317) 555-0123",
"Id": "003G000001LrjlTIAR",
"LastName": "Teller",
"MobilePhone": null,
"OtherPhone": null,
"MailingStreet": null,
"MailingCity": null,
"MailingState": null,
"MailingCountry": null,
"MailingPostalCode": null
}
]
}La respuesta sin procesar contiene un nodo raíz (searchRecords). El objeto searchRecords representa la información de contacto devuelta por Salesforce.
Mapa de traducción
El mapa de traducción extrae segmentos de datos de la respuesta sin procesar. En este caso, queremos extraer todo el nodo searchRecords.
- Los nombres de propiedad en el mapa de traducción deben comenzar con una letra (az, AZ) y solo contener letras, números (0-9), guiones (-) o guiones bajos (_).
- Si el nombre de su valor contiene un espacio, agregue corchetes y comillas simples alrededor del nombre, por ejemplo "contacto": "$. ['Buscar registros']".
"translationMap": {
"contact": "$.searchRecords"
}La expresión JSONPath $ .searchRecords extrae el objeto searchRecords de la respuesta sin procesar y le asigna el alias "contacto". La plantilla de éxito usa el alias.
Plantilla de éxito
La plantilla de éxito hace referencia al alias "contacto" que se creó en el mapa de traducción. El alias apunta a un objeto en la respuesta sin procesar que contiene todos los valores necesarios para coincidir con el esquema de éxito.
${contact}
Respuesta resuelta
La plantilla de éxito crea una respuesta resuelta para la acción. La respuesta resuelta es la respuesta que devuelve la acción.
[
{
"attributes": {
"type": "Contact",
"url": "/services/data/v37.0/sobjects/Contact/003G000001LrjlTIAR"
},
"Email": null,
"FirstName": "Jack",
"HomePhone": null,
"Phone": "(317) 555-0123",
"Id": "003G000001LrjlTIAR",
"LastName": "Teller",
"MobilePhone": null,
"OtherPhone": null,
"MailingStreet": null,
"MailingCity": null,
"MailingState": null,
"MailingCountry": null,
"MailingPostalCode": null
}
] Acción de ejemplo para usar con un proveedor de pagos
Respuesta cruda
El siguiente es un ejemplo de respuesta sin procesar con una acción cuando cargamos una tarjeta de crédito.
{
"id": "ch_1AS7Iv2eZvKYlo2CmgEX0bHw",
"object": "charge",
"amount": 999,
"amount_refunded": 0,
"application": null,
"application_fee": null,
"balance_transaction": "txn_1AS7Iv2eZvKYlo2CjrARHR6C",
"captured": true,
"created": 1496854005,
"currency": "usd",
"customer": "cus_AFEwvtMn3H17af",
"description": null,
"destination": null,
"dispute": null,
"failure_code": null,
"failure_message": null,
"fraud_details": {
},
"invoice": "in_1AS6Mf2eZvKYlo2C9QEibbxz",
"livemode": false,
"metadata": {
},
"on_behalf_of": null,
"order": null,
"outcome": {
"network_status": "approved_by_network",
"reason": null,
"risk_level": "normal",
"seller_message": "Payment complete.",
"type": "authorized"
},
"paid": true,
"receipt_email": null,
"receipt_number": null,
"refunded": false,
"refunds": {
"object": "list",
"data": [
],
"has_more": false,
"total_count": 0,
"url": "/v1/charges/ch_1AS7Iv2eZvKYlo2CmgEX0bHw/refunds"
},
"review": null,
"shipping": null,
"source": {
"id": "card_19ukSY2eZvKYlo2CHlYUs1DM",
"object": "card",
"address_city": null,
"address_country": null,
"address_line1": null,
"address_line1_check": null,
"address_line2": null,
"address_state": null,
"address_zip": "94301",
"address_zip_check": "pass",
"brand": "Visa",
"country": "US",
"customer": "cus_AFEwvtMn3H17af",
"cvc_check": null,
"dynamic_last4": null,
"exp_month": 12,
"exp_year": 2018,
"fingerprint": "Xt5EWLLDS7FJjR1c",
"funding": "credit",
"last4": "4242",
"metadata": {
},
"name": null,
"tokenization_method": null
},
"source_transfer": null,
"statement_descriptor": null,
"status": "succeeded",
"transfer_group": null
}
Mapa de traducción
El mapa de traducción extrae segmentos de datos de la respuesta sin procesar. En este caso, queremos extraer cuatro campos de la respuesta sin procesar.
"translationMap": {
"idValue": "$.id",
"paidValue": "$.paid",
"outcomeValue": "$.outcome",
"sourceValue": "$.source"
}
Las expresiones JSONPath $ .id, $ .pagado, $ .outcome, y $ .fuente extraer los valores de la respuesta sin procesar y asignarlos a los alias idValue, pagadoValor, resultValue, y sourceValue. Los valores predeterminados del mapa de traducción establecen el valor predeterminado para sourceValue. La plantilla de éxito utiliza todos estos alias.
Valores predeterminados del mapa de traducción
Los valores predeterminados del mapa de traducción establecen las claves en el mapa de traducción a los valores predeterminados. En este caso, la respuesta no incluía una propiedad de origen, por lo que establecimos sourceValue al valor predeterminado "DESCONOCIDO".
"translationMapDefaults": {
"sourceValue": "\"UNKNOWN\""
}
Las respuestas de los proveedores de pago pueden incluir o no la propiedad de origen en el mapa de traducción. Para asegurarnos de que usamos la propiedad fuente si la respuesta la incluye y no arrojamos un error si la respuesta no la incluye, establezca sourceValue en el mapa de traducción por defecto "DESCONOCIDO".
Si las respuestas no incluyen ningún otro campo en el mapa de traducción, la acción falla.
Plantilla de éxito
La plantilla de éxito crea una respuesta JSON válida, que hace referencia a los alias idValue, pagadoValor, y resultValue que se crearon en el mapa de traducción. Los alias apuntan a valores en la respuesta sin procesar que son necesarios para coincidir con el esquema de éxito.
{
"id": ${idValue},
"outcome": ${outcomeValue},
"paid": ${paidValue},
"source": ${sourceValue}
}
Respuesta resuelta
La plantilla de éxito crea una respuesta resuelta para la acción. La respuesta resuelta es la respuesta que devuelve la acción.
{
"id": "ch_1AS7Iv2eZvKYlo2CmgEX0bHw",
"outcome": {
"network_status": "approved_by_network",
"reason": null,
"risk_level": "normal",
"seller_message": "Payment complete.",
"type": "authorized"
},
"paid": true,
"source": "UNKNOWN"
}
Para obtener información sobre la configuración en acciones personalizadas, consulte Agregar configuración y Modificar configuración.
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.
