CMDBQBScopedScriptableAPI :スコープ指定

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

    • サーバーサイドスクリプトで 構成管理データベース (CMDB) クエリビルダー操作を実行するメソッドを提供します。

    この API は、 CMDBQueryBuilderAPI - グローバル に相当するスコープです。

    この API は、スコープ対象アプリの構成管理プラグイン (com.snc.cmdb.scoped) を必要とし、 sn_cmdb 名前空間内で提供されます。

    CMDBクエリビルダーの詳細については、「CMDB Query Builder」を参照してください。

    CMDBQBScopedScriptableAPI - createReport(文字列 savedQueryId, 文字列 savedQueryName)

    構成管理データベース (CMDB)クエリビルダークエリの結果を表示し、レポートの URL を返すレポートを作成します。

    表 : 1. パラメーター
    名前 タイプ 説明
    savedQueryId 文字列 レポートに使用するクエリのSys_id。

    クエリ名が指定されている場合、このパラメーターは必要ありません。

    テーブル:保存済みクエリ [qb_saved_query]
    savedQueryName 文字列 レポートに使用するクエリの名前。

    クエリー sys_idが指定されている場合、このパラメーターは必要ありません。

    テーブル:保存済みクエリ [qb_saved_query] テーブルの [名前 ] フィールドに保存されます。
    表 : 2. 戻り値
    タイプ 説明
    オブジェクト 作成されたレポートとエラーの詳細。
    {
  "error": "String",
  "message": "String",
  "status": "String"
}
    <Object>。エラー エラーコード。レポートの作成に失敗した場合、または無効な入力パラメーターが指定された場合に返されます。

    考えられるエラー:

    • USER_NOT_AUTHORIZED_EXCEPTION
    • INVALID_PARAM
    • QUERY_SYS_ID_INVALID
    • REPORT_INELIGIBLE

    データタイプ：文字列
    <Object>.message レポート作成の成功または失敗に関する詳細を含むメッセージ。
    可能なメッセージ:
    • <report-url>
    • ユーザーには CMDBQueryBuilder クエリレポートを作成する権限がありません
    • 無効なパラメーター。保存済みクエリの有効な sysId または有効な名前のいずれかを指定してください
    • queryId が無効です。有効な保存済みクエリ ID を指定してください
    • クエリには、レポートを作成するために少なくとも 1 回実行されるスケジュールが必要です。
    「Schedule a CMDB query」も参照してください。

    データタイプ：文字列
    <Object>.status ステータスコード。更新が成功すると返されます。

    値: 成功

    データタイプ：文字列

    この例では、保存済みクエリ名を渡してレポートを作成する方法を示します。

    var queryReport = sn_cmdb.CMDBQBScopedScriptableAPI.createReport('','CMDBQueryTest1');

gs.info(JSON.stringify(queryReport, null, 2));

    出力:

    {
   "message":"\/sys_report_template.do?sysparm_report_source_id=6d299cf81bbd4210bccf42a3b24bcb7a&sysparm_type=list&sysparm_title=CMDBQueryTest1&sysparm_source_type=source&sysparm_from_list=true&sysparm_chart_size=large&sysparm_manual_labor=true",
   "status":"success"
}

    この例は、クエリsys_idと名前の両方がメソッド呼び出しにない場合のエラーを示しています。

    var queryReport = sn_cmdb.CMDBQBScopedScriptableAPI.createReport('', '');

