Créer des définitions de script pour une table distante

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

    • Définissez des scripts pour une table distante afin de récupérer des données à partir d’une source de données externe ou de modifier des données dans une source externe.

    Avant de commencer

    Rôle requis : delegated_developer avec Autoriser les autorisations de scripting ou admin

    Pourquoi et quand exécuter cette tâche

    Le récupère ServiceNow AI Platform et met en cache les données de la table distante en exécutant le script de requête sur une source de données externe afin que vous puissiez l’afficher ou la modifier. Vous pouvez également indiquer comment ces données externes sont mises en cache et combien de temps les données sont mises en cache en mémoire jusqu’à ce que le script doive s’exécuter à nouveau.

    Procédure

    1. Accédez à la Tous > Définition du système > Tables distantes > Définition.
    2. Sélectionnez Nouveau.
    3. Remplissez les champs du formulaire.
      Contrôle Description
      Nom

      Nom du script que vous créez pour l’associer à la table distante sélectionnée.
      Table
      Nom de la table distante à laquelle vous souhaitez associer le script que vous créez.
      • Pour une table distante dans une application incluse dans le périmètre, le nom est précédé d’un identificateur d’espace de noms et la chaîne st_ pour indiquer qu’elle est distante et qu’elle fait partie d’une application.
      • Pour une table distante dans l’application globale, le nom est précédé de la chaîne u_st_.
      Application Application associée à cette table distante. Si vous travaillez sur une application ou créez une table distante à partir d’un enregistrement d’application, le champ est défini par défaut sur cette application. Sinon, la valeur par défaut du champ est Global. Tous les enregistrements créés à partir de l’enregistrement de table, tels que les modules et les règles de sécurité, sont affectés par défaut à cette application.
      Actifs Option permettant d’activer le script que vous associez à la table distante. Vous pouvez avoir plusieurs définitions de script inactives pour une table distante, mais vous ne pouvez avoir qu’une seule définition de script active. Lorsque vous activez une définition de script, vous l’associez à la table distante afin de pouvoir récupérer et mettre en cache les données externes.
      Avancés Option permettant d’accéder aux paramètres de mise en cache et de modification avancés.
      Les paramètres de mise en cache indiquent comment la mise en cache de la mémoire doit fonctionner dans cette ServiceNow AI Platform table distante.
      Remarque :
      Seuls les utilisateurs avancés doivent définir les paramètres de mise en cache pour une table distante.
    4. Facultatif : Si vous avez sélectionné l’option Avancé , renseignez les champs de la section Avancé.
      Remarque :
      Par défaut, les données externes sont mises en cache dans la mémoire par l’utilisateur.
      Champ Description
      Cache TTL Durée de vie de mise en cache, exprimée en secondes, pendant laquelle les données externes sont mises en cache dans la mémoire pour cette définition de script de table distante. Par exemple, entrez 300 pour mettre en cache les données dans la mémoire pendant 5 minutes.

      La valeur par défaut est 0, ce qui signifie que les données ne sont pas mises en cache et sont récupérées à chaque fois. La valeur maximale est de 60 minutes (3 600 secondes).
      Niveau d'isolement du cache Mettez en cache les résultats de la requête pour chaque utilisateur ou pour tous les utilisateurs.
      • Cache par utilisateur : les résultats de la requête mise en cache doivent être spécifiques à l’utilisateur connecté. Il s’agit de la valeur par défaut.
      • Cache partagé du système : les résultats de la requête mise en cache doivent être les mêmes pour tous les utilisateurs.
      Capacité accrue Option permettant de sélectionner la capacité accrue pour prendre en charge plus de 1 000 lignes dans une table distante.
      Remarque :
      Si la taille des données récupérées à partir de la source externe est petite, utilisez la limite par défaut de 1 000 lignes dans une table distante pour réduire les temps d’requête. Vous pouvez sélectionner le champ Capacité accrue si la taille des données récupérées est importante et peut être moins performative.

      Ce champ n’est pas pris en charge si l’option Modifiable est sélectionnée.
      Modifiable Option permettant de prendre en charge la modification de la table distante et de sa source de données externe à partir de l’instance. Utilisez l’API v_record pour personnaliser les définitions de script pour l’insertion, la mise à jour et la suppression de données dans la table.
    5. Personnalisez les définitions de script suivantes à l’aide des API v_table, v_query et v_record .

      Pour en savoir plus sur ces API, reportez-vous aux sections v_table – Scoped, Global, v_query – Scoped, Global et v_record - Scoped, Global.

      Définition de script Description
      Requête

      La définition de script de requête récupère les données de la source externe pour les inclure dans la table distante. Dans la section Requête, personnalisez le script à l’aide des API v_table et v_query .

      Chaque fois qu’une liste contenant des données externes provenant d’une table distante est actualisée, les scripts de requête associés s’exécutent.

      (function executeQuery(v_table, v_query) {
     // Parameters:
     //      v_table - object to record response:
     //          v_table.addRow({ ... })                - adds a row to the result set.
     //              keys are the column names of the table definition.
     //              sys_id must be non-empty and uniquely identify each row.
     //                  the above rule will be strictly enforced for editable tables, and generate warnings for read-only tables.
     //                  sys_id will be supplied to the Update, and Delete scripts to specify the row's identity.
 
     //      v_query - the query definition:
     //          v_query.getEncodedQuery()              - encoded querystring
     //          v_query.getCondition(field)            - encoded querystring for the given field (includes field name, operator, and value)
     //          v_query.getParameter(field)            - parameter for the given field (only includes value for equality conditions)
     //          v_query.isGet()                        - whether the query is a single get by sys_id
     //          v_query.getSysId()                     - parameter for sys_id field
     //          v_query.isTextSearch()                 - whether the query contains a text query parameter
     //          v_query.getTextSearch()                - text search query parameter (internal field name 123TEXTQUERY321)
     //          v_query.getFirstRowWanted()            - the first row to include, don't use with caching
     //          v_query.getLastRowWanted()             - the last row to include, don't use with caching
     //          v_query.setLastErrorMessage(message)   - the message is visible from GlideRecord.getLastErrorMessage()
 
     // Sample code:
     //  try {
     //      retrieve-rows-from-external-system;     //      if (there-was-an-error) {
     //          var message = ...;     //          v_query.setLastErrorMessage(message);
     //          return;
     //      }
     //
     //      for (var row in rows) {
     //          v_table.addRow(row);
     //      }
     //  } catch (ex) {
     //      var message = ex.getMessage();
     //      v_query.setLastErrorMessage(message);
     //  }
 
  })(v_table, v_query);
      Insérer

      La définition de script d’insertion ajoute un enregistrement à la source externe. Cette définition de script n’est disponible que si vous avez sélectionné l’option Modifiable avancée. Dans la section Insérer, personnalisez le script à l’aide de l’API v_record .

      Chaque fois qu’un enregistrement est ajouté à une table distante, les scripts d’insertion associés s’exécutent.

      function executeInsert(v_record) {
     // Parameters:
     //      v_record is a map of field names and values containing the sys_id of the
     //              record and the fields that need to be inserted in the record on the
     //              remote system (source of data)
     
     //          v_record.<field_name>                   - fields in the remote table GlideRecord
     //          v_record.setLastErrorMessage(message)   - signal an error
 
     // Sample code:
     //  try {
     //      update-external-system;
     //      if (there-was-an-error) {
     //          var message = ...;
     //          v_record.setLastErrorMessage(message);
     //      }
     //  } catch (ex) {
     //      var message = ex.getMessage();
     //      v_record.setLastErrorMessage(message);
     //  }
  })(v_record);
      Mettre à jour

      La définition de script de mise à jour modifie un enregistrement dans la source externe. Cette définition de script n’est disponible que si vous avez sélectionné l’option Modifiable avancée. Dans la section Mettre à jour, personnalisez le script à l’aide de l’API v_record .

      Chaque fois qu’un enregistrement est mis à jour dans une table distante, les scripts de mise à jour associés s’exécutent.

      Remarque :
      Si plusieurs utilisateurs mettent à jour le même enregistrement en même temps, la valeur sur le système distant correspond au dernier appel de mise à jour exécuté.
      (function executeUpdate(v_record, v_changed_fields) {
     // Parameters:
     //    v_record - a map of field names and values containing the sys_id of the record
     //          v_record.<field_name>                   - fields in the remote table GlideRecord
     //          v_record.setLastErrorMessage(message)   - signal an error
     //    v_changed_fields - a map of field names and values containing the sys_id of the record
     //          v_changed_fields.<field_name>           - changed fields in the remote table GlideRecord
 
     // Sample code:
     //  try {
     //      update-external-system;
     //      if (there-was-an-error) {
     //          var message = ...;
     //          v_record.setLastErrorMessage(message);
     //      }
     //  } catch (ex) {
     //      var message = ex.getMessage();
     //      v_record.setLastErrorMessage(message);
     //  }
  })(v_record, v_changed_fields);
      Supprimer

      La définition de script de suppression supprime un enregistrement de la source externe. Cette définition de script n’est disponible que si vous avez sélectionné l’option Modifiable avancée. Dans la section Supprimer, personnalisez le script à l’aide de l’API v_record .

      Chaque fois qu’un enregistrement est supprimé d’une table distante, les scripts de suppression associés s’exécutent.

      (function executeDelete(v_record) {
     // Parameters:
     //      v_record - a map of field names and values containing (among others) the
     //              sys_id of the record that needs to be deleted on the remote system
     //          v_record.<field_name>                  - fields in the remote table GlideRecord
     //          v_record.setLastErrorMessage(message)   - signal an error
 
     // Sample code:
     //  try {
     //      update-external-system;
     //      if (there-was-an-error) {
     //          var message = ...;
     //          v_record.setLastErrorMessage(message);
     //      }
     //  } catch (ex) {
     //      var message = ex.getMessage();
     //      v_record.setLastErrorMessage(message);
     //  }
  })(v_record);
    6. Sélectionnez Soumettre.