Étape REST
Envoyez une demande de service Web REST sortante à un système externe.
Le service Web REST sortant est une fonctionnalité de plateforme qui vous permet de récupérer, créer, mettre à jour ou supprimer des données sur un serveur de services Web qui prend en charge l’architecture REST.
Rôles et disponibilité
Disponible en tant qu’étape d’action Studio de workflow . Les utilisateurs disposant du rôle action_designer peuvent créer une action personnalisée avec une ou plusieurs étapes d’action.
Champs
| Champ | Description |
|---|---|
| Connexion | Type de connexion à utiliser.
Pour en savoir plus sur les connexions et les informations d’identification, consultez Présentation des informations d’identification, des connexions et des alias. |
| Alias de connexion | Enregistrement d’alias de connexion et d’informations d’identification que le système utilise pour exécuter l’étape d’action. Les utilisateurs disposant du rôle flow_designer ou admin peuvent créer ou sélectionner un enregistrement de connexion associé. L'utilisation d'un alias élimine la nécessité de configurer plusieurs informations d'identification et profils d'informations de connexion lors de l'utilisation d'une action dans plusieurs environnements. De même, si les informations de connexion changent, vous n’avez pas besoin de mettre à jour votre action personnalisée. Pour en savoir plus sur les connexions et les informations d’identification , consultez Informations d’identification, connexions et alias. La valeur d’informations d’identification s’affiche sous la forme d’une pastille de données de mot de passe (2 sens cryptés) sur le panneau de données. Remarque : Ce champ est disponible lorsque l’option Utiliser l’alias de connexion est sélectionnée dans la liste Connexion. |
| Alias d’informations d’identification | Alias d’informations d’identification utilisé par le système pour exécuter l’étape d’action. Les utilisateurs disposant du rôle flow_designer ou admin peuvent créer ou sélectionner un enregistrement de connexion associé. L’utilisation d’un alias élimine la nécessité de configurer plusieurs informations d’identification lors de l’utilisation d’une action dans plusieurs environnements. De même, si les informations d’identification changent, vous n’avez pas besoin de mettre à jour votre action personnalisée. Pour en savoir plus sur les connexions et les informations d’identification , consultez Informations d’identification, connexions et alias. La valeur d’informations d’identification s’affiche sous la forme d’une pastille de données de mot de passe (2 sens cryptés) sur le panneau de données. Remarque : Ce champ est disponible lorsque l’option Définir l’inline de la connexion est sélectionnée dans la liste Connexion. |
| Utiliser MID | Option permettant d’utiliser un ServiceNow® Serveur MID pour exécuter le Étape RESTfichier . Cochez cette case pour afficher les champs Application MID et Options . Remarque : Le système ne consigne pas les données d’exécution de la demande, de la réponse et des paramètres REST envoyées via un MID Server de la même manière que la journalisation des services Web sortants . Au lieu de cela, vous pouvez afficher ces données dans les détails d’exécution du flux. |
| URL de base | URL de base de la demande REST.
|
| Tester l'étape REST | Bouton permettant de tester l’étape REST. Pour tester, sélectionnez le bouton Tester l’étape REST . Entrez les valeurs d’entrée requises et sélectionnez le bouton Exécuter le test . Une fois le test exécuté, les sorties d’étape ou les messages d’erreur s’affichent dans la section Résultats des tests de la fenêtre de test. |
| Délai de connexion | Nombre de millisecondes pendant lesquelles le système attend une connexion de l'hôte réussie. Si l’étape n’aboutit pas à une connexion pendant ce temps, la demande de connexion expire. Si Définir l’inline de la connexion est sélectionné, entrez une valeur de délai d’expiration pour la connexion. Laissez ce champ vide pour utiliser la valeur de délai de connexion par défaut du système. |
| Sélection de MID |
Option permettant de sélectionner le serveur MID ou la grappe MID spécifique.
|
| Application MID | Capacités que le doit prendre en charge pour être éligible à la Serveur MID sélection. Le système exécute l’étape d’action à partir d’un Serveur MID qui prend en charge les options sélectionnées. Ce champ est disponible lorsque l’option Définir l’inline de la connexion est sélectionnée dans la liste Connexion, que la case Utiliser MID est cochée et que l’option Sélectionner automatiquement Serveur MID est sélectionnée dans la liste Sélection MID. |
| Aptitudes | Capacités que le doit prendre en charge pour être éligible à la Serveur MID sélection. Le système exécute l’étape d’action à partir d’un Serveur MID qui prend en charge les options sélectionnées. Ce champ est disponible lorsque l’option Définir l’inline de la connexion est sélectionnée dans la liste Connexion, que la case Utiliser MID est cochée et que l’option Sélectionner automatiquement Serveur MID est sélectionnée dans la liste Sélection MID. |
| Serveur MID | Pilule de données de l’espace requis Serveur MID. Ce champ est disponible lorsque l’option Définir l’inline de la connexion est sélectionnée dans la liste Connexion, que la case Utiliser MID est cochée et que Serveur MID spécifique est sélectionné dans la liste Sélection MID. |
| Grappe MID | Pilule de données pour la grappe MID que vous souhaitez utiliser. Ce champ est disponible lorsque l’option Définir l’inline de la connexion est sélectionnée dans la liste Connexion, que l’option Utiliser MID est cochée et que l’option Grappe MID spécifique est sélectionnée dans la liste Sélection MID. |
| Demande de version | Option permettant de créer la demande manuellement, d’importer une spécification OpenAPI ou d’importer un message REST.
|
| Source de l'API | Option permettant de sélectionner une spécification OpenAPI utilisée pour construire la demande, ou de sélectionner Importer OpenAPI pour importer une nouvelle spécification OpenAPI. Vous pouvez importer des spécifications en fournissant une URL vers le YAML ou le JSON, ou en copiant et collant du contenu. Remarque : Ce champ est disponible lorsque vous sélectionnez À partir de la spécification OpenAPI dans la liste Demande de version. |
| Opération API | Option permettant de sélectionner une opération dans la liste. Les opérations disponibles sont fournies par la spécification OpenAPI dans le champ Source de l’API . Remarque : Ce champ est disponible lorsque vous sélectionnez À partir de la spécification OpenAPI dans la liste Demande de version. |
| Message REST | Nom du message REST à importer. Sélectionnez un message REST dans la liste. Remarque : Ce champ est disponible lorsque vous sélectionnez À partir du message REST dans la liste Demande de version. |
| Fonction de message REST | Nom de la fonction à partir de laquelle importer le message REST. Les options disponibles sont déterminées par les méthodes HTTP associées au message REST sélectionné. Remarque : Ce champ est disponible lorsque vous sélectionnez À partir du message REST dans la liste Demande de version. |
| Importer le message REST | Bouton permettant d’importer le message REST. Remarque : Ce champ est disponible lorsque vous sélectionnez un message REST dans le champ Message REST . |
| Chemin d'accès à la ressource | Chemin d’accès de la ressource. |
| Fonction de message REST | Méthode HTTP utilisée pour traiter la demande.
|
| Paramètres de requêtes | Paires nom-valeur à transmettre au point de terminaison REST. Vous pouvez créer ces paramètres manuellement ou faire glisser les variables d’entrée dans les champs de paramètres, puis affecter une valeur. Prenez en charge les demandes d’étape REST qui contiennent des noms de paramètres de requête en double. Si vous créez une demande REST contenant des noms de paramètres de requête en double, Studio de workflow ajoute les paramètres de requête à la demande dans le même ordre que vous les avez définis. Remarque : lors de l'importation d'une spécification OpenAPI, le système ajoute tous les paramètres et en-têtes présents dans la spécification à l'étape REST. Passez en revue les valeurs de l'étape REST finale et supprimez les paramètres que vous ne souhaitez pas envoyer dans la demande. Par exemple, si l'API accepte les en-têtes de type de contenu pour les formats JSON et XML, le système ajoute les deux en-têtes à l'étape REST. Supprimez l'un des en-têtes en fonction du type de contenu que vous souhaitez recevoir dans la réponse. |
| En-têtes | En-têtes à envoyer avec la demande. Vous pouvez créer des en-têtes manuellement ou faire glisser des variables d’entrée dans les champs de paramètres, puis affecter une valeur. Prendre en charge les demandes d’étape REST qui contiennent des en-têtes de demande en double. Si vous créez une demande REST contenant des en-têtes de demande en double, les en-têtes sont envoyés dans le même ordre que vous les avez définis. Remarque : lors de l'importation d'une spécification OpenAPI, le système ajoute tous les paramètres et en-têtes présents dans la spécification à l'étape REST. Passez en revue les valeurs de l'étape REST finale et supprimez les paramètres que vous ne souhaitez pas envoyer dans la demande. Par exemple, si l'API accepte les en-têtes de type de contenu pour les formats JSON et XML, le système ajoute les deux en-têtes à l'étape REST. Supprimez l'un des en-têtes en fonction du type de contenu que vous souhaitez recevoir dans la réponse. |
| Type de demande | Format de la demande. Les options comprennent.
Remarque : Ce champ est modifiable lorsque la méthode HTTP est POST,PUT, PATCH ou DELETE. |
| Corps de la demande [texte] | Corps de la demande au format JSON ou XML. Les détails d’exécution du flux affichent le corps de la réponse sous la forme d’un lien vers la visionneuse de texte incorporé ou de sys_id de l’enregistrement de pièce jointe contenant la réponse. Remarque : Ce champ est modifiable si vous sélectionnez Texte dans la liste Type de demande. |
| Pièce jointe | Enregistrement de la pièce jointe qui contient la demande. Vous pouvez rechercher ou créer cet enregistrement dans une étape antérieure et le définir comme variable d’entrée. Créez-le à l’aide des API JSONStreamingBuilder et XMLStreamingBuilder dans l’étape Script. Remarque : Ce champ est disponible lorsque vous sélectionnez Binaire dans la liste Type de demande. |
| Nom, type de pièce, valeur | Contenu d’une demande en plusieurs parties. Pour chaque article, spécifiez son nom, son type de pièce et sa valeur soit à l’aide des champs individuellement, soit à l’aide d’un script en ligne pour toutes les pièces. Vous pouvez spécifier les valeurs en plusieurs parties en cliquant sur l’icône Activer/désactiver les scripts (icône
Remarque : Ces champs sont disponibles lorsque vous sélectionnez Plusieurs parties dans la liste Type de demande. |
| Nom, valeur | Contenu d’une demande codée par l’URL d’un formulaire. Spécifiez chaque partie de la demande codée URL avec une paire nom-valeur à l’aide des champs individuellement ou à l’aide d’un script en ligne pour toutes les parties. Vous pouvez spécifier le script inline des valeurs codées par l’URL du formulaire en cliquant sur l’icône Activer/désactiver le script (icône  ) et en modifiant le script. Pour plus d’informations sur le scripting en ligne, reportez-vous à Scripts alignés.Remarque : Ce champ est disponible lorsque vous sélectionnez Codage URL de formulaire dans la liste Type de demande. |
| Activer la politique des nouveaux essais | Option permettant d'activer la politique des nouveaux essais. Pour plus d'informations, reportez-vous à Politique des nouveaux essais. |
| Remplacer la politique des nouveaux essais pour l’alias | Option permettant de remplacer la politique des nouveaux essais par défaut. Cette case à cocher n'est pas disponible si l'option Définir l'inline de la connexion est sélectionnée dans la liste des connexions. |
| Politique des nouveaux essais | Politique des nouveaux essais par défaut associée à l'alias de connexion. Si l'option Remplacer la politique des nouveaux essais pour l'alias est sélectionnée, vous pouvez remplacer la politique des nouveaux essais par défaut et sélectionner une autre politique existante des nouveaux essais en fonction de vos besoins. |
| Enregistrer en tant que pièce jointe | Option permettant de spécifier s’il faut enregistrer la réponse en tant qu’enregistrement dans la table Pièce jointe [sys_attachment]. |
| Nom de fichier de la pièce jointe | Nom de la pièce jointe créée par la réponse REST. Par exemple, rest-response.txt. Remarque : Ce champ est disponible lorsque l’option Enregistrer en tant que pièce jointe est sélectionnée. |
| Enregistrement du fichier de la pièce jointe | Enregistrement cible auquel la pièce jointe est associée. L’enregistrement cible doit être une pastille de données de type Enregistrement. Par exemple, un enregistrement d’incident spécifique. Vous pouvez rechercher cet enregistrement dans une étape préalable ou le définir comme variable d’entrée. Les détails d’exécution du flux affichent la sys_id de l’enregistrement associé. Remarque : Ce champ est disponible lorsque l’option Enregistrer en tant que pièce jointe est sélectionnée. |
) et en saisissant la vôtre.Évaluation de l’erreur d’action
- En cas d'échec de cette étape
- Type de données : Choice
Option permettant de continuer à exécuter l’étape suivante ou d’accéder à l’évaluation des erreurs. Pour utiliser le code d’état ou le message de l’étape pour une condition d’erreur d’action personnalisée, reportez-vous à la section Évaluation de l’erreur d’action.
Limites de taille de la réponse REST
Par défaut, le système limite à 5 Mo la taille des réponses REST qui ne sont pas enregistrées en tant que pièces jointes. Les réponses REST directes qui dépassent cette limite génèrent une erreur. Pour prendre en charge des tailles de réponse plus importantes, enregistrez la réponse en tant que pièce jointe ou augmentez la limite de taille de réponse avec la glide.pf.rest.response_payload_max_size propriété système. Cette propriété système prend en charge une valeur maximale de 10 240 Ko, ce qui limite la réponse REST à une taille de 10 Mo.
Analyse d’une réponse REST
Les appels d’API REST renvoient des données dans le corps de la réponse. Les données du corps de la réponse sont généralement structurées au format JSON ou XML. Vous pouvez utiliser a Étape Script pour analyser les données structurées en variables à utiliser ailleurs dans l’action ou dans un flux. Il est également possible d’analyser XML parser step le corps d’une réponse au format XML.
- Examinez le corps de la réponse pour sélectionner les données à renvoyer.
- Créez des variables d’entrée et de sortie dans l’étape Script.
- Créez une variable d’entrée à transmettre dans le corps de la réponse à partir de l’étape REST.
- Créez des variables de sortie pour renvoyer les données de la réponse.
- Créez un script pour analyser et mapper les données.
- Utilisez la méthode
JSON.parse()dans une étape de script pour analyser le corps d’une réponse JSON. - Mappez les données analysées aux variables de sortie.
- Utilisez la méthode
- Créez des sorties d’action pour les variables de sortie afin de rendre les données disponibles à un flux.