gs.info(JSON.stringify(queryReport, null, 2));

    出力:

    {
   "error":"INVALID_PARAM",
   "message":"Invalid Parameters. Please provide either a valid sysId or a valid name of a saved query"
}

    CMDBQBScopedScriptableAPI - deleteQuery(文字列 savedQueryId, 文字列 savedQueryName)

    構成管理データベース (CMDB)クエリビルダークエリを削除します。

    表 : 3. パラメーター
    名前 タイプ 説明
    savedQueryId 文字列 削除するクエリのSys_id。

    クエリ名が指定されている場合、このパラメーターは空の文字列として指定できます。

    テーブル:保存済みクエリ [qb_saved_query]
    savedQueryName 文字列 削除するクエリの名前。

    クエリー sys_idが指定されている場合、このパラメーターは必要ありません。

    テーブル:保存済みクエリ [qb_saved_query] テーブルの [名前 ] フィールドに保存されます。
    表 : 4. 戻り値
    タイプ 説明
    オブジェクト 削除されたクエリとエラーの詳細。
    {
  "error": "String",
  "message": "String",
  "status": "String"
}
    <Object>。エラー エラーコード。削除操作が失敗した場合、または無効な入力パラメーターが指定された場合に返されます。

    考えられるエラー:

    • USER_NOT_AUTHORIZED_EXCEPTION
    • INVALID_PARAM
    • QUERY_DELETE_FAILED

    データタイプ：文字列
    <Object>.message 削除操作の成功または失敗に関する詳細を含むメッセージ。

    可能なメッセージ:

    • 保存済みクエリが正常に削除されました
    • ユーザーには CMDBQueryBuilder クエリの削除権限がありません
    • 無効なパラメーター。保存済みクエリの有効な sysId または有効な名前のいずれかを指定してください
    • 指定された保存済みクエリの削除に失敗しました

    データタイプ：文字列
    <Object>.status ステータスコード。更新が成功すると返されます。

    値: 成功

    データタイプ：文字列

    この例では、クエリ名を渡して保存済みクエリを削除する方法を示します。

    gs.info(JSON.stringify(sn_cmdb.CMDBQBScopedScriptableAPI.deleteQuery('', 'CMDBQueryTest1')));

    出力:

    {
   "message":"Successfully deleted the saved query",
   "status":"success"
}

    この例は、クエリsys_idと名前の両方がメソッド呼び出しにない場合のエラーを示しています。

    gs.info(JSON.stringify(sn_cmdb.CMDBQBScopedScriptableAPI.deleteQuery('', '')));

    出力:

    {
   "error":"INVALID_PARAM",
   "message":"Invalid Parameters. Please provide either a valid sysId or a valid name of a saved query"
}

    CMDBQBScopedScriptableAPI:getSavedQueryExecutionDetails(String savedQueryName, Boolean executeQuery, Number timeout)

    構成管理データベース (CMDB)クエリビルダークエリの実行の詳細を返します。

    必要に応じて、クエリを実行して、現在の実行の詳細を返すこともできます。

    クエリの実行中にタイムアウトまたはメモリの問題が発生した場合は、クエリのバッチサイズを微調整して、これらの問題を軽減することができます。詳細については、「 クエリ ビルダの保存済みクエリのバッチ サイズ」を参照してください。

    表 : 5. パラメーター
    名前 タイプ 説明
    savedQueryName 文字列 実行の詳細を取得するクエリの名前。

    テーブル:保存済みクエリ [qb_saved_query] テーブルの [名前 ] フィールド。
    executeQuery ブーリアン オプション。指定されたクエリを実行するかどうかを示すフラグ。

    有効な値：

    • true：指定されたクエリーを実行し、実行の詳細を返します。
    • false:指定されたクエリを実行しません。クエリの最新の実行の詳細を返します。

    デフォルト値：False
    タイムアウト 番号 オプション。デフォルトのクエリー実行タイムアウト制限の 5 分を上書きする整数値。

    単位：秒

    デフォルト：5 分
    表 : 6. 返される内容
    タイプ 説明
    オブジェクト クエリの実行とエラーの詳細。
    {
  "error": "String",
  "execution_batch_size": Number,
  "message": "String",
  "query_id": "String",
  "status": "String",
  "table_name": "String"
}
    <Object>。エラー エラーコード。クエリー実行が失敗した場合、または指定されたクエリーが見つからない場合に返されます。

    考えられるエラー:

    • QUERY_EXECUTION_NOT_FOUND
    • QUERY_NOT_FOUND
    • QUERY_EXECUTION_FAILED
    • USER_NOT_AUTHORIZED_EXCEPTION

    データタイプ：文字列
    <Object>.execution_batch_size クエリの実行に割り当てられたバッチサイズ 100。この値は、 executeQuery パラメーターが true の場合にのみ返されます。「Batch size for CMDB Query Builder queries」も参照してください。

    データタイプ：数値
    <Object>.message エラーコードの詳細を含むメッセージ。クエリー実行が失敗した場合、または指定されたクエリーが見つからない場合に返されます。

    可能なメッセージ:

    • クエリ実行の詳細が見つかりません。クエリを実行してください。
    • 指定された保存済みクエリが見つかりません。保存済みクエリの名前を渡していることを確認してください。
    • クエリの実行に失敗しました。有効なクエリを使用してください。
    • ユーザーには CMDBQueryBuilder クエリを実行する権限がありません。

    データタイプ：文字列
    <Object>.query_id クエリ実行のSys_id。

    データタイプ：文字列

    テーブル:クエリステータス [qb_query_status]
    <Object>.status クエリー実行のステータス。
    • COMPLETE：実行が完了しました。
    • FAILED：クエリー実行中にエラーが発生しました。
    • TIME_OUT：クエリー実行がタイムアウトしました。
    • MAX_LIMIT：返される結果の最大数に達しました。

    データタイプ：文字列
    <Object>.table_name クエリ実行の詳細を含むテーブルの名前。

    データタイプ：文字列

    この例では、保存済みクエリを実行し、クエリ実行タイムアウト値を 10 分に設定する方法を示します。

    var savedQuery = sn_cmdb.CMDBQBScopedScriptableAPI.getSavedQueryExecutionDetails('CMDBQueryTest1', true, 600);

