Créer une action de flux de données pour obtenir des utilisateurs

  • Rversion finale: Yokohama
  • Mis à jour 30 janv. 2025
  • 7 minutes de lecture

    • Créez une action de flux de données pour obtenir une liste des abonnements de l’utilisateur à partir de l’application SaaS .

    Avant de commencer

    Si vous utilisez un spoke existant ServiceNow® Hub d'intégration , vérifiez s’il dispose d’une action de flux de données pour obtenir une liste d’utilisateurs que vous pouvez utiliser au lieu d’en créer un. Pour plus d’informations sur les actions de flux de données, voir Actions de flux de données.

    Rôle requis : flow_designer ou admin

    Procédure

    1. Accédez à la Tout > Concepteur de flux > Concepteur.
    2. Sélectionnez Nouveau.
    3. Sélectionnez un flux de données.
    4. Renseignez les champs du formulaire.
      Tableau 1. Formulaire Propriétés de l’action
      Champ Valeur
      Nom Nom de votre choix.

      Par exemple, Obtenir des utilisateurs.
      Accessible depuis Tous les périmètres de l’application.
      Catégorie Laissez ce champ vide.
      Protection Aucun.
      Demande Application de spoke à intégrer à l’application SaaS .

      Cette application de spoke peut être un spoke existant Hub d'intégration ou un nouveau spoke que vous avez créé.
      Annotation dans le flux Laissez ce champ vide.
      Description Description de votre choix.
    5. Sélectionnez Soumettre.
    6. Si l’API avec laquelle vous travaillez nécessite une authentification utilisateur pour les demandes, sélectionnez Entrées dans le Plan d’action et ajoutez des entrées pour l’authentification.
      L’ID d’utilisateur administrateur et le nom du site sont des exemples d’entrées d’authentification utilisateur courantes. Consultez la documentation de l’API que vous avez choisie pour en savoir plus sur les exigences relatives à l’authentification utilisateur dans votre cas spécifique. Si l’API nécessite un jeton d’accès, une variable Valeur d’informations d’identification est automatiquement créée ultérieurement. Vous n’avez pas besoin d’ajouter un jeton d’accès en tant qu’entrée.

      Lorsque vous utilisez votre action de flux de données terminée dans un flux secondaire, vous définissez les valeurs à transmettre en tant qu’entrées.

    7. Sélectionnez Demande dans le Plan d’action.
    8. Renseignez les champs du formulaire.
      Tableau 2. Formulaire de demande
      Champ Valeur
      Comment obtiendrez-vous des données ? Choisissez l’étape REST ou l’étape SOAP.

      Votre choix dépend de l’API de l’application SaaS avec laquelle vous intégrez.
      Activer la pagination Sélectionné.
      Exécuter un script avant chaque demande Non sélectionné.
    9. Sélectionnez l’étape de configuration de la pagination dans le Plan d’action.
    10. Définissez des variables de pagination en fonction des paramètres de requête utilisés par l’API SaaS .

      Si vous utilisez la pagination basée sur le décalage, utilisez le modèle de pagination Limite/Décalage pour précharger la configuration de pagination.

      Remarque :
      La valeur de la variable getNextPage réservée détermine s’il faut demander une autre page de résultats. Tant que la variable getNextPage est définie sur vrai, l’action continue d’envoyer des demandes pour la page suivante.
    11. Écrivez un script Variables de pagination pour mettre à jour les variables de pagination.

      Le script s’exécute sur chaque demande. Si vous utilisez un modèle de pagination, ajustez le script préchargé selon vos besoins.

      L’image suivante montre un exemple d’achèvement de l’étape de configuration de la pagination. Cet exemple provient de l’action Obtenir le flux de données des utilisateurs utilisée dans le Webex flux secondaire Télécharger les abonnements.

      Étape de configuration de la pagination
      Remarque :
      Les variables de pagination prennent uniquement en charge les données de type chaîne. Pour effectuer des opérations mathématiques, vous devez convertir la valeur en nombre entier, effectuer toutes les opérations requises, puis la convertir en chaîne.
    12. Sélectionnez l’étape SOAP ou l’étape REST dans le plan d’action pour recevoir des données.
      • Si vous avez sélectionné l’étape SOAP, renseignez les détails.
        Tableau 3. Formulaire Étape SOAP
        Champ Valeur
        Détails de la connexion
        Connexion Utilisez des alias de connexion.
        Alias de connexion Alias de connexion que vous avez créé lors de la création du profil d’intégration. Si vous n’avez pas encore créé de profil d’intégration, suivez les étapes pour créer un profil d’intégration personnalisé avec un alias de connexion.
        Point de terminaison Cette valeur est automatiquement renseignée lorsque vous sélectionnez l’alias de connexion.

        Cette valeur est définie sur l’URL de connexion à partir de l’enregistrement de connexion HTTPs lié à l’alias.
        Détails de la demande
        Enveloppe de version Manuellement.
        Action SOAP Demande d’API pour obtenir une liste de tous les utilisateurs. Consultez la documentation de l’API que vous avez choisie pour sélectionner la demande appropriée.
        Enveloppe SOAP Message de demande XML pour obtenir une liste de tous les utilisateurs. Consultez la documentation de l’API de votre choix pour savoir comment écrire un message de demande XML. En général, l’en-tête doit contenir vos variables d’entrée pour l’authentification utilisateur ainsi que la variable Valeur d’informations d’identification comme jeton d’accès. Le corps doit inclure la demande d’obtention d’une liste de tous les utilisateurs et de vos variables à partir de l’étape de configuration de la pagination.
        Remarque :
        Pour obtenir un exemple d’enveloppe SOAP, consultez l’action Obtenir le flux de données des utilisateurs utilisée dans le Webex flux secondaire Télécharger les abonnements.
      • Si vous avez sélectionné l’étape REST, renseignez les détails.
        Tableau 4. Formulaire Étape REST
        Champ Valeur
        Détails de la connexion
        Connexion Utilisez des alias de connexion.
        Alias de connexion Alias de connexion que vous avez créé lors de la création du profil d’intégration. Si vous n’avez pas encore créé de profil d’intégration, suivez les étapes pour créer un profil d’intégration personnalisé avec un alias de connexion.
        URL de base Cette valeur est automatiquement renseignée lorsque vous sélectionnez l’alias de connexion. Elle est définie sur l’URL de connexion à partir de l’enregistrement de connexion HTTP(s) lié à l’alias.
        Détails de la demande
        Demande de version Manuellement.
        Chemin d'accès à la ressource Chemin d’accès à la ressource. Cette valeur est ajoutée à l’URL de base. Consultez la documentation de l’API avec laquelle vous travaillez pour savoir comment construire le chemin d’accès de la ressource.
        Méthode HTTP GET.
        Paramètres de requêtes Ajoutez des paramètres pour la pagination. Définissez les valeurs en tant que variables que vous avez créées à l’étape de configuration de la pagination.

        L’image suivante montre un exemple terminé de l’étape REST. Cet exemple provient de l’action Obtenir Jira le flux de données des utilisateurs utilisée dans le Jira flux secondaire Télécharger les abonnements.

        Étape REST
    13. Sélectionnez Analyse dans Plan d’action.
    14. Renseignez les champs du formulaire.
      Tableau 5. Analyse du formulaire
      Champ Valeur
      Comment identifierez-vous chaque enregistrement ? Séparateur JSON/XML
      Comment analyserez-vous chaque élément dans un objet ? Analyseur de script
    15. Sélectionnez l’étape de séparation dans le Plan d’action.
    16. Renseignez les champs du formulaire.
      Tableau 6. Étape de séparation
      Champ Valeur
      Format source Sélectionnez XML ou JSON, selon le format renvoyé par la réponse API.
      Chemin de l'élément Chemin d’accès absolu à un élément utilisateur dans le message de réponse. Consultez la documentation de l’API avec laquelle vous travaillez pour en savoir plus sur le format du message de réponse.
      • Exemple de chemin d’accès de l’élément XML : /message/body/user
      • Exemple de chemin d’accès de l’élément JSON : $.data.user
    17. Sélectionnez des sorties dans le plan d’action.
    18. Sélectionnez Créer une sortie et modifiez la variable comme indiqué.
      Tableau 7. Résultat de l'action
      Étiquette Nom Type Obligatoire
      targetObject targetObject Objet Non
    19. Ajoutez des éléments enfants pour targetObject en fonction des éléments enfants de l’utilisateur renvoyés dans le message de réponse.
      Par exemple, une réponse XML peut ressembler à ceci.
      <message>​
  <body>​
    <user>
      <userID>​12345</userID>​
      ​<email>​email@email.com</email>​
      <firstName>​Jane</firstName>​
      <lastName>​Doe</lastName>​
      <lastLoginTime>​08/13/2019 20:08:16</lastLoginTime>​
      <active>​TRUE</active>​
    </user>​
    <user>
      ...
    </user>
  </body>​
