Créer une activité de service Web REST

  • Rversion finale: Zurich
  • Mis à jour 31 juil. 2025
  • 13 minutes de lecture

    • Utilisez cette procédure pour créer une activité de service Orchestration Web REST personnalisée.

    Avant de commencer

    Rôle requis : web_service_admin, activity_admin activity_creator

    Pourquoi et quand exécuter cette tâche

    Pour créer et utiliser une activité de workflow de service Web REST :

    Procédure

    1. Créez une activité personnalisée.
      Cette action crée une activité personnalisée à l’aide d’un modèle.
    2. Après avoir configuré les propriétés générales et créé des variables d’entrée, configurez la commande d’exécution du service Web REST.
      OptionDescription
      Mapper les variables d’entrée Utilisez les variables que vous avez créées pour configurer la commande qu’exécute Orchestration.
      Message REST Nom d’un message REST existant à utiliser dans cette activité.
      Fonction de message REST Fonction de message REST à utiliser pour cette activité.
      Point de terminaison URL du point de terminaison pour le service Web REST que cette activité utilise. Entrez un point de terminaison dans ce champ pour remplacer le point de terminaison configuré dans le message REST. Cliquez sur le verrou pour ouvrir le champ d’entrée.
      Substitutions de variables Paires nom-valeur à transmettre au point de terminaison REST. Vous pouvez créer ces paramètres manuellement ou faire glisser des variables d’entrée dans les champs de paramètres, puis affecter une valeur. Les paramètres définis dans le message REST qui utilisent ${} peuvent être des données affectées à partir de ce modèle d’activité. Utilisez la colonne Attribut supplémentaire pour configurer le système afin qu’il ne soit pas soumis à une séquence d’échappement du texte. Par défaut, le texte envoyé au message REST est échappé. Si les utilisateurs ont fourni des variables à l’aide de la substitution de variables dans des messages REST sortants dans le message REST, la colonne Nom est automatiquement renseignée.
      En-têtes supplémentaires Paramètres d’en-tête HTTP supplémentaires pour le message REST sélectionné. Vous pouvez également utiliser ces valeurs pour remplacer les paramètres hérités du message REST.
      Paramètres de requêtes supplémentaires Paramètres de requête supplémentaires pour le message REST sélectionné. Vous pouvez également utiliser ces valeurs pour remplacer les paramètres hérités du message REST.
      Utiliser un serveur MID Case à cocher qui détermine si un serveur MID doit être utilisé pour appeler le service Web REST.
      Remarque :
      Si la fonction de message de service Web REST définit un serveur MID, ce serveur MID est utilisé à la place de celui sélectionné ici.
      Capacités de Serveur MID requises Serveur MID avec les options de Serveur MID appropriées pour la connexion au point de terminaison REST. Par défaut, le système sélectionne un serveur MID avec les options REST. Ce champ est disponible lorsque la case Utiliser Serveur MID est cochée.
      Délai Durée autorisée de la demande de service Web REST avant l’expiration de celle-ci, en secondes. La valeur par défaut est 10.
      Authentification Détermine le type d’authentification requis pour le point de terminaison. Les options sont les suivantes :
      • Utiliser les informations d’identification existantes dans le message REST : utilise les définitions d’informations d’identification de la définition de message REST.
      • Remplacer par les informations d’identification de base : utilise l’option Activer l’authentification de base pour les informations d’identification SOAP sortantes afin de remplacer les informations d’identification dans la définition de message REST. Les informations d’identification d’authentification de base doivent être mises en service avant d’être disponibles à la sélection.
      • Remplacer par certificat Informations d’identification d’authentification : utilise un certificat, tel qu’une clé privée, pour remplacer les informations d’identification dans la définition du message REST.
      • Remplacer par les informations d’identification de base et par certificat : utilise à la fois l’authentification de base et l’authentification par certificat pour remplacer les informations d’identification dans la définition du message REST.
      • Remplacer par les informations d’identification d’authentification OAuth : utilise les informations d’identification OAuth 2.0 pour remplacer les informations d’identification dans la définition du message REST. Le message REST sélectionné pour cette activité doit avoir son didacticiel OAuth 2.0 - créez un message REST défini sur OAuth 2.0 et ses profils et champs d’application OAuth configurés de manière appropriée.
      Informations d'identification Point de terminaison REST requis : informations d’identification d’authentification de base. Ce champ est disponible lorsque Remplacer les informations d’identification de l’authentification de base est sélectionné dans le champ Authentification . Seules les informations d’identification d’authentification de base apparaissent dans la liste de sélection, qui comprend les informations d’identification stockées sur l’instance et les ID d’informations d’identification d’un système de stockage externe. Si vous utilisez des informations d’identification stockées dans un coffre-fort CyberArk, vous pouvez remplacer le coffre-fort par défaut défini dans le fichier de configuration du serveur MID. Pour plus d’informations, consultez Configurer le serveur MID pour CyberArk . Ajoutez le nom d’un autre coffre-fort comme préfixe à l’ID d’identifiant, séparé par deux points. Par exemple, newsafe:orch-test-f5.
      Profil du protocole Authentification par certificat à utiliser. Ce champ est disponible lorsque les sélections dans l’authentification sont soit Remplacer par les informations d’identification d’authentification de certificat , soit Remplacer par les informations d’identification de base et d’authentification par certificat.
      Profil OAuth Profil du fournisseur OAuth pour ce message REST. Consultez Spécifier un profil OAuth pour plus d’informations.
      Remarque :
      Vous pouvez mapper automatiquement les valeurs des paramètres d’une charge utile de test aux variables de l’onglet Sorties . Voir variables de sortie de mappage automatique.

    Que faire ensuite

    Terminez la création de votre activité de service Web Rest en créant des variables de sortie, une règle d’analyse ou desconditions. Reportez-vous à la rubrique Créer des activités personnalisées pour connaître les options de votre modèle.

    Mapper automatiquement les variables de sortie d’activité REST

    Le ServiceNow concepteur d’activité vous permet de mapper automatiquement les valeurs des paramètres d’une charge utile de test REST aux variables de l’étape Sorties .

    Avant de commencer

    Rôle requis : web_service_admin, activity_admin activity_creator

    Pourquoi et quand exécuter cette tâche

    Remarque :
    Vous pouvez tester les variables d’entrée à n’importe quelle étape du concepteur d’activité si vous avez fourni suffisamment d’informations pour qu’Orchestration contacte le point de terminaison et renvoie les données. En règle générale, l’étape de commande d’exécution est le point auquel vos entrées sont prêtes pour le test.

    Procédure

    1. Dans le concepteur d’activité, passez à l’étape Commande d’exécution .
    2. Définir un Serveur MID approprié, si demandé.
      Le test échoue si le serveur MID est introuvable ou s’il ne peut pas se connecter à la cible.
    3. Cliquez sur Activité de test pour tester les paramètres d’entrée.
      Si vous avez ajouté des valeurs réelles pour les paramètres et les champs, le système exécute ces valeurs par rapport à la cible spécifiée et renvoie la charge utile résultante. Si vous avez mappé des variables d’entrée à des champs et des paramètres, le système affiche une boîte de dialogue permettant d’affecter des valeurs de test à ces variables.
    4. Fournissez des valeurs de test, si demandé, et cliquez sur OK pour afficher la charge utile.
      L’ensemble de la charge utile apparaît dans l’onglet Sortie brute du formulaire de réponse.
      Contrôles de mappage automatique
    5. Sélectionnez l’une de ces options de mappage automatique.
      • Mappage automatique vers local : mappe directement les valeurs à une variable locale à utiliser dans l’activité.
      • Mappage automatique vers la sortie : mappe directement les valeurs à la variable de sortie pour les transmettre à d’autres activités du workflow. Le mappage automatique à une variable de sortie crée un tableau d’objets, chacun contenant les noms de colonnes du résultat de la requête.

    Paramètres d’exécution du modèle REST

    Vous utilisez les paramètres d’exécution pour créer le script de processus d’entrée dans le formulaire Prétraitement du concepteur d’activité.

    Pour obtenir des descriptions des champs de commande du service Web REST, reportez-vous à la section Configurer la commande d’exécution REST.
    Remarque :
    Vous devez utiliser le préfixe executionParam. avec toutes les variables de cette table.
    Tableau 1. Paramètres d’exécution du modèle REST
    Nom Variable Type Utilisation
    Message de service Web web_service_message Référence La sys_id du message de service Web correspondant.
    Fonction de message de service Web web_service_message_function Référence Le sys_id de la fonction de message REST.
    Point de terminaison de service Web web_service_endpoint Chaîne URL du point de terminaison REST.
    Paramètres paramètres Tableau d’objets JavaScript Tableau d’objets JavaScript, exprimé avec le préfixe executionParam. Pour obtenir des instructions sur la création de tableaux à l’aide de ce paramètre, reportez-vous à la section Créer un tableau JavaScript dans un modèle REST.
    Utiliser un Serveur MID use_mid_server Booléen Indique s’il faut utiliser ou non le Serveur MID. Une valeur vrai utilise le serveur MID et une valeur faux n’utilise pas le serveur MID.
    Capacités moyennes midCapabilities Chaîne (séparée par des virgules) Liste de références aux options de Serveur MID requises.
    Délai d'expiration atteint arrêt de jeu Chaîne Durée du délai d’expiration autorisé, exprimé en secondes.
    ValeurCapacités valueCapabilities Tableau de la carte de hachage Valeurs d’aptitude utilisées pour sélectionner le Serveur MID. Pour plus d’informations, voir Aptitudes du serveur MID. Utilisez cet exemple pour personnaliser la sélection de Serveur MID si des options supplémentaires sont affectées par valeur :
    var valueCapability = {'NEW_MID_CAPABIILTY':'NEW_MID_CAPABILITY_VALUE'}; executionParam.valueCapabilities.push(valueCapability);
    Type d'authentification Type d’authentification Booléen Type d’informations d’identification à utiliser. Les choix possibles sont les suivants :
    • basic_auth_pick_credentials
    • use_existing_credentials
    Informations d'identification informations d'identification Référence Contient les informations d’identification à utiliser pour ce message REST lorsque le auth_type sélectionné est basic_auth_pick_credentials.

    Créer un tableau JavaScript dans un modèle REST

    Il s’agit d’instructions pour créer des tableaux JavaScript à l’aide des paramètres d’exécution REST.

    Avant de commencer

    Rôle requis : web_service_admin, activity_admin activity_creator

    Pourquoi et quand exécuter cette tâche

    Pour ajouter d’autres paires nom-valeur au tableau du paramètre, ajoutez les valeurs au tableau existant.

    Procédure

    1. Créez un objet JavaScript avec la syntaxe suivante et ajoutez-le au tableau executionParam.parameter : 
      var newParameter = {"name":"parameterName","value":"parameterValue","additional_attribute":"none"}; 