gs.info(JSON.stringify(savedQuery, null, 2));

    出力:

    {
   "execution_batch_size": 100,
   "query_id":"024fd53a7773330033b5270bba106141",
   "table_name":"u_cmdb_qb_result_598918aacb4dbf3f1a8dcf03fce6a5d57151a4e2",
   "status":COMPLETE
}

    CMDBQBScopedScriptableAPI - saveQuery(String savedQueryName, String queryJson)

    構成管理データベース (CMDB)クエリビルダーのクエリを保存し、保存されたクエリのsys_idを返します。

    表 : 7. パラメーター
    名前 タイプ 説明
    savedQueryName 文字列 クエリを保存する名前。

    テーブル:保存済みクエリ [qb_saved_query] テーブルの [名前 ] フィールドに保存されます。
    クエリ JSON 文字列 クエリを定義する JSON。

    テーブル:保存済みクエリ [qb_saved_query] テーブルの [クエリ ] フィールドに保存されます。
    表 : 8. 戻り値
    タイプ 説明
    オブジェクト 保存済みクエリとエラーの詳細を含むオブジェクト。
    {
   "error": "String",
   "message": "String",
   "status": "String"
}
    <Object>。エラー エラーコード。保存操作が失敗した場合、または無効な入力パラメーターが指定された場合に返されます。

    考えられるエラー:

    • USER_NOT_AUTHORIZED_EXCEPTION
    • QUERY_NAME_INVALID
    • QUERY_INVALID
    • QUERY_EXISTS_ALREADY
    • QUERY_SAVE_FAILED

    データタイプ：文字列
    <Object>.message 保存操作の成功または失敗に関する詳細を含むメッセージ。

    可能なメッセージ:

    • sysId <sy_id> のクエリが正常に保存されました
    • ユーザーには CMDBQueryBuilder クエリを保存する権限がありません
    • クエリ名が空です。名前を入力してください
    • QueryJson が無効です。有効な queryJson を指定してください
    • クエリ名は既に使用されています。別の名前を使用してください
    • クエリの保存中に予期しない例外が発生しました

    データタイプ：文字列
    <Object>.status ステータスコード。保存操作が成功したときに返されます。

    値: 成功

    データタイプ：文字列

    この例では、保存済みクエリ [qb_saved_query] テーブルにクエリを追加する方法を示します。

    var queryJson = "{\"type\":\"cmdb\",\"nodes\":[{\"label\":\"Server\",\"unique_id\":\"d93f96981b310210bccf42a3b24bcb41\",\"nodeType\":\"class\",\"image\":\"images/app.ngbsm/server.svg\",\"properties\":\"\",\"allowed_connections\":[],\"filters\":{\"platform\":\"cmdb_ci_server\",\"custom\":\"\"},\"ci_type\":\"cmdb_ci_server\",\"ci_type_label\":\"Server\",\"sys_id\":\"d93f96981b310210bccf42a3b24bcb41\",\"x\":72,\"y\":337,\"returnValues\":[],\"filters_attrib\":\"\",\"applied_filters\":\"\",\"isStartNode\":true,\"nodeId\":\"d93f96981b310210bccf42a3b24bcb41_4_23_2024_5_50_54\",\"name\":\"Server 1\",\"type\":\"class\",\"refFilterApplied\":false,\"focused\":false,\"id\":\"d93f96981b310210bccf42a3b24bcb41_4_23_2024_5_50_54\",\"className\":\"cmdb_ci_server\"},{\"label\":\"Database\",\"unique_id\":\"b640269c1b310210bccf42a3b24bcb36\",\"nodeType\":\"class\",\"image\":\"images/app.ngbsm/database.svg\",\"properties\":\"\",\"allowed_connections\":[],\"filters\":{\"platform\":\"cmdb_ci_database\",\"custom\":\"\"},\"ci_type\":\"cmdb_ci_database\",\"ci_type_label\":\"Database\",\"sys_id\":\"b640269c1b310210bccf42a3b24bcb36\",\"x\":510,\"y\":340,\"returnValues\":[],\"filters_attrib\":\"\",\"applied_filters\":\"\",\"isStartNode\":false,\"nodeId\":\"b640269c1b310210bccf42a3b24bcb36_4_23_2024_5_50_57\",\"name\":\"Database 1\",\"type\":\"class\",\"refFilterApplied\":false,\"focused\":false,\"id\":\"b640269c1b310210bccf42a3b24bcb36_4_23_2024_5_50_57\",\"className\":\"cmdb_ci_database\"}],\"edges\":[{\"id\":\"Server 1_Database 1\",\"from\":\"d93f96981b310210bccf42a3b24bcb41_4_23_2024_5_50_54\",\"to\":\"b640269c1b310210bccf42a3b24bcb36_4_23_2024_5_50_57\",\"isDotted\":false,\"type\":\"relation\",\"isReverse\":false,\"direction\":\"outbound\",\"hiddenLevel\":0,\"relations\":[\"607ad1b2c0a8010e01941856b365af90\",\"1a9cb166f1571100a92eb60da2bce5c5\"]}],\"usedNames\":{\"cmdb_ci_server\":1,\"cmdb_ci_database\":1}}";

