Configuration de la réponse pour les actions de données

Remarque : Cet article s'applique aux intégrations AWS Lambda, Genesys Cloud, Google, Microsoft Dynamics 365, Salesforce, services web et actions de données Zendesk.

Vous pouvez créer des actions personnalisées pour les intégrations d’actions de données. Une action personnalisée inclut une demande et une réponse dans sa configuration. Pour plus d’informations, voir Créer une action personnalisée.

Cet article explique les différentes parties de réponse. Pour plus d’informations sur les demandes, voir Demander une configuration.

Les actions personnalisées utilisent des mappes de traduction et des modèles de réussite pour convertir les réponses brutes de services Web distants ou de votre fonction AWS Lambda en réponses résolues conformes aux schémas de réussite définis. Ces modèles de réussite prennent en charge l’utilisation de macros. Pour plus d’informations, voir Macros Velocity pour les actions de données.

Réponses brutes

Lorsqu'une action s'exécute pour les intégrations d'actions de données, la réponse entière est appelée la réponse brute. Cependant, les réponses brutes ne correspondent pas nécessairement au format défini dans le schéma de réussite d’une action. Si réponse brut ne correspond pas, vous pouvez utiliser des cartes de traduction et des modèles de réussite pour reformater les données.

Remarque : Les fonctions Google Cloud renvoient une réponse JSON sous forme de chaîne que les actions convertissent en JSON avant de traiter les mappages de traduction.

Cartes de traduction

Les cartes de traduction contiennent des paires clé-valeur qui mappent les noms de propriété aux valeurs (ou objets) renvoyées à partir de l’évaluation des expressions JSONPath.

Paramètres de traduction par défaut

Les valeurs par défaut des cartes de traduction contiennent des paires clé-valeur qui définissent les clés de la carte de traduction sur une valeur par défaut. La valeur par défaut est utilisée si l'expression JSONPath configurée dans la carte de traduction ne parvient pas à résoudre une valeur. Les valeurs nulles ne reviennent pas aux valeurs par défaut.

Modèles de réussite

Les modèles de réussite utilisent la notation variable du langage de modèle Velocity. Les modèles de réussite utilisent le nom de propriété des mappes de traduction pour insérer les données renvoyées par les expressions JSONPath. En général, toutes les données des modèles de réussite sont traitées comme des littéraux dans la sortie. Les éléments dans $ {} sont des références aux valeurs de la carte de traduction.{} Pour plus d’informations, consultez Le projet Apache Velocity Documentation.

Réponses résolues

Les modèles de réussite créent des réponses résolues qui doivent être conformes aux schémas de réussite. Sinon, des erreurs en résultent.

Schémas de succès

Les schémas de réussite définissent le format requis pour réponse d’une action.

Cas d’utilisation

Vous souhaitez souvent utiliser une carte de traduction et un modèle de réussite pour convertir les réponses brutes dans les situations suivantes :

Votre réponse brut contient plusieurs objets. Plusieurs objets doivent être renvoyés en tant que membres d’un autre objet pour que la sortie résolue corresponde au schéma de réussite.
Votre réponse brut contient des valeurs ou des types de conversion, tels que des tableaux, que vous souhaitez convertir en valeurs discrètes.
Vous souhaitez uniquement renvoyer un sous-ensemble spécifique de données.
Vous voulez garantir l’ordre des attributs retournés.

Si réponse du troisième prévisualisation du mode de numérotation correspond au schéma de réussite, vous souhaitez renvoyer le brut sans réponse. Dans ce cas, utilisez le modèle de demande par défaut. Si aucune autre valeur n’est fournie, le modèle de demande par défaut utilise le modèle intégré rawResult valeur de contexte. Le modèle de réussite transmet ensuite l’intégralité du résultat sans utiliser de mappage de traduction pour extraire des valeurs.

${rawResult}

Exemple d’action Salesforce GetContactByPhoneNumber

réponse brut

