Configuración de respuesta para acciones de datos

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

Puede crear acciones personalizadas para las integraciones de acciones de datos. Una acción personalizada incluye una solicitud y un respuesta en su configuración. Para obtener más información, consulte Crear 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 las 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 obtener más información, consulte Macros Velocity para acciones de datos.

Respuestas sin procesar

Cuando se ejecuta una acción para las integraciones de acciones de datos, se denomina respuesta toda la bruta respuesta. Sin embargo, las respuestas sin procesar no coinciden necesariamente con el formato definido en el esquema de éxito para una acción. Si la raw respuesta no coincide, puede utilizar mapas de traducción y plantillas de éxito para reformatear los datos.

Nota: Las funciones de Google Cloud devuelven un JSON respuesta stringificado que las acciones se convierten en JSON antes de procesar mapas de traducción.

Mapas de traducción

Los mapas de traducción contienen pares de valor clave que asignan nombres de propiedad a los valores devueltos (o objeto) de la evaluación de expresiones JSONPath.

Valores predeterminados del mapa de traducción

Los valores predeterminados de mapas de traducción contienen pares de valor clave que establecen claves de mapa de traducción a un valor por opción predeterminada. El valor por opción predeterminada se utiliza si la expresión de JSONPath configurada en el mapa de traducción no resuelve un valor. Los valores nulos no se vuelven a caer a los valores predeterminados.

Plantillas de éxito

Las plantillas de éxito utilizan la anotación variable del idioma de la plantilla de Velocity. Las plantillas de éxito utilizan el nombre de la propiedad de mapas de traducción para insertar datos devueltos por las expresiones de JSONPath. En general, todos los datos de las plantillas de éxito se tratan como literals en la salida. Los artículos de ${} son referencias a los valores del mapa de traducción. Para obtener más información, consulte 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, los errores resulten.

Esquema de éxito

Los esquemas de éxito definen el formato requerido de una acción respuesta. 

Casos de uso

A menudo, desea utilizar un mapa de traducción y una plantilla de éxito para convertir las respuestas sin procesar en las siguientes situaciones:

  • Su raw respuesta 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 raw respuesta contiene valores o tipos de conversión, como arrays, que desea traducir a valores discretos.
  • Solo desea devolver un subconjunto específico de datos.
  • Desea garantizar el orden de los atributos devueltos.

Si el respuesta del tercer-persona coincide con el esquema de éxito, entonces desea devolver la raw respuesta sin manipulación. En este caso, utilice la plantilla de solicitud por opción predeterminada. Si no se proporciona ningún otro valor, la plantilla de solicitud predeterminado utiliza el rawResultado valor de contexto. La plantilla de éxito pasa el resultado completo sin usar un mapa de traducción para extraer valores.

${rawResult}

Ejemplo Salesforce Acción de GetContactByPhonEnumber

Sin procesar respuesta

El siguiente es un ejemplo sin procesar respuesta desde 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 raw respuesta contiene un nodo raíz (searchRecords). El objeto Search Records representa la información de contacto que se ha devuelto de Salesforce.

Mapa de traducción

El mapa de traducción extrae segmentos de datos de la raw respuesta. En este caso, queremos extraer todos los registros de búsqueda de nodos. 

Notas
  • Los nombres de las propiedades del mapa de traducción deben comenzar con una letra (a-z, A-Z) y contener solo 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”: “$.[‘Search Records’]”.

"translationMap": {
  "contact": "$.searchRecords"
}

La expresión de JSONPath $.searchRegistros extrae el objeto searchRecords de la raw respuesta y lo asigna el alias “contacto”. La plantilla de éxito utiliza 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 señala un objeto de la bruta respuesta que contiene todos los valores necesarios para coincidir con el esquema de éxito.

${contact}

Resuelto respuesta

La plantilla de éxito crea una resolución respuesta para la acción. La resuelta respuesta 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
    }
]		

Ejemplo de acción para usar con un proveedor de pagos

Sin procesar respuesta

A continuación se muestra un ejemplo sin procesar respuesta con una acción cuando cobramos 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 raw respuesta. En este caso, queremos quitar cuatro campos de la bruta respuesta.

"translationMap": {
  "idValue": "$.id",
  "paidValue": "$.paid",
  "outcomeValue": "$.outcome",
  "sourceValue": "$.source"
}

Expresiones JSONPath ID de $, $.pagado, $.resultado, y $.fuente extraer los valores de la bruta respuesta y asignarlos a los alias Valor de idValor, Valor de pausa, outcomEvaluación, y sourcValor. Los valores predeterminados del mapa de traducción establecen el valor predeterminado para sourcValor. 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 del mapa de traducción a por opción predeterminada valores. En este caso, el respuesta no incluía una propiedad de origen, así que sourcValor al valor predeterminado “DESCONOCIDO”.

"translationMapDefaults": {
  "sourceValue": "\"UNKNOWN\""
}

Las respuestas de los proveedores de pagos pueden incluir o no la propiedad de origen en el mapa de traducción. Para asegurarse de que utilizamos la propiedad de origen si el respuesta lo incluye y no presenta un error si el respuesta no lo incluye, establezca sourcValor en el mapa de traducción predeterminado “DESCONOCIDO”.

Si las respuestas no incluyen otros campos del mapa de traducción, la acción falla.

Plantilla de éxito

La plantilla de éxito crea un JSON válido respuesta, que hace referencia a los alias Valor de idValor, Valor de pausa, y outcomEvaluación que se crearon en el mapa de traducción. Los alias apuntan a valores en la bruta respuesta que se necesitan para coincidir con el esquema de éxito.

{
   "id": ${idValue},
   "outcome": ${outcomeValue},
   "paid": ${paidValue},
   "source": ${sourceValue}
}
Nota: El texto fuera de ${} se trata como literals.

Resuelto respuesta

La plantilla de éxito crea una resolución respuesta para la acción. La resuelta respuesta 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 Añadir configuraciónModificar configuración.

Para obtener más información, consulte Acerca de acciones personalizadas para integraciones.

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