var newQuery = sn_cmdb.CMDBQBScopedScriptableAPI.saveQuery('CMDBQueryTest1', queryJson);

gs.info(JSON.stringify(newQuery, null, 2));

    出力:

    {
   "message":"Successfully saved the query with sysId d93f96981b310210bccf42a3b24bcb41",
   "status":"success"
}

    この例は、無効な JSON クエリが指定された場合のエラーを示しています。

    var queryJson = "Test";
var newQuery = sn_cmdb.CMDBQBScopedScriptableAPI.saveQuery('Test', queryJson);

gs.info(JSON.stringify(newQuery, null, 2));

    出力:

    {
   "error":"QUERY_INVALID",
   "message":"QueryJson is invalid. Please provide a valid queryJson"
}

    CMDBQBScopedScriptableAPI - updateQuery(String savedQueryId, String savedQueryName, String queryJson)

    構成管理データベース (CMDB)クエリビルダークエリの JSON を更新します。

    表 : 9. パラメーター
    名前 タイプ 説明
    savedQueryId 文字列 更新するクエリのSys_id。

    クエリ名が指定されている場合、このパラメーターは必要ありません。

    テーブル:保存済みクエリ [qb_saved_query]
    savedQueryName 文字列 更新するクエリの名前。

    クエリー sys_idが指定されている場合、このパラメーターは必要ありません。

    テーブル:保存済みクエリ [qb_saved_query] テーブルの [名前 ] フィールドに保存されます。
    クエリ JSON 文字列 クエリーの更新に使用する JSON。

    テーブル:保存済みクエリ [qb_saved_query] テーブルの [クエリ ] フィールドに保存されます。
    表 : 10. 戻り値
    タイプ 説明
    オブジェクト 更新されたクエリとエラーの詳細。
    {
  "error": "String",
  "message": "String",
  "status": "String"
}
    <Object>。エラー エラーコード。更新が失敗した場合、または無効な入力パラメーターが指定された場合に返されます。

    考えられるエラー:

    • USER_NOT_AUTHORIZED_EXCEPTION
    • INVALID_PARAM
    • QUERY_INVALID
    • QUERY_UPDATE_FAILED
    • UNAUTHORIZED_REPORT_SOURCE_USER

    データタイプ：文字列
    <Object>.message 更新の成功または失敗に関する詳細を含むメッセージ。

    可能なメッセージ:

    • 保存済みクエリが正常に更新されました
    • ユーザーには CMDBQueryBuilder クエリを更新する権限がありません
    • 無効なパラメーター。保存済みクエリの有効な sysId または有効な名前のいずれかを指定してください
    • QueryJson が無効です。有効な queryJson を指定してください
    • 指定された保存済みクエリの更新に失敗しました
    • ユーザーには保存済みクエリのレポートソースを更新する権限がありません

    データタイプ：文字列
    <Object>.status ステータスコード。更新が成功すると返されます。

    値: 成功

    データタイプ：文字列

    この例では、クエリ名を渡して保存済みクエリを更新する方法を示します。

    var queryJson = "{\"type\":\"cmdb\",\"nodes\":[{\"label\":\"Server\",\"unique_id\":\"d93f96981b310210bccf42a3b24bcb41\",\"nodeType\":\"class\",\"image\":\"images/app.ngbsm/server.svg\",\"properties\":\"\",\"allowed_connections\":[],\"filters\":{\"platform\":\"cmdb_ci_server\",\"custom\":\"\"},\"ci_type\":\"cmdb_ci_server\",\"ci_type_label\":\"Server\",\"sys_id\":\"d93f96981b310210bccf42a3b24bcb41\",\"x\":72,\"y\":336,\"returnValues\":[],\"filters_attrib\":\"\",\"applied_filters\":\"\",\"isStartNode\":true,\"nodeId\":\"d93f96981b310210bccf42a3b24bcb41_4_23_2024_5_50_54\",\"name\":\"Server 1\",\"type\":\"class\",\"refFilterApplied\":false,\"focused\":false,\"id\":\"d93f96981b310210bccf42a3b24bcb41_4_23_2024_5_50_54\",\"className\":\"cmdb_ci_server\"},{\"label\":\"Web Server\",\"unique_id\":\"984f5a981b310210bccf42a3b24bcb03\",\"nodeType\":\"class\",\"image\":\"images/app.ngbsm/web_server.svg\",\"properties\":\"\",\"allowed_connections\":[],\"filters\":{\"platform\":\"cmdb_ci_web_server\",\"custom\":\"\"},\"ci_type\":\"cmdb_ci_web_server\",\"ci_type_label\":\"Web Server\",\"sys_id\":\"984f5a981b310210bccf42a3b24bcb03\",\"x\":446,\"y\":330,\"returnValues\":[],\"filters_attrib\":\"\",\"applied_filters\":\"\",\"isStartNode\":false,\"nodeId\":\"984f5a981b310210bccf42a3b24bcb03_4_23_2024_6_32_19\",\"name\":\"Web Server 1\",\"type\":\"class\",\"refFilterApplied\":false,\"focused\":false,\"id\":\"984f5a981b310210bccf42a3b24bcb03_4_23_2024_6_32_19\",\"className\":\"cmdb_ci_web_server\"}],\"edges\":[{\"id\":\"Server 1_Web Server 1\",\"from\":\"d93f96981b310210bccf42a3b24bcb41_4_23_2024_5_50_54\",\"to\":\"984f5a981b310210bccf42a3b24bcb03_4_23_2024_6_32_19\",\"isDotted\":false,\"type\":\"relation\",\"isReverse\":false,\"direction\":\"outbound\",\"hiddenLevel\":0,\"relations\":[\"607ad1b2c0a8010e01941856b365af90\"]}],\"usedNames\":{\"cmdb_ci_server\":1,\"cmdb_ci_database\":1,\"cmdb_ci_web_server\":1}}";

