Créer et configurer un outil

Commencez par la documentation officielle de l'API pour le service commercial et une tâche que votre compte est autorisé à effectuer. Un outil restreint et bien décrit est plus facile à tester qu’un outil générique acceptant une URL et une méthode arbitraires.

Définir la demande#

Donnez à l'outil un nom stable et une description qui explique son objectif, ses limites importantes et s'il modifie les données. Sélectionnez la méthode HTTP et le point de terminaison documentés. Utilisez des espaces réservés uniquement pour les éléments de chemin variable que l'opération autorise réellement.

Pour une recherche d'enregistrement fictif, le chemin peut contenir un identifiant d'enregistrement. Le nom d'hôte et la région du compte doivent rester une partie de la connexion configurée plutôt qu'une entrée de modèle ouverte.

Définir et cartographier les entrées#

Utilisez le schéma d'entrée pour décrire chaque champ, son type, son statut requis et ses valeurs valides. Un petit schéma pour une recherche fictive est :

{
  "type": "object",
  "properties": {
    "record_id": {
      "type": "string",
      "description": "The verified identifier of the record to read"
    }
  },
  "required": ["record_id"],
  "additionalProperties": false
}

Mappez les arguments sur les champs de chemin, de requête ou de corps documentés. Vérifiez que les champs obligatoires manquants et les arguments supplémentaires inattendus échouent clairement. Conservez l'authentification dans la connexion au serveur prise en charge, et non dans une invite, un exemple de schéma ou un en-tête d'outil codé en dur.

Façonner le résultat#

Le mappage ou la transformation des réponses peut renvoyer les champs dont le flux de travail a besoin au lieu d'une réponse de service complète. Vérifiez la sortie transformée par rapport au résultat du test d’origine. Ne supprimez pas l’identifiant de l’enregistrement, les informations de pagination ou les détails d’erreur nécessaires pour comprendre si le résultat est complet.

Vérifier les paramètres de fonctionnement#

La configuration de l'outil prend en charge les paramètres de délai d'attente, de mise en cache et de nouvelle tentative. Utilisez la mise en cache uniquement lorsque des données obsolètes sont acceptables ; une lecture en cache ne convient pas comme preuve finale qu'une écriture vient de se terminer. Réessayer une écriture non idempotente peut créer des doublons, choisissez donc le comportement de nouvelle tentative parmi les garanties documentées de l'API.

Testez le vrai chemin#

Vérifiez l'entrée correcte, l'entrée invalide, les résultats vides, l'échec de l'autorisation et un appel réussi limité. Les diagnostics de test peuvent contenir des informations de demande sensibles ; inspectez-les uniquement via la voie de l’administrateur approuvé et expurgez-les avant de les partager. Voir test avant qu'un client utilise l'outil.