Bonnes pratiques : formes d'objet

Suivez les bonnes pratiques recommandées pour l'utilisation d'objets dans les cartes d'action.

Évitez de concevoir une carte d'action qui nécessite un objet JSON comme valeur d'entrée, et il est préférable de ne pas ajouter de champs de résultat qui renvoient des objets uniques. Si un champ de résultat ne renvoie qu'un seul objet à la fois et que les clés de l'objet sont connues, ajoutez alors un ensemble de champs de résultat pour renvoyer chacune des valeurs de l'objet. Sinon, vous obligerez probablement un utilisateur de la carte d'action à implémenter des cartes supplémentaires dans son flux pour analyser l'objet JSON renvoyé par la carte d'action.

Voici un exemple d'objet renvoyé par une API :

{
  "user": {
    "name": {
      "first": "Bill",
      "last": "Lumbergh"
    },
    "email": "bill@initech.net",
    "address": {
      "street1": "123 Corporate Drive",
      "street2": "Suite 45",
      "city": "Middle",
      "state": "TX",
      "zip": "67890",
      "country": "US"
    }
  }
}

Il est recommandé de renvoyer ces attributs imbriqués en tant que champs de premier niveau en utilisant des en-têtes pour les regrouper.

[
  {
    "name": "User",
    "attributes": [
      {
        "name": "First Name",
        "type": "string"
      },
      {
        "name": "Last Name",
        "type": "string"
      },
      {
        "name": "Email",
        "type": "string"
      }
    ]
  },
  {
    "name": "Address",
    "attributes": [
      {
        "name": "Street 1",
        "type": "string"
      },
      {
        "name": "Street 2",
        "type": "string"
      },
      {
        "name": "City",
        "type": "string"
      },
      {
        "name": "State",
        "type": "string"
      },
      {
        "name": "Zipcode",
        "type": "string"
      },
      {
        "name": "Country",
        "type": "string"
      }
    ]
  }
]

L'utilisation d'objets en tant que sorties est courante lorsqu'une carte d'action renvoie une collection d'éléments, comme une liste d'enregistrements provenant d'une app de collaboration ou de billetterie. Dans un tel objet, veillez à inclure un schéma pour les attributs de cet objet. Faites en sorte que la structure de l'objet soit aussi plate que possible afin de réduire le risque que d'autres cartes d'action ne doivent lire des données à partir du même point de terminaison de l'API.

[
  {
    "name": "Result",
    "attributes": [
      {
        "name": "Tags",
        "type": "object",
        "collection": true,
        "attributes": [
          {
            "name": "Tag Name",
            "type": "string"
          },
          {
            "name": "Tag ID",
            "type": "string"
          },
          {
            "name": "Tag Color",
            "type": "string"
          }
        ]
      }
    ]
  }
]