var queryUpdate = sn_cmdb.CMDBQBScopedScriptableAPI.updateQuery('', 'CMDBQueryTest1', queryJson); 

gs.info(JSON.stringify(queryUpdate, null, 2));

    出力:

    {
   "message":"Successfully updated the saved query",
   "status":"success"
}

    この例は、クエリsys_idと名前の両方がメソッド呼び出しにない場合のエラーを示しています。

    var queryJson = "{\"type\":\"cmdb\",\"nodes\":[{\"label\":\"Server\",\"unique_id\":\"d93f96981b310210bccf42a3b24bcb41\",\"nodeType\":\"class\",\"image\":\"images/app.ngbsm/server.svg\",\"properties\":\"\",\"allowed_connections\":[],\"filters\":{\"platform\":\"cmdb_ci_server\",\"custom\":\"\"},\"ci_type\":\"cmdb_ci_server\",\"ci_type_label\":\"Server\",\"sys_id\":\"d93f96981b310210bccf42a3b24bcb41\",\"x\":72,\"y\":336,\"returnValues\":[],\"filters_attrib\":\"\",\"applied_filters\":\"\",\"isStartNode\":true,\"nodeId\":\"d93f96981b310210bccf42a3b24bcb41_4_23_2024_5_50_54\",\"name\":\"Server 1\",\"type\":\"class\",\"refFilterApplied\":false,\"focused\":false,\"id\":\"d93f96981b310210bccf42a3b24bcb41_4_23_2024_5_50_54\",\"className\":\"cmdb_ci_server\"},{\"label\":\"Web Server\",\"unique_id\":\"984f5a981b310210bccf42a3b24bcb03\",\"nodeType\":\"class\",\"image\":\"images/app.ngbsm/web_server.svg\",\"properties\":\"\",\"allowed_connections\":[],\"filters\":{\"platform\":\"cmdb_ci_web_server\",\"custom\":\"\"},\"ci_type\":\"cmdb_ci_web_server\",\"ci_type_label\":\"Web Server\",\"sys_id\":\"984f5a981b310210bccf42a3b24bcb03\",\"x\":446,\"y\":330,\"returnValues\":[],\"filters_attrib\":\"\",\"applied_filters\":\"\",\"isStartNode\":false,\"nodeId\":\"984f5a981b310210bccf42a3b24bcb03_4_23_2024_6_32_19\",\"name\":\"Web Server 1\",\"type\":\"class\",\"refFilterApplied\":false,\"focused\":false,\"id\":\"984f5a981b310210bccf42a3b24bcb03_4_23_2024_6_32_19\",\"className\":\"cmdb_ci_web_server\"}],\"edges\":[{\"id\":\"Server 1_Web Server 1\",\"from\":\"d93f96981b310210bccf42a3b24bcb41_4_23_2024_5_50_54\",\"to\":\"984f5a981b310210bccf42a3b24bcb03_4_23_2024_6_32_19\",\"isDotted\":false,\"type\":\"relation\",\"isReverse\":false,\"direction\":\"outbound\",\"hiddenLevel\":0,\"relations\":[\"607ad1b2c0a8010e01941856b365af90\"]}],\"usedNames\":{\"cmdb_ci_server\":1,\"cmdb_ci_database\":1,\"cmdb_ci_web_server\":1}}";

var queryUpdate = sn_cmdb.CMDBQBScopedScriptableAPI.updateQuery('', '', queryJson);

gs.info(JSON.stringify(queryUpdate, null, 2));

    出力:

    {
   "error":"INVALID_PARAM",
   "message":"Invalid Parameters. Please provide either a valid sysId or a valid name of a saved query"
}