リモートテーブルのスクリプト定義の作成

  • リリースバージョン: Zurich
  • 更新日 2025年07月31日
  • 所要時間：11分

    • リモートテーブルのスクリプトを定義して、外部データソースからデータを取得したり、外部ソースでデータを編集したりします。

    始める前に

    必要なロール:[スクリプティングを許可] 権限を持つdelegated_developerまたはアドミン

    このタスクについて

    ServiceNow AI Platformは、外部データソースに対してクエリスクリプトを実行することでリモートテーブルのデータを取得してキャッシュします。これにより、リモートテーブルを表示または変更できるようになります。また、この外部データのキャッシュ方法と、スクリプトを再実行するまでにメモリにデータをキャッシュしておく期間を指定することもできます。

    手順

    1. 移動先 すべて > システム定義 > リモートテーブル > 定義.
    2. [New (新規)] を選択します。
    3. フォームのフィールドに入力します。
      コントロール 説明
      名前

      選択したリモートテーブルに関連付けるために作成するスクリプトの名前。
      テーブル
      作成しているスクリプトを関連付けるリモートテーブルの名前。
      • スコープ対象のアプリケーションのリモートテーブルの場合、名前にはリモートであり、アプリケーションの一部であることを示す名前空間識別子と文字列 st_ がプリフィックスとして付きます。
      • グローバルアプリケーションのリモートテーブルの場合、名前には文字列 u_st_ がプリフィックスとして付きます。
      アプリケーション このリモートテーブルに関連付けられるアプリケーション。アプリケーションで作業している場合、またはアプリケーションレコードからリモートテーブルを作成している場合、フィールドはデフォルトでそのアプリケーションに設定されます。それ以外の場合は、このフィールドのデフォルトは [グローバル] です。モジュールやセキュリティルールなど、テーブルレコードから作成されたすべてのレコードは、デフォルトでこのアプリケーションに割り当てられます。
      Active (アクティブ) リモートテーブルに関連付けるスクリプトをアクティブ化するためのオプション。リモートテーブルに対して複数の非アクティブなスクリプト定義を設定できますが、有効なスクリプト定義は 1 つのみです。スクリプト定義を有効化するときは、外部データを取得してキャッシュできるように、それをリモートテーブルに関連付けます。
      詳細 キャッシュと編集の詳細設定にアクセスするオプション。
      キャッシュ設定は、このリモートテーブルの ServiceNow AI Platform でメモリキャッシュがどのように動作するかを指定します。
      注:
      上級ユーザーのみがリモートテーブルのキャッシュパラメーターを設定する必要があります。
    4. オプション: [詳細] オプションを選択した場合は、[詳細] セクションでフィールドに入力します。
      注:
      デフォルトでは、外部データはユーザーによってメモリにキャッシュされます。
      フィールド 説明
      キャッシュ TTL このリモートテーブルスクリプト定義のために外部データがメモリにキャッシュされるキャッシュ存続時間 (秒単位)。たとえば、メモリにデータを 5 分間キャッシュするには、300 と入力します。

      デフォルト値は 0 で、データはキャッシュされず、毎回取得されます。最大値は 60 分 (3600 秒) です。
      キャッシュ分離レベル 各ユーザーまたはすべてのユーザーのクエリ結果をキャッシュします。
      • ユーザーごとのキャッシュ:キャッシュされたクエリ結果は、ログインしているユーザーに固有のものである必要があります。これがデフォルト値です。
      • システム共有キャッシュ:キャッシュされたクエリ結果は、すべてのユーザーで同じである必要があります。
      拡張されたキャパシティ リモートテーブル内の 1000 行を超える行をサポートするように拡張されたキャパシティを選択するオプション。
      注:
      外部ソースから取得されるデータのサイズが小さい場合は、リモートテーブルで 1000 行のデフォルト制限を使用して、クエリ時間を最短にします。取得されたデータのサイズが大きく、パフォーマンスが低下する可能性がある場合は、[ 拡張されたキャパシティ ] フィールドを選択できます。

      [編集可能] が選択されている場合、このフィールドはサポートされません。
      編集可能 インスタンスからのリモートテーブルとその外部データソースの編集をサポートするオプション。v_record API を使用して、テーブルのデータを挿入、更新、および削除するためのスクリプト定義をカスタマイズします。
    5. v_table、v_query、および v_record API を使用して、次のスクリプト定義をカスタマイズします。

      これらの API の詳細については、「 v_table – Scoped, Global」、「 v_query – Scoped, Global」、および「 v_record - Scoped, Global」を参照してください。

      スクリプト定義 説明
      クエリ

      クエリスクリプト定義は、リモートテーブルに含めるデータを外部ソースから取得します。[クエリ] セクションで、 v_table API と v_query API を使用してスクリプトをカスタマイズし ます 。

      リモートテーブルの外部データを含むリストが更新されるたびに、関連するクエリスクリプトが実行されます。

      (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);
      挿入

      挿入スクリプト定義は、外部ソースにレコードを追加します。このスクリプト定義は、詳細な 編集可能 オプションを選択した場合にのみ使用できます。[挿入] セクションで、 v_record API を使用してスクリプトをカスタマイズします。

      レコードがリモートテーブルに追加されるたびに、関連する挿入スクリプトが実行されます。

      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);
      更新

      更新スクリプト定義は、外部ソースのレコードを変更します。このスクリプト定義は、詳細な 編集可能 オプションを選択した場合にのみ使用できます。[更新] セクションで、 v_record API を使用してスクリプトをカスタマイズします。

      リモートテーブルでレコードが更新されるたびに、関連する更新スクリプトが実行されます。

      注:
      複数のユーザーが同じレコードを同時に更新する場合、リモートシステムの値は最後に実行された更新呼び出しの値になります。
      (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);
      削除

      削除スクリプト定義により、外部ソースからレコードが削除されます。このスクリプト定義は、詳細な 編集可能 オプションを選択した場合にのみ使用できます。[削除] セクションで、 v_record API を使用してスクリプトをカスタマイズします。

      リモートテーブルからレコードが削除されるたびに、関連する削除スクリプトが実行されます。

      (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. [Submit (送信)] を選択します。