---
sourceDocument: Xanadu API リファレンス
sourceDocumentLink: https://www.servicenow.com/docs/r/ja-JP/xanadu/api-reference

 Release :

    - xanadu

ft:locale :

    - ja-JP

ft:publication_title :

    - Xanadu API リファレンス

ft:clusterId :

    - crapiref

bundleId :

    - crapiref

workflow :

    - Creator


---

# spUtil - クライアント

# spUtil - クライアント {#ariaid-title1}

* リリースバージョン: Xanadu
* 
* 更新日 2024年08月01日
* 
* ![](https://www.servicenow.com/docs/portal-asset/ico-clock) 所要時間：12分

spUtil API は、サービスポータルウィジェットクライアントスクリプトで一般的な機能を実行するためのユーティリティメソッドを提供します。  
これらの機能には、次のものが含まれます。

* 通知エラーメッセージを表示します。 [spUtil - addErrorMessage(文字列 message)](https://www.servicenow.com/docs/XFo_X8tQkF6RDEfW9t0~wg#SPU-addErrorMessage_S "通知エラーメッセージを表示します。")
* 通知情報メッセージを表示します。 [spUtil - addInfoMessage(文字列 message)](https://www.servicenow.com/docs/XFo_X8tQkF6RDEfW9t0~wg#SPU-addInfoMessage_S "通知情報メッセージを表示します。")
* 簡単な通知メッセージを表示します。 [spUtil - addTrivialMessage(文字列 message)](https://www.servicenow.com/docs/XFo_X8tQkF6RDEfW9t0~wg#SPU-addTrivialMessage_S "些細な通知メッセージを表示します。")
* 一意の識別子を作成します。 [spUtil - createUid()](https://www.servicenow.com/docs/XFo_X8tQkF6RDEfW9t0~wg#SPU-createUid "一意の識別子を作成します。")
* 変数を使用して文字列を書式設定します。 [spUtil - format(文字列 template, オブジェクト data)](https://www.servicenow.com/docs/XFo_X8tQkF6RDEfW9t0~wg#SPU-format_S_O "変数を含む文字列を書式設定します。")
* ウィジェットクライアントスクリプトにウィジェットモデルを埋め込みます。 [spUtil - get(文字列 widgetId オブジェクト data)](https://www.servicenow.com/docs/XFo_X8tQkF6RDEfW9t0~wg#SPU-get_S "ウィジェットクライアントスクリプトにウィジェットモデルを埋め込みます。")
* API 呼び出しに使用するすべてのヘッダーを取得します。 [spUtil - getHeaders()](https://www.servicenow.com/docs/XFo_X8tQkF6RDEfW9t0~wg#SPU-getHeaders "API 呼び出しに使用するすべてのヘッダーを取得します。")
* 完全なホストドメインを返します。 [spUtil - getHost()](https://www.servicenow.com/docs/XFo_X8tQkF6RDEfW9t0~wg#SPU-getHost "完全なホストドメインを返します。")
* 設定名を渡して、ユーザー設定応答でコールバックを実行します。 [spUtil - getPreference(文字列 preference, 関数 callback)](https://www.servicenow.com/docs/XFo_X8tQkF6RDEfW9t0~wg#SPU-getPreference "設定名を渡すことにより、ユーザー設定応答でコールバックを実行します。")
* 現在のサービスポータルの URL 情報を返します。 [spUtil - getURL()](https://www.servicenow.com/docs/XFo_X8tQkF6RDEfW9t0~wg#SPU-getURL "現在のサービスポータルの URL 情報を返します。")
* 現在のクライアントがモバイルデバイスかどうかを確認します。 [spUtil - isMobile()](https://www.servicenow.com/docs/XFo_X8tQkF6RDEfW9t0~wg#SPU-isMobile "現在のクライアントがモバイルデバイスかどうかを確認します。")
* 指定された文字列内のカンマ区切りの属性を解析します。 [spUtil - parseAttributes(文字列 attributes)](https://www.servicenow.com/docs/XFo_X8tQkF6RDEfW9t0~wg#SPU-parseAttributes "指定された文字列内のカンマ区切りの属性を解析します。")
* テーブルまたはフィルターの更新を監視し、コールバック関数から値を返します。 [spUtil - recordWatch(オブジェクト $scope, 文字列 table, 文字列 filter, 関数 callback)](https://www.servicenow.com/docs/XFo_X8tQkF6RDEfW9t0~wg#SPU-recordWatch_O_S_S_F "テーブルまたはフィルターの更新を監視し、コールバック関数から値を返します。")
* サーバーを呼び出し、現在の オプション と データを サーバーの応答に置き換えます。 [spUtil - refresh(オブジェクト $scope)](https://www.servicenow.com/docs/XFo_X8tQkF6RDEfW9t0~wg#SPU-refresh_O "サーバーを呼び出し、サーバーの応答から取得された現在のオプションとデータを置き換えます。")
* 指定されたセレクターを持つ要素まで、指定された期間にわたってスクロールします。 [spUtil - scrollTo(文字列 selector, 数字 time)](https://www.servicenow.com/docs/XFo_X8tQkF6RDEfW9t0~wg#SPU-scrollTo "指定されたセレクターを持つ要素まで、指定された期間にわたってスクロールします。")
* ヘッダーのブレッドクラムを更新します。 [spUtil - setBreadCrumb(オブジェクト $scope, 配列ブレッドクラム)](https://www.servicenow.com/docs/XFo_X8tQkF6RDEfW9t0~wg#SPU-setBreadCrumb "ヘッダーのブレッドクラムを更新します。")
* ユーザー初期設定を設定します。 [spUtil - setPreference(文字列設定, 文字列値)](https://www.servicenow.com/docs/XFo_X8tQkF6RDEfW9t0~wg#SPU-setPreference "ユーザー設定を設定します。")
* 検索ページを更新します。 [spUtil - setSearchPage(文字列 searchPage)](https://www.servicenow.com/docs/XFo_X8tQkF6RDEfW9t0~wg#SPU-setSearchPage "検索ページを更新します。")
* 指定されたスコープ内のサーバー上のデータオブジェクトを更新します。 [spUtil - update(オブジェクト $scope)](https://www.servicenow.com/docs/XFo_X8tQkF6RDEfW9t0~wg#SPU-update_O "指定されたスコープ内にあるサーバー上のデータオブジェクトを更新します。")

ウィジェットの詳細については、「 [サービスポータルウィジェット」](https://www.servicenow.com/docs/access?context=service-portal-widgets&version=xanadu&pubname=xanadu-platform-user-interface&ft:locale=en-US)を参照してください。

## spUtil - addErrorMessage(文字列 message) {#ariaid-title2}

通知エラーメッセージを表示します。
{#SPU-addErrorMessage_S__table_yjp_zpz_31b__entry__3}

| 名前 | タイプ | 説明 |
|-|-|-|
| message | 文字列 | 表示するエラー メッセージ。 |
[表 : 1. パラメーター]

{#SPU-addErrorMessage_S__table_yjp_zpz_31b} {#SPU-addErrorMessage_S__table_zjp_zpz_31b__entry__2}

| タイプ | 説明 |
|-|-|
| なし |   |
[表 : 2. 返される内容]

{#SPU-addErrorMessage_S__table_zjp_zpz_31b}  

    spUtil.addErrorMessage("There has been an error processing your request")

## spUtil - addInfoMessage(文字列 message) {#ariaid-title3}

通知情報メッセージを表示します。
{#SPU-addInfoMessage_S__table_b2m_bqz_31b__entry__3}

| 名前 | タイプ | 説明 |
|-|-|-|
| message | 文字列 | 表示するメッセージ。 |
[表 : 3. パラメーター]

{#SPU-addInfoMessage_S__table_b2m_bqz_31b} {#SPU-addInfoMessage_S__table_c2m_bqz_31b__entry__2}

| タイプ | 説明 |
|-|-|
| なし |   |
[表 : 4. 返される内容]

{#SPU-addInfoMessage_S__table_c2m_bqz_31b}  

    spUtil.addInfoMessage("Your order has been placed")

## spUtil - addTrivialMessage(文字列 message) {#ariaid-title4}

些細な通知メッセージを表示します。
些細なメッセージはしばらくすると消えます。
{#SPU-addTrivialMessage_S__table_kcx_dqz_31b__entry__3}

| 名前 | タイプ | 説明 |
|-|-|-|
| message | 文字列 | 表示するメッセージ。 |
[表 : 5. パラメーター]

{#SPU-addTrivialMessage_S__table_kcx_dqz_31b} {#SPU-addTrivialMessage_S__table_lcx_dqz_31b__entry__2}

| タイプ | 説明 |
|-|-|
| なし |   |
[表 : 6. 返される内容]

{#SPU-addTrivialMessage_S__table_lcx_dqz_31b}  

    spUtil.addTrivialMessage("Thanks for your order")

## spUtil - createUid() {#ariaid-title5}

一意の識別子を作成します。
{#SPU-createUid__table_ccv_cbr_t2b__entry__3}

| 名前 | タイプ | 説明 |
|-|-|-|
| なし |   |   |
[表 : 7. パラメーター]

{#SPU-createUid__table_ccv_cbr_t2b} {#SPU-createUid__table_dcv_cbr_t2b__entry__2}

| タイプ | 説明 |
|-|-|
| 文字列 | 一意の 32 文字の ID。 |
[表 : 8. 返される内容]

{#SPU-createUid__table_dcv_cbr_t2b}

## spUtil - get(文字列 widgetId オブジェクト data) {#ariaid-title6}

ウィジェットクライアントスクリプトにウィジェットモデルを埋め込みます。
コールバック関数が完全なウィジェットモデルを返します。ウィジェットの詳細については、「 [サービスポータルウィジェット」](https://www.servicenow.com/docs/access?context=service-portal-widgets&version=xanadu&pubname=xanadu-platform-user-interface&ft:locale=en-US)を参照してください。
{#SPU-get_S__table_bcy_fqz_31b__entry__3}

| 名前 | タイプ | 説明 |
|-|-|-|
| widgetId | 文字列 | 埋め込むウィジェットのウィジェット ID または sys_id。 |
| data | オブジェクト | オプション。ウィジェットモデルに渡すパラメーターの名前/値ペア。 |
[表 : 9. パラメーター]

{#SPU-get_S__table_bcy_fqz_31b} {#SPU-get_S__table_ccy_fqz_31b__entry__2}

| タイプ | 説明 |
|-|-|
| オブジェクト | 埋め込みウィジェットのモデル。 |
[表 : 10. 返される内容]

{#SPU-get_S__table_ccy_fqz_31b}  
データを渡さずに。

    spUtil.get("widget-cool-clock").then(function(response) {
      c.coolClock = response;
    });

データが渡されました。

    spUtil.get('pps-list-modal', {title: c.data.editAllocations, 
      table: 'resource_allocation', 
      queryString: 'GROUPBYuser^resource_plan=' + c.data.sysId, 
      view: 'resource_portal_allocations' }).then(function(response) {
        var formModal = response;
        c.allocationListModal = response;
      });  	

## spUtil - getHeaders() {#ariaid-title7}

API 呼び出しに使用するすべてのヘッダーを取得します。
{#SPU-getHeaders__table_dns_ldr_t2b__entry__3}

| 名前 | タイプ | 説明 |
|-|-|-|
| なし |   |   |
[表 : 11. パラメーター]

{#SPU-getHeaders__table_dns_ldr_t2b} {#SPU-getHeaders__table_ens_ldr_t2b__entry__2}

| タイプ | 説明 |
|-|-|
| オブジェクト | API 呼び出しに使用するすべてのヘッダー。 |
[表 : 12. 返される内容]

{#SPU-getHeaders__table_ens_ldr_t2b}

## spUtil - getHost() {#ariaid-title8}

完全なホストドメインを返します。
{#SPU-getHost__table_olb_vkr_t2b__entry__3}

| 名前 | タイプ | 説明 |
|-|-|-|
| なし |   |   |
[表 : 13. パラメーター]

{#SPU-getHost__table_olb_vkr_t2b} {#SPU-getHost__table_plb_vkr_t2b__entry__2}

| タイプ | 説明 |
|-|-|
| 文字列 | 完全なホストのドメイン (例：`hi.servicenow.com`) |
[表 : 14. 返される内容]

{#SPU-getHost__table_plb_vkr_t2b}

## spUtil - getPreference(文字列 preference, 関数 callback) {#ariaid-title9}

設定名を渡すことにより、ユーザー設定応答でコールバックを実行します。
{#SPU-getPreference__table_rvb_34r_t2b__entry__3}

| 名前 | タイプ | 説明 |
|-|-|-|
| preference | 文字列 | 設定の名前。 |
| コールバック | 関数 | コールバック関数を定義します。 |
[表 : 15. パラメーター]

{#SPU-getPreference__table_rvb_34r_t2b} {#SPU-getPreference__table_svb_34r_t2b__entry__2}

| タイプ | 説明 |
|-|-|
| なし |   |
[表 : 16. 返される内容]

{#SPU-getPreference__table_svb_34r_t2b}

## spUtil - getURL() {#ariaid-title10}

現在のサービスポータルの URL 情報を返します。
{#SPU-getURL__table_sbh_dls_t2b__entry__3}

| 名前 | タイプ | 説明 |
|-|-|-|
| なし |   |   |
[表 : 17. パラメーター]

{#SPU-getURL__table_sbh_dls_t2b} {#SPU-getURL__table_tbh_dls_t2b__entry__2}

| タイプ | 説明 |
|-|-|
| 文字列 | 現在のサービスポータル URL。 |
[表 : 18. 返される内容]

{#SPU-getURL__table_tbh_dls_t2b}

## spUtil - format(文字列 template, オブジェクト data) {#ariaid-title11}

変数を含む文字列を書式設定します。
このメソッドは、文字列連結の代わりに使用します。
{#SPU-format_S_O__table_yrh_hqz_31b__entry__3}

| 名前 | タイプ | 説明 |
|-|-|-|
| template | 文字列 | 変数代替の値を含む文字列テンプレート。 |
| データ | オブジェクト | テンプレート文字列で定義された変数の値を含むオブジェクト。 |
[表 : 19. パラメーター]

{#SPU-format_S_O__table_yrh_hqz_31b} {#SPU-format_S_O__table_zrh_hqz_31b__entry__2}

| タイプ | 説明 |
|-|-|
| 文字列 | 変数の命名法の代わりに変数値を含む文字列。 |
[表 : 20. 返される内容]

{#SPU-format_S_O__table_zrh_hqz_31b}  

    spUtil.format('An error ocurred: {error} when loading {widget}', {error: '404', widget: 'sp-widget'})

出力:

    'An error occurred: 404 when loading sp-widget'

## spUtil - isMobile() {#ariaid-title12}

現在のクライアントがモバイルデバイスかどうかを確認します。
{#SPU-isMobile__table_gz2_pcd_v2b__entry__3}

| 名前 | タイプ | 説明 |
|-|-|-|
| なし |   |   |
[表 : 21. パラメーター]

{#SPU-isMobile__table_gz2_pcd_v2b} {#SPU-isMobile__table_hz2_pcd_v2b__entry__2}

| タイプ | 説明 |
|-|-|
| ブール | 現在のクライアントがモバイルデバイスかどうかを示すフラグ。 有効な値： * true:現在のクライアントはモバイルデバイスです。 * false:現在のクライアントはモバイルデバイスではありません。 {#SPU-isMobile__ul_fpx_gsv_fvb} |
[表 : 22. 返される内容]

{#SPU-isMobile__table_hz2_pcd_v2b}

## spUtil - parseAttributes(文字列 attributes) {#ariaid-title13}

指定された文字列内のカンマ区切りの属性を解析します。
{#SPU-parseAttributes__table_jkb_tvm_w2b__entry__3}

| 名前 | タイプ | 説明 |
|-|-|-|
| attributes | 文字列 | 辞書レコードの \[属性\] フィールドなど、カンマ区切りの属性を含む文字列。 |
[表 : 23. パラメーター]

{#SPU-parseAttributes__table_jkb_tvm_w2b} {#SPU-parseAttributes__table_kkb_tvm_w2b__entry__2}

| タイプ | 説明 |
|-|-|
| アレイ | 解析された属性を含むオブジェクトのアレイ。 |
[表 : 24. 返される内容]

{#SPU-parseAttributes__table_kkb_tvm_w2b}  

    function getRefQualElements() {
      var refQualElements = [];
      if (field && field.attributes && field.attributes.indexOf('ref_qual_elements') > -1) {
        var attributes = spUtil.parseAttributes(field.attributes);
        refQualElements = attributes['ref_qual_elements'].split(';');
      }
      return refQualElements;
    }

## spUtil - recordWatch(オブジェクト $scope, 文字列 table, 文字列 filter, 関数 callback) {#ariaid-title14}

テーブルまたはフィルターの更新を監視し、コールバック関数から値を返します。
ウィジェット開発者がリアルタイムでテーブルの更新に応答できるようになります。例えば、recordWatch() を使用すると、簡易リストウィジェットでデータテーブルの変更をリスンできます。レコードが追加、削除、または更新されると、ウィジェットが自動的に更新されます。  
注:  
`$scope` 引数を recordWatch() 関数に渡すときに、クライアントスクリプト関数のパラメーターに `$scope` を挿入します。
{#SPU-recordWatch_O_S_S_F__table_vys_mqz_31b__entry__3}

| 名前 | タイプ | 説明 |
|-|-|-|
| $scope | オブジェクト | コールバック関数によって更新されたデータオブジェクトのスコープ。 |
| table | 文字列 | 監視対象テーブル。 |
| filter | 文字列 | 監視対象フィールドのフィルター。 |
| callback | 関数 | オプション。コールバック関数を定義するパラメーター。 |
[表 : 25. パラメーター]

{#SPU-recordWatch_O_S_S_F__table_vys_mqz_31b} {#SPU-recordWatch_O_S_S_F__table_wys_mqz_31b__entry__2}

| タイプ | 説明 |
|-|-|
| Promise | コールバック関数の戻り値。 |
[表 : 26. 返される内容]

{#SPU-recordWatch_O_S_S_F__table_wys_mqz_31b}  

    //A simple recordWatch function.
    spUtil.recordWatch($scope, "live_profile", "sys_id=" + liveProfileId);

    //In a widget client script
    function(spUtil, $scope) {
      /* widget controller */
      var c =this;

      // Registers a listener on the incident table with the filter active=true, 
      // meaning that whenever something changes on that table with that filter, 
      // the callback function is executed.    
      // The callback function takes a single parameter 'response', which contains 
      // the property 'data'. The 'data' property contains information about the changed record. 
      spUtil.recordWatch($scope, "incident", "active=true", function(response) {
            
        // Returns the data inserted or updated on the table 
        console.log(response.data);   
        
        });
    }

## spUtil - refresh(オブジェクト $scope) {#ariaid-title15}

サーバーを呼び出し、サーバーの応答から取得された現在のオプションとデータを置き換えます。
`spUtil.refresh()` の呼び出しは `server.refresh()` の呼び出しに類似しています。ただし、`spUtil.refresh()`を呼び出すと、$scope オブジェクトを定義できます。
{#SPU-refresh_O__table_p2k_kqz_31b__entry__3}

| 名前 | タイプ | 説明 |
|-|-|-|
| $scope | オブジェクト | 更新のために定義されたスコープ。 |
[表 : 27. パラメーター]

{#SPU-refresh_O__table_p2k_kqz_31b} {#SPU-refresh_O__table_q2k_kqz_31b__entry__2}

| タイプ | 説明 |
|-|-|
| オブジェクト | オプションとデータオブジェクトが更新されました。 |
[表 : 28. 返される内容]

{#SPU-refresh_O__table_q2k_kqz_31b}

## spUtil - scrollTo(文字列 selector, 数字 time) {#ariaid-title16}

指定されたセレクターを持つ要素まで、指定された期間にわたってスクロールします。
{#SPU-scrollTo__table_drd_wzp_v2b__entry__3}

| 名前 | タイプ | 説明 |
|-|-|-|
| selector | 文字列 | スクロール先のセレクター。 |
| 時刻 | 番号 | 指定されたセレクターへのスクロールにかかる時間。 単位：ミリ秒 |
[表 : 29. パラメーター]

{#SPU-scrollTo__table_drd_wzp_v2b} {#SPU-scrollTo__table_erd_wzp_v2b__entry__2}

| タイプ | 説明 |
|-|-|
| なし |   |
[表 : 30. 返される内容]

{#SPU-scrollTo__table_erd_wzp_v2b}

## spUtil - setBreadCrumb(オブジェクト $scope, 配列ブレッドクラム) {#ariaid-title17}

ヘッダーのブレッドクラムを更新します。
{#SPU-setBreadCrumb__table_sqx_jkr_v2b__entry__3}

| 名前 | タイプ | 説明 |
|-|-|-|
| $scope | オブジェクト | テーブルに定義されたスコープ。 |
| ブレッドクラム | アレイ | ブレッドクラムフィルターの作成に使用される条件。 |
[表 : 31. パラメーター]

{#SPU-setBreadCrumb__table_sqx_jkr_v2b} {#SPU-setBreadCrumb__table_tqx_jkr_v2b__entry__2}

| タイプ | 説明 |
|-|-|
| なし |   |
[表 : 32. 返される内容]

{#SPU-setBreadCrumb__table_tqx_jkr_v2b}

## spUtil - setPreference(文字列設定, 文字列値) {#ariaid-title18}

ユーザー設定を設定します。
{#SPU-setPreference__table_m1m_1hl_w2b__entry__3}

| 名前 | タイプ | 説明 |
|-|-|-|
| 県 | 文字列 | 初期設定名 |
| 値 | 文字列 | 設定値 |
[表 : 33. パラメーター]

{#SPU-setPreference__table_m1m_1hl_w2b} {#SPU-setPreference__table_n1m_1hl_w2b__entry__2}

| タイプ | 説明 |
|-|-|
| なし |   |
[表 : 34. 返される内容]

{#SPU-setPreference__table_n1m_1hl_w2b}

## spUtil - setSearchPage(文字列 searchPage) {#ariaid-title19}

検索ページを更新します。
{#SPU-setSearchPage__table_hm4_v4l_w2b__entry__3}

| 名前 | タイプ | 説明 |
|-|-|-|
| searchPage | 文字列 | 検索ページの名前。 |
[表 : 35. パラメーター]

{#SPU-setSearchPage__table_hm4_v4l_w2b} {#SPU-setSearchPage__table_im4_v4l_w2b__entry__2}

| タイプ | 説明 |
|-|-|
| なし |   |
[表 : 36. 返される内容]

{#SPU-setSearchPage__table_im4_v4l_w2b}

## spUtil - update(オブジェクト $scope) {#ariaid-title20}

指定されたスコープ内にあるサーバー上のデータオブジェクトを更新します。
このメソッドは `server.update()` に似ていますが、渡すスコープを定義する $scope パラメーターが含まれています。
{#SPU-update_O__table_hpd_4qz_31b__entry__3}

| 名前 | タイプ | 説明 |
|-|-|-|
| $scope | オブジェクト | 更新のために定義されたスコープ。 |
[表 : 37. パラメーター]

{#SPU-update_O__table_hpd_4qz_31b} {#SPU-update_O__table_ipd_4qz_31b__entry__2}

| タイプ | 説明 |
|-|-|
| オブジェクト | 更新されたデータオブジェクト。 |
[表 : 38. 返される内容]

{#SPU-update_O__table_ipd_4qz_31b}  
次の例には、ステータスフィールドの変更を監視する P1 ウィジェットが含まれています。フィルターを使用してすべてのアクティブな P1 を監視して、データを更新するかどうかの判断をコールバック関数に許可します。data.changes プロパティには更新されたフィールドのアレイが入っています。フィールドのステータスが変更されると、ウィジェット内のデータが更新されます。

    var q = "priority=1^active=true^EQ";
    spUtil.recordWatch($scope, "incident", q, function(event, data) {
       if (data.changes.includes("state")) { // only update if state was updated.
          spUtil.update($scope);
       }
    });