Voici un exemple réponse brut de Salesforce lorsque l’action Salesforce GetContactByPhoneNumber s’exécute.

{
  "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
    }
  ]
}

Le réponse brut contient un nœud racine (searchRecords). L’objet searchRecords représente les informations de contact renvoyées par Salesforce.

Carte de traduction

La carte de traduction extrait des segments de données du fichier brut réponse. Dans ce cas, nous voulons extraire l’intégralité du noeud searchRecords.

Remarques:

Les noms de propriété dans la carte de traduction doivent commencer par une lettre (az, AZ) et ne contenir que des lettres, des chiffres (0 à 9), des traits d’union (-) ou des traits de soulignement (_).
Si le nom de votre valeur contient un espace, ajoutez des crochets et des guillemets simples autour du nom, par exemple « contact» : "$.['Rechercher des enregistrements']".

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

L’expression JSONPath $.searchRecords extrait l’objet searchRecords de la réponse brute et lui affecte l’alias "contact". Le modèle de réussite utilise l’alias.

Modèle de réussite

Le modèle de réussite fait référence à l’alias "contact" qui a été créé dans la carte de traduction. L’alias pointe vers un objet dans la réponse brute qui contient toutes les valeurs nécessaires pour correspondre au schéma de réussite.

${contact}

Résolu réponse

Le modèle de réussite crée une réponse résolue pour l’action. La réponse résolue est la réponse que l’action renvoie.

[
    {
      "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
    }
]

Exemple d’action à utiliser avec un fournisseur de paiement

réponse brut

Voici un exemple de réponse brut avec une action lorsque nous débitons une carte de crédit.

{
  "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
}

Carte de traduction

La carte de traduction extrait des segments de données du fichier brut réponse. Dans ce cas, nous voulons extraire quatre champs du fichier brut réponse.

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

Les expressions JSONPath $.id, $.paid, $.outcome, et $.source extraire les valeurs de la réponse brute et les affecter aux alias idValue, payéValeur, resultValue, et sourceValue. Les valeurs par défaut mappage de traduction définissent la par défaut pour sourceValue. Le modèle de réussite utilise tous ces alias.

Paramètres de traduction par défaut

Les valeurs par défaut de la carte de traduction définissent les clés de la carte de traduction sur les valeurs par défaut. Dans ce cas, la réponse ne comprenait pas de propriété source, nous avons donc défini sourceValue à la par défaut "INCONNUE".

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

Les réponses des fournisseurs de paiement peuvent inclure ou non la propriété source dans la carte de traduction. Pour nous assurer que nous utilisons la propriété source si la réponse inclut et ne lançons pas d’erreur si la réponse ne l’inclut pas, définissez sourceValue dans la carte de traduction par défaut "INCONNUE".

Si les réponses n’incluent aucun autre champ dans la carte de traduction, l’action échoue.

Modèle de réussite

Le modèle de réussite crée une réponse JSON valide, qui fait référence aux alias idValue, payéValeur, et resultValue qui ont été créés dans la carte de traduction. Les alias pointent vers les valeurs brutes réponse nécessaires pour faire correspondre le schéma de réussite.

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

Remarque : Le texte situé en dehors de $ {} est traité comme un littéral.{}

Résolu réponse

Le modèle de réussite crée une réponse résolue pour l’action. La réponse résolue est la réponse que l’action renvoie.

{
   "id": "ch_1AS7Iv2eZvKYlo2CmgEX0bHw",
   "outcome": {
      "network_status": "approved_by_network",
      "reason": null,
      "risk_level": "normal",
      "seller_message": "Payment complete.",
      "type": "authorized"
   },
   "paid": true,
   "source": "UNKNOWN"
}

Pour plus d’informations sur la configuration dans les actions personnalisées, voir Ajouter une configuration et Modifier la configuration.

Pour plus d’informations, voir A propos des actions personnalisées pour les intégrations.

Pour plus d’informations sur l’intégration, voir À propos de l’intégration des actions de données Zendesk.