executionParam.parameters.push(newParameter);

      En ajoutant le nouvel objet JavaScript paramètre au tableau, vous vous assurez que les éléments déjà disponibles dans le tableau ne sont pas affectés.

    2. Assurez-vous de définir la valeur dans la colonne Attribut supplémentaire du champ d’entrée Paramètres du message REST sur Ne pas échapper de texte.

      Dans ce cas, le système n’échappe pas la valeur spécifiée pour l’attribut value . Par exemple :

      var newParameter = {"name":"parameterName","value":"parameterValue","additional_attribute":"do_not_escape_text"}; 
executionParam.parameters.push(newParameter);
      Remarque :
      Si la valeur du champ additional_attribute est Aucun, le système échappe la valeur spécifiée par l’attribut value . Dans le premier exemple, parameterValue est échappé.

    Paramètres de post-traitement du modèle REST

    Utilisez ces paramètres pour créer un script de post-traitement.

    Tableau 2. Paramètres de post-traitement du concepteur d’activité
    Nom Variable Type Utilisation
    Code d'état status_code Entier Contient le code d’état renvoyé par le service Web REST.
    En-tête header Hashmap de l’objet JavaScript Carte de hachage des paires clé-valeur associées aux valeurs d’en-tête transmise au service Web. Vous pouvez accéder à chaque valeur à l’aide de executionResult.header[keyName].
    Détails body Chaîne Contient une valeur de chaîne représentant la sortie du message REST
    Erreur erreur Chaîne Renvoie la chaîne d’erreur du service Web REST, sauf s’il n’y a pas d’erreur, auquel cas renvoienull.

    Configurer la commande d’exécution REST

    Utilisez les variables d’entrée que vous avez créées pour configurer la commande qu’Orchestration exécute sur le point de terminaison REST.

    Avant de commencer

    Créez les variables d’entrée dont vous avez besoin dans le formulaire Entrées avant de pouvoir passer à l’étape de commande d’exécution .

    Rôle requis : web_service_admin, activity_admin activity_creator

    Remarque :
    Vous pouvez tester la connexion REST entre le serveur MID et le point de terminaison sans avoir à exécuter l’activité dans un contexte de workflow. Pour plus d’informations, consultez Sorties de modèles de tests.

    Procédure

    1. Faites glisser les variables de la liste des entrées et déposez-les dans les champs de commande.
      Le système formate la variable dans la syntaxe appropriée pour la commande.
      Figure 1. Commande d’exécution REST
      Commande d’exécution REST
    2. Renseignez les champs indiqués dans la table.
      Tableau 3. Champs de commandes d’exécution REST
      Champ Description
      Entrée Générateur de variables d’entrée. Créer des variables d’entrée pour mapper aux champs disponibles.
      Message REST Nom d’un message REST existant à utiliser dans cette activité. Les utilisateurs doivent disposer du rôle web_service_admin pour configurer ce champ.
      Fonction de message REST Fonction de message REST à utiliser pour cette activité. Les utilisateurs doivent disposer du rôle web_service_admin pour configurer ce champ.
      Point de terminaison URL du point de terminaison pour le service Web REST que cette activité utilise. Entrez un point de terminaison dans ce champ pour remplacer le point de terminaison configuré dans le message REST. Cliquez sur le verrou pour ouvrir le champ d’entrée.
      Substitutions de variables Paires nom-valeur à transmettre au point de terminaison REST. Vous pouvez créer ces paramètres manuellement ou glisser-déplacer des variables d’entrée dans les champs de paramètres, puis affecter une valeur. Les paramètres définis dans le message REST qui utilisent ${} peuvent être des données affectées à partir de ce modèle d’activité. Utilisez la colonne Attribut supplémentaire pour configurer le système afin qu’il ne soit pas soumis à une séquence d’échappement du texte. Par défaut, le texte envoyé au message REST est échappé. La colonne Nom est automatiquement renseignée si les utilisateurs ont fourni des variables à l’aide de la substitution de variables dans les messages REST sortants dans le message REST.
      En-têtes supplémentaires Paramètres d’en-tête HTTP supplémentaires pour le message REST sélectionné. Vous pouvez également utiliser ces valeurs pour remplacer les paramètres hérités du message REST.
      Paramètres de requêtes supplémentaires Paramètres de requête supplémentaires pour le message REST sélectionné. Vous pouvez également utiliser ces valeurs pour remplacer les paramètres hérités du message REST.
      Utiliser un serveur MID Case à cocher qui détermine si un serveur MID doit être utilisé pour appeler le service Web REST.
      Remarque :
      Si la fonction de message de service Web REST définit un serveur MID, ce serveur MID est utilisé à la place de celui sélectionné ici.
      Capacités de Serveur MID requises Serveur MID avec les options de Serveur MID appropriées pour la connexion au point de terminaison REST. Par défaut, le système sélectionne un serveur MID avec les options REST. Ce champ est disponible lorsque la case Utiliser Serveur MID est cochée.
      Délai Durée autorisée de la demande de service Web REST avant l’expiration de celle-ci, en secondes. La valeur par défaut est 10.
      Authentification Détermine le type d’authentification requis pour le point de terminaison. Les options sont les suivantes :
      • Utiliser les informations d’identification existantes dans le message REST : utilise les définitions d’informations d’identification de la définition de message REST.
      • Remplacer par les informations d’identification de base : utilise l’option Activer l’authentification de base pour les informations d’identification SOAP sortantes afin de remplacer les informations d’identification dans la définition de message REST. Les informations d’identification d’authentification de base doivent être mises en service avant d’être disponibles à la sélection.
      • Remplacer par certificat Informations d’identification d’authentification : utilise un certificat, tel qu’une clé privée, pour remplacer les informations d’identification dans la définition du message REST.
      • Remplacer par les informations d’identification de base et par certificat : utilise à la fois l’authentification de base et l’authentification par certificat pour remplacer les informations d’identification dans la définition du message REST.
      • Remplacer par les informations d’identification d’authentification OAuth : utilise les informations d’identification OAuth 2.0 pour remplacer les informations d’identification dans la définition du message REST. Le message REST sélectionné pour cette activité doit avoir son didacticiel OAuth 2.0 - créez un message REST défini sur OAuth 2.0 et ses profils et champs d’application OAuth configurés de manière appropriée.
      Informations d'identification Point de terminaison REST requis : informations d’identification d’authentification de base. Ce champ est disponible lorsque Remplacer les informations d’identification de l’authentification de base est sélectionné dans le champ Authentification . Seules les informations d’identification d’authentification de base apparaissent dans la liste de sélection, qui comprend les informations d’identification stockées sur l’instance et les ID d’informations d’identification d’un système de stockage externe. Si vous utilisez des informations d’identification stockées dans un coffre-fort CyberArk, vous pouvez remplacer la valeur Configurer le serveur MID pour CyberArk définie dans le fichier de configuration du serveur MID en ajoutant le nom d’un autre coffre-fort comme préfixe à l’ID d’informations d’identification, séparé par deux points. Par exemple, newsafe:orch-test-f5.
      Profil du protocole Authentification par certificat à utiliser. Ce champ est disponible lorsque les sélections dans le champ Authentification sont soit Remplacer par les informations d’identification de l’authentification de certificat , soit Remplacer par les informations d’identification de base et de certificat.
      Profil OAuth Profil du fournisseur OAuth pour ce message REST. Consultez Spécifier un profil OAuth pour plus d’informations.
    3. Cliquez sur Enregistrer.
    4. Cliquez sur Continuer pour passer à l’étape Sorties .