Déclencheur de REST API

  • Rversion finale: Washingtondc
  • Mis à jour 1 févr. 2024
  • 5 minutes de lecture

    • Démarrez un flux à partir d’un appel d’API entrant ou d’un webhook à partir d’un système externe. Configurez les conditions de démarrage du déclencheur sans avoir à écrire ou à gérer du code personnalisé.

    Par exemple, vous pouvez créer un flux qui commence lorsqu’un système de suivi des tickets informatiques tiers envoie une demande entrante à l’instance. Vous pouvez ensuite analyser les données de la demande REST entrante dans un objet de données complexe et utiliser les valeurs pour ouvrir un incident sur votre instance.

    Une fois que vous avez activé le flux, le point de terminaison que vous avez créé apparaît dans l’explorateur d’API sous l’espace de noms que vous avez créé. Vous pouvez utiliser cette page pour aider à définir le webhook dans votre système tiers et pour tester votre flux.

    Pour en savoir plus sur les déclencheurs de flux, consultez Concepteur de flux Types de déclencheurs.

    Remarque :
    Utilisez le déclencheur d’API REST pour démarrer des flux à partir d’appels REST provenant de systèmes externes. Pour démarrer un flux à partir d’un script ou d’un appel d’API à partir de la même instance, utilisez un flux secondaire, un extrait de code ou Concepteur de flux une API. Reportez-vous à Accès API à Concepteur de flux et Créer des extraits de code pour les flux, les flux secondaires et les actions.

    Pastilles de données disponibles

    Selon la façon dont vous configurez le point de terminaison, les concepteurs de flux ont accès à ces pastilles de données à partir du déclencheur :

    Paramètres de chemin d'accès
    Un objet contenant les paramètres de chemin dans la demande entrante.
    Paramètres de requêtes
    Un objet contenant les paramètres de requête dans la demande entrante.
    En-têtes de demandes
    Un objet contenant des en-têtes dans la demande entrante.
    Corps de la demande
    Objet de données complexe qui définit la structure du corps de la demande entrante. Pour en savoir plus sur les objets complexes, reportez-vous à la rubrique Complex data.

    Lors de la configuration du déclencheur, définissez à quoi ressembleront les données entrantes. Vous pouvez ensuite utiliser les pastilles de données associées dans les actions de votre flux. Lorsque le système reçoit une demande entrante qui démarre le flux, il utilise les valeurs d’exécution envoyées dans la demande.

    Créer un flux à l’aide du déclencheur d’API REST

    Créez un flux qui démarre lorsqu’un système tiers envoie une demande REST à votre instance.

    Avant de commencer

    Rôle requis : flow_designer ou admin.

    Remarque :
    Cette fonctionnalité nécessite un abonnement à Hub d'intégration Entreprise. Pour plus d'informations, consultez Demander le Hub d'intégration.

    Procédure

    1. Ouvrez Concepteur de flux et créez un flux.

      Reportez-vous à la section Créer un flux.

      Gardez à l’esprit que le champ d’application de votre flux est inclus dans le point de terminaison REST que vous créez.

    2. Dans la section TRIGGER , sélectionnez REST API - Déclencheur asynchrone .
    3. Dans le champ Méthode HTTP , définissez la méthode HTTP pour le point de terminaison.
      Les options incluent :
      • POST
      • GET
      • DELETE
      • PUT
      • CORRECTIF
    4. Créez tous les paramètres de chemin d’accès requis pour le point de terminaison et ajoutez-les au chemin d’accès relatif dans le champ Chemin .
      Le chemin d’accès relatif au point de terminaison est au format /api/<flow-application-scope>/<flow-name>/<path-parameters>.

      Vous pouvez cliquer sur Copier pour copier le chemin d’accès complet au point de terminaison. Utilisez ce chemin lors de la configuration du point de terminaison pour l’appel REST dans votre système tiers.

      1. Créez des variables dans la section Paramètres de chemin .
      2. Faites glisser la pastille de données qui représente le paramètre de chemin d’accès vers l’entrée vide du champ Chemin d’accès .

        Ce champ n’accepte que les pastilles de données de la section Paramètres de chemin.

    5. Sélectionnez Requiert une authentification pour exiger des en-têtes d’authentification dans la demande REST entrante.
    6. Si l’option Authentification obligatoire est sélectionnée, ajoutez les rôles requis pour autoriser la demande dans le champ Requiert des rôles .
    7. Dans le champ Corps de la section Contenu de la demande , créez un objet de données complexe qui définit la structure du corps de la demande entrante.

      Pour plus d’informations sur la création d’un objet complexe, reportez-vous à la rubrique Données complexes.

      Remarque :
      La section Contenu de la demande s’affiche uniquement lorsque la méthode HTTP est POST, PUT ou PATCH.

      Cet exemple de corps trouve le champ Description dans une charge utile entrante qui contient des informations sur les tickets provenant d’un système de suivi des tickets tiers.

    8. Dans le champ En-têtes , définissez les en-têtes à envoyer dans la demande entrante.
      Vous pouvez sélectionner Requis pour exiger que la demande entrante les inclue.
    9. Dans le champ Paramètres de requête , définissez les paramètres de requête à envoyer dans la demande entrante.
      Vous pouvez sélectionner Requis pour exiger que la demande entrante les inclue.
    10. Ajoutez des actions à votre flux qui s’exécutent lorsque le point de terminaison est appelé.

      Vous pouvez utiliser les pastilles de données du déclencheur de l’API REST dans vos actions de flux.

      Cette action crée un enregistrement d’incident et mappe les champs Description et Groupe d’affectation de la charge utile entrante à l’incident.

    11. Testez et activez le flux.
      Pour plus d’informations, consultez Tester un flux et Activer un flux.

      Une fois activé, le point de terminaison s’affiche dans l’explorateur d’API REST. Vous pouvez utiliser cette page pour tester davantage votre point de terminaison ou configurer la demande à partir de votre système tiers.

    12. Configurez la demande REST à partir de votre système tiers.
      Par exemple, vous pouvez envoyer cette demande cURL pour déclencher le flux défini dans les étapes précédentes.
      curl "https:your-instance.servicenow.com/api/now/create_incident_from_external_event/assignment_group/287ebd7da9fe198100f92cc8d1d2154e" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
fields: {
   description: \"Major outage with data loss\"
   }
}" \
--user 'username':'password'

    Résultats

    Le flux s’exécute et la demande REST renvoie l’ID d’exécution.
    {
  "result": {
    "executionId": "ndoxeRhshDSezldeGfbYlviFSeFnBjCO"
  }
}

    Que faire ensuite

    Copiez l’ID d’exécution dans les résultats et accédez à l’onglet Exécutions dans Flow Designer. Vous pouvez filtrer par ID d’exécution pour localiser les détails de l’exécution et afficher l’état de celle-ci.

    Pour résoudre les problèmes, vous pouvez déboguer la requête REST ou vérifier les détails de l’exécution du flux. Consultez Déboguer les requêtes REST et les détails de l’exécution du flux.