</message>
      Pour cette réponse, ajoutez les éléments enfants comme indiqué.
      Tableau 8. Éléments enfants pour targetObject
      Étiquette Nom Type Obligatoire
      userID userID Chaîne Non
      E-mail E-mail Chaîne Non
      firstName firstName Chaîne Non
      lastName lastName Chaîne Non
      lastLoginTime lastLoginTime Chaîne Non
      actif actif Vrai/Faux Non
    20. Sélectionnez l’étape de l’analyseur de script dans le Plan d’action.
    21. Créez un objet de sortie targetObject pour chaque élément utilisateur de la réponse, puis mappez chaque élément enfant utilisateur à un élément enfant targetObject .

      Le script d’analyseur est exécuté pour chaque élément utilisateur.

      Remarque :
      Ces exemples montrent les types d’éléments généralement contenus dans une réponse à une demande d’obtention d’utilisateurs. Ne copiez pas directement ces scripts. Utilisez les noms d’éléments de la documentation de l’API avec laquelle vous travaillez.
      Exemple de script qui analyse une réponse XML. 
      (function parse(inputs, outputs) {
    var xmlDoc = new XMLDocument(inputs.sourceItem, false);
    outputs.targetObject.userID = xmlDoc.getNodeText('/user/userID');
    outputs.targetObject.email = xmlDoc.getNodeText('/user/email');
    outputs.targetObject.firstName = xmlDoc.getNodeText('/user/firstName');
    outputs.targetObject.lastName = xmlDoc.getNodeText('/user/lastName');
    outputs.targetObject.lastLoginTime = xmlDoc.getNodeText('/user/lastLoginTime');
    outputs.targetObject.active = xmlDoc.getNodeText('/user/active');
})(inputs, outputs)
      Exemple de script qui analyse une réponse JSON. 
      (function parse(inputs, outputs) {
    var record = JSON.parse(inputs.sourceItem);
    outputs.targetObject.userID = record.userID;
    outputs.targetObject.email = record.email;
    outputs.targetObject.firstName = record.firstName;
    outputs.targetObject.lastName = record.lastName;
    outputs.targetObject.lastLoginTime = record.lastLoginTime;
    outputs.targetObject.active = record.active;
})(inputs, outputs)
    22. Pour tester votre action de flux de données, sélectionnez Tester.
      1. Consultez les résultats des tests et les journaux système pour plus de détails sur les éventuelles erreurs.
        Pour afficher les journaux système, accédez à Journaux système > Journal système > Tout.
      2. Si votre action de flux de données comporte des erreurs, assurez-vous que vous utilisez les bons points de terminaison et que les demandes et réponses d’API sont structurées comme prévu.
    23. Après avoir vérifié que l’action de flux de données fonctionne comme prévu, sélectionnez Publier.

    Que faire ensuite

    Créer un flux secondaire pour obtenir des utilisateurs.