Pagination et actions de flux de données

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

    • Envoyez des demandes REST, SOAP ou JDBC de Concepteur de flux à des API qui retournent un flux de données de réponse supérieur à 10 Mo ou qui retournent des résultats paginés. Analysez les données de flux dans une série de sorties d'objets complexes et utilisez les pastilles de données dans d'autres actions dans un flux.

    Par exemple, créez une Flux de données action pour importer une grande quantité de données d’employés à partir d’un site RH tiers. L’action Flux de données envoie une demande REST au site tiers et traite la réponse pour remplir les enregistrements dans la table Utilisateur [sys_user].
    Remarque :
    les actions de flux de données nécessitent un abonnement Hub d'intégration. Pour plus d'informations, consultez Calendriers juridiques - Vue d'ensemble du Centre d'intégration.

    Avantages

    Flux de données Les actions offrent ces avantages.

    • Analysez et formatez un flux de données de réponse supérieur à 10 Mo.
    • Envoyez automatiquement plusieurs demandes aux API qui paginent les résultats, le cas échéant.
    • Peut être utilisé dans Hub d'intégration -Importation et pour créer une source de données.
    • Permettez aux concepteurs de flux de traiter des demandes volumineuses sans codage ni configuration complexes.
    • Permettre aux concepteurs de flux de traiter chaque objet d'un flux de données à l'aide d'une logique de flux Pour chaque. Par exemple, vous pouvez créer une action Flux de données pour importer des données de document à partir d'un site tiers. Lorsque vous ajoutez l'action à un flux, Concepteur de flux ajoute automatiquement cette action à un bloc logique de flux Pour chaque, permettant ainsi aux concepteurs de flux de créer facilement un enregistrement dans ServiceNow pour chaque objet du flux de données. Reportez-vous à Utiliser une Flux de données action dans un flux.
    • Autorisez les concepteurs de flux à réutiliser Flux de données les actions dans plusieurs flux, en utilisant la même source de données de plusieurs façons.

    Exécution d’une action de flux de données

    Il existe deux façons d’exécuter une Flux de données action.

    À partir d’un flux
    Vous pouvez traiter chaque objet d'un flux de données à l'aide d'une logique de flux Pour chaque. Par exemple, vous pouvez créer une action Flux de données pour importer des données de document à partir d'un site tiers. Lorsque vous ajoutez l'action à un flux, Concepteur de flux ajoute automatiquement cette action à un bloc logique de flux Pour chaque, permettant ainsi aux concepteurs de flux de créer facilement un enregistrement dans ServiceNow pour chaque objet du flux de données. Reportez-vous à Utiliser une Flux de données action dans un flux.
    À partir d’un script
    Vous pouvez démarrer une Flux de données opération à l’aide de la méthode executeDataStreamAction() dans la classe FlowAPI. Pour plus d’informations, consultez FlowAPI.

    Plan d’action

    Flux de données Les actions suivent une structure définie. Suivez les invites pour ajouter et supprimer des étapes du plan d’action. Vous ne pouvez pas ajouter manuellement d’étapes à une Flux de données action.

    Figure 1. Actions des flux de données REST et SOAP
    Action REST et flux de données SOAP.
    Figure 2. Action de flux de données JDBC
    Action de flux de données JDBC
    Remarque :
    La désactivation d'une option dans une page de configuration supprime l'étape du plan Flux de données ainsi que toutes les données associées à l'étape.

    Prétraitement de l'action

    Utilisez la catégorie Prétraitement d’action pour récupérer les détails de connexion et d’informations d’identification ou pour exécuter un script de prétraitement.

    Sélectionnez Récupérer les informations de connexion pour récupérer les détails de connexion et d’informations d’identification à utiliser dans votre action. La sélection de cette option ajoute l’étape Obtenir des informations sur la connexion comme première étape du prétraitement de l’action. Pour plus d'informations, consultez Get Connection Info step.

    Sélectionnez Activer le script de prétraitement pour exécuter un script de prétraitement avant que l’action n’envoie la demande d’API initiale. Par exemple, validez les entrées d'action ou définissez les valeurs par défaut. La sélection de cette option ajoute une étape de script à l'action Flux de données. Pour plus d'informations, consultez Script step.

    Le prétraitement s'exécute une fois par action, avant la première demande d'API.

    Il s’agit d’un composant d’action facultatif Flux de données qui s’exécute sur l’instance ou sur un Serveur MID.

    Demande

    Utilisez la catégorie Demande pour configurer la façon dont l’action envoie des demandes d’API. La section Demande s’exécute une fois par page de résultats. Les composants de demande fournissent les options de configuration suivantes.

    Étape de configuration de la pagination

    Demande entraîne des lots. Une fois que la page de données est traitée, l'action Flux de données réexécute la section de demande pour retourner le jeu suivant de résultats. Utilisez l’étape de configuration de la pagination pour configurer les options de pagination requises par l’API. Configurez manuellement l’étape de configuration de la pagination ou sélectionnez un modèle prédéfini pour appliquer des configurations communes. Par exemple, appliquez le modèle Limite/décalage pour spécifier le nombre d'éléments que vous souhaitez retourner par page (limite), ainsi que le numéro de départ du premier élément (décalage). Après l'application d'un modèle, mettez à jour les valeurs pour vous assurer que la configuration est conforme aux exigences de l'API.

    Remarque :
    À des fins de gestion des licences, chaque demande compte comme une seule transaction, y compris chaque demande pour la page de résultats suivante.

    La valeur de la variable getNextPage réservée et en lecture seule détermine s’il faut demander une autre page de résultats. Tant que la variable getNextPage est définie sur vrai et que la page précédente contient des données, l'action continue d'envoyer des demandes pour la page suivante.

    Remarque :
    Vous devez définir explicitement la valeur sur true dans le script, sinon elle sera définie par défaut sur false.
    Il s’agit d’un composant de demande facultatif qui ne s’exécute que sur l’instance.
    Remarque :
    La pagination ne s’applique pas à l’étape JDBC.
    Étape Script

    Exécutez un script avant chaque demande pour la page suivante de résultats. Utilisez ce script pour la validation et la transformation des données lors de l’appel d’une API paginée. Par exemple, générez une charge utile JSON pour la demande de page suivante. La sélection de cette option ajoute une étape de script à l'action Flux de données. Pour plus d'informations, consultez Script step.

    Il s’agit d’un composant de demande facultatif qui s’exécute sur l’instance ou sur un Serveur MID.

    Étape REST ou SOAP

    Envoyez une demande REST ou SOAP à une API tierce. Sélectionnez un format de données pour ajouter une étape associée à l’action Flux de données . Pour plus d'informations, consultez Étape REST et Étape SOAP.

    Il s’agit d’un composant de demande obligatoire qui s’exécute sur l’instance ou sur un Serveur MID.

    Étape JDBC

    Envoyez une demande JDBC à une API tierce. Utilisez un script de transformation pour formater les données et ajouter une étape associée à l’action Flux de données . Pour plus d'informations, consultez Étape JDBC et Tester l’étape JDBC. Toutes les données sont récupérées et la pagination n’est pas nécessaire.

    Il s’agit d’un composant de demande obligatoire qui s’exécute sur un Serveur MIDfichier .

    Analyse des étapes REST et SOAP

    Utilisez la catégorie Analyse pour configurer la façon dont l’action sépare les éléments de flux de données en objets de données complexes. Utilisez l’étape de séparation pour identifier et séparer les éléments d’un flux XML ou JSON, et utilisez l’étape de l’analyseur de script pour transformer chaque élément en un objet complexe. La section d’analyse s’exécute une fois par élément du flux. Vous pouvez accéder aux sorties des étapes précédentes de votre action de flux de données à l’aide de l’objet fd_data , à l’exclusion des éléments suivants :
    • Étape REST ou SOAP Sorties de corps de réponse, de flux ou de message d’erreur
    • Sorties de l’étape de séparation

    Fractionnement et analyse d’un flux d’enregistrements utilisateur.

    Pour plus d’informations sur les données complexes, reportez-vous à la rubrique Données complexes. Les composants d’analyse fournissent les options de configuration suivantes.

    Étape du séparateur

    Identifier le nœud parent dans le flux de réponse à mapper à un objet complexe. Par exemple, identifiez un élément utilisateur dans une charge utile XML pour créer un objet complexe pour chaque utilisateur dans le flux de réponse.

    Sélectionnez un type de séparateur pour identifier et séparer les éléments répétés dans un flux de données XML ou JSON.

    • JSON : identifie les objets d'un flux de données JSON. Utilisez une expression JSONPath pour identifier un tableau JSON contenant des données répétées.
    • XML : identifie les objets à partir d'un flux de données XML. Utilisez une expression XPath pour identifier un élément XML contenant des données répétées.

    Il s’agit d’un composant d’analyse obligatoire qui ne s’exécute que sur l’instance.

    Étape de l'analyseur de script

    Utilisation JavaScript et des API ServiceNow pour mapper des éléments du flux de réponse à une sortie d'objet complexe représentée par l'objet global TargetObject. Par exemple, mappez les éléments d'enregistrement d'incident identifiés à l'étape de séparation à un objet complexe contenant des champs d'incident. Si le flux de données inclut des frères et sœurs de l'élément identifié dans l'étape de séparation que vous ne souhaitez pas mapper à un objet complexe, incluez des conditions pour exclure ces éléments. Vous pouvez ignorer des éléments dans le flux en ajoutant outputs.state = 'SKIP' partout où cela est nécessaire à la section de script de l’étape de l’analyseur de script.

    Il s’agit d’un composant d’analyse obligatoire qui ne s’exécute que sur l’instance.

    Figure 3. Vue d’ensemble des actions des flux de données REST et SOAP
    Vue d’ensemble de l’action REST et SOAP Data Stream.

    Transformer le script dans l’étape JDBC

    L’action de flux de données JDBC ne nécessite pas de pagination. De plus, les étapes de séparation et d’analyse ne sont pas nécessaires.

    L’étape JDBC génère un objet complexe pour chacun des enregistrements récupérés. Par conséquent, le prétraitement de l’action et le script de transformation dans l’action de flux de données JDBC sont facultatifs. Lors de l’utilisation du script de transformation, le concepteur d’action doit spécifier le nom interne des colonnes de table dans le script de transformation.
    Figure 4. Vue d’ensemble de l’action Flux de données JDBC
    Vue d’ensemble de l’action Flux de données JDBC.

    Sorties de flux de données dans les étapes SOAP et REST

    Lors de la conception d’une Flux de données action, vous devez créer une sortie unique de type Objet ou Objet dynamique. L’étape de l’analyseur de script mappe les éléments du flux à cet objet à l’aide de l’objet global targetObject .

    Lors de l’exécution, le système divise et analyse le flux de données de réponse en fonction de la Flux de données configuration. Chaque élément du flux est mappé à la structure d’objet complexe définie par l’étape de l’analyseur de script et la sortie de l’objet, ce qui donne une grande série d’objets complexes. Pour plus d’informations sur les données complexes, reportez-vous à la rubrique Données complexes.

    Sorties de flux de données dans l’étape JDBC

    La sortie des étapes JDBC est un flux d’objets complexe. Toutes les données sont récupérées en une seule demande.
    Remarque :
    • Vous ne pouvez récupérer que des données et ne pouvez pas mettre à jour ou supprimer des enregistrements à l’aide de l’action de flux de données JDBC.
    • Les champs, Ligne maximum et Taille de charge utile maximale (Ko) disponibles dans l’étape JDBC ne sont pas disponibles dans l’action de flux de données JDBC.

    Détails de l’exécution dans les étapes REST et SOAP

    Affichez les résultats de configuration et d’exécution pour chaque élément traité par une Flux de données action. Sélectionnez un numéro d’enregistrement pour afficher ses détails de configuration et d’exécution. Par défaut, les détails d’exécution incluent les demandes des 1 000 derniers éléments. Pour modifier le nombre d’éléments dans les détails d’exécution, mettez à jour la com.snc.process_flow.reporting.datastream.item.lastn propriété système.

    Détails de l’exécution d’une action de flux de données.

    Résumé du flux de données

    Affichez une vue d’ensemble de l’exécution qui inclut ces informations.

    • Nombre de pages : nombre de pages renvoyées par une API paginée.
    • Nombre total d’éléments : nombre d’éléments dans le flux de réponse mappés aux sorties d’objets complexes.
    • Nombre d’erreurs : nombre d’erreurs rencontrées.
    Détails de page

    Affichez les données d’exécution pour chaque étape de l’action Flux de données . Sélectionnez une page pour afficher les détails d’exécution pour chaque demande à une API paginée. Par défaut, les détails de l’exécution incluent les demandes des cinq dernières pages. Pour modifier le nombre de demandes dans les détails de l’exécution, mettez à jour la com.snc.process_flow.page.reporting.lastn propriété système. Définissez la valeur sur 0 pour supprimer des pages des détails d’exécution et sur -1 pour inclure toutes les pages.

    Remarque :
    L’inclusion de toutes les pages peut affecter les performances et n’est pas recommandée.

    Détails de l’exécution

    Détails de l’exécution dans l’étape JDBC

    La construction du schéma d’objet complexe de sortie n’est pas nécessaire pour l’action de flux de données JDBC. Vous pouvez tester la requête et afficher son résultat. Consultez Tester l’étape JDBC pour plus d'informations. Configurez les propriétés mid.jdbc.datastream.max.record.size et mid.jdbc.datastream.fail.when.attachement.limit.exceeded récupérez les Serveur MID données selon vos besoins. Consultez les propriétés du MID Server pour plus d’informations.