Déclencheur REST API

Rversion finale: Yokohama

Mis à jour 30 janv. 2025

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 de 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 vous 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 Studio de workflow 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 Studio de workflow une API. Reportez-vous à Accès API à Studio de workflow et Créer des extraits de code pour les flux, les sous-flux et les actions.
ServiceNow s’est associé Boomi à pour proposer Boomi API Management, une plateforme basée sur le cloud qui permet aux clients de découvrir, gérer, sécuriser et monétiser leurs API. Boomi prend en charge la gestion complète du cycle de vie des API, y compris la gouvernance, l’analyse et la sécurité des API.

Boomi fournit de la documentation via son propre portail, et les clients qui demandent de l’aide Boomi API Management peuvent contacter l’assistance Boomi via leurs canaux standard.

Pour commencer, consultez la Boomi API Management liste sur le ServiceNow® Store, qui comprend des informations sur les autorisations et les modules d’extension requis, ainsi qu’un lien vers le Boomi API Management interne.

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: Objet contenant des paramètres de chemin d’accès dans la demande entrante.
Paramètres de requêtes: Objet contenant des paramètres de requête dans la demande entrante.
en-têtes de demandes: 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 plus d’informations sur les objets complexes, reportez-vous à la section 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 commence lorsqu’un système tiers envoie une demande REST à votre instance.

Avant de commencer

Rôle requis : flow_designer ou administrateur.

Cette fonctionnalité nécessite un Hub d'intégration abonnement. Pour plus d’informations, consultez Calendriers juridiques - Vue d’ensemble du Centre d’intégration.

Procédure

Ouvrir Studio de workflow et créer un flux.

Voir Création d’un flux.

Gardez à l’esprit que le périmètre de votre flux est inclus dans le point de terminaison REST que vous créez.
Dans la section TRIGGER , sélectionnez REST API - Déclencheur asynchrone .
Dans le champ Méthode HTTP , définissez la méthode HTTP pour le point de terminaison.
Les options incluent :
- POST
- GET
- DELETE
- PUT
- PATCH
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 d’accès .
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 d’accès lors de la configuration du point de terminaison de 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 dans l’entrée vide du champ Chemin d’accès .
  
  Ce champ accepte uniquement les pastilles de données de la section Paramètres de chemin d’accès .
Sélectionnez Authentification requise pour exiger des en-têtes d’authentification dans la demande REST entrante.
Si l’option Requiert l’authentification est sélectionnée, ajoutez les rôles requis pour autoriser la demande dans le champ Requiert des rôles .
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, consultez Données complexes.

Remarque :
La section Contenu de la demande n’apparaît que 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 de ticket provenant d’un système de suivi de ticket tiers.
Dans le champ En-têtes, définissez les en-têtes à envoyer dans la demande entrante.
Vous pouvez sélectionner Obligatoire pour exiger que la demande entrante les inclue.
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 Obligatoire pour exiger que la demande entrante les inclue.
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 d’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.
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.

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/snc/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 le résultat et accédez à l’onglet Exécutions dans Concepteur de flux. Vous pouvez filtrer par ID d’exécution pour localiser les détails de l’exécution et afficher l’état de l’exécution.

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