CMDBQueryBuilderAPI - グローバル

  • リリースバージョン: Xanadu
  • 更新日 2024年08月01日
  • 所要時間：25分

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

    この API には、 構成管理データベース (CMDB) アプリケーション (com.snc.cmdb) が必要です。

    スコープ対象のアプリケーションでこれらのメソッドを使用するには、「 CMDBQBScopedScriptableAPI :スコープ指定」を参照してください。

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

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

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

    表 : 1. パラメーター
    名前 タイプ 説明
    savedQueryId 文字列 レポートに使用するクエリのSys_id。保存済みクエリ [qb_saved_query] テーブルにあります。

    クエリ名が指定されている場合、このパラメーターは必要ありません。
    savedQueryName 文字列 レポートに使用するクエリの名前。保存済みクエリ [qb_saved_query] テーブルのクエリレコードの [名前] フィールドにあります。

    クエリー sys_idが指定されている場合、このパラメーターは必要ありません。
    表 : 2. 返される内容
    タイプ 説明
    オブジェクト 作成されたレポートとエラーに関する詳細を含むオブジェクト。
    {
   "error": "String",
   "message": "String",
   "status": "String"
}
    <Object>。エラー エラーコード。レポートの作成に失敗した場合、または無効な入力パラメーターが指定された場合に返されます。

    考えられるエラー:

    • USER_NOT_AUTHORIZED_EXCEPTION
    • INVALID_PARAM
    • QUERY_SYS_ID_INVALID

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

    考えられるメッセージ:

    • <report-url>
    • ユーザーは CMDBQueryBuilder クエリレポートの作成を許可されていません
    • 無効なパラメーター。有効な sysId または保存済みクエリの有効な名前を指定してください
    • queryId が無効です。有効な保存済みクエリ ID を指定してください

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

    値: 成功

    データタイプ：文字列

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

    SNC.CMDBQueryBuilderAPI.createReport('', 'CMDBQueryTest1');

    出力:

    {
   "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"
}

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

    SNC.CMDBQueryBuilderAPI.createReport('', 'Test');

    出力:

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

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

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

    表 : 3. パラメーター
    名前 タイプ 説明
    savedQueryId 文字列 削除するクエリのSys_id。保存済みクエリ [qb_saved_query] テーブルにあります。

    クエリ名が指定されている場合、このパラメーターは必要ありません。
    savedQueryName 文字列 削除するクエリの名前。保存済みクエリ [qb_saved_query] テーブルのクエリレコードの [名前] フィールドにあります。

    クエリー sys_idが指定されている場合、このパラメーターは必要ありません。
    表 : 4. 返される内容
    タイプ 説明
    オブジェクト 削除されたクエリとエラーに関する詳細を含むオブジェクト。
    {
   "error": "String",
   "message": "String",
   "status": "String"
}
    <Object>。エラー エラーコード。削除操作が失敗した場合、または無効な入力パラメーターが指定された場合に返されます。

    考えられるエラー:

    • USER_NOT_AUTHORIZED_EXCEPTION
    • INVALID_PARAM
    • QUERY_DELETE_FAILED

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

    考えられるメッセージ:

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

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

    値: 成功

    データタイプ：文字列

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

    SNC.CMDBQueryBuilderAPI.deleteQuery('', 'CMDBQueryTest1');

    出力:

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

    CMDBQueryBuilderAPI - getSavedQueryExecutionDetails(文字列 savedQueryName, ブール executeQuery, 数値 timeout)

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

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

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

    表 : 5. パラメーター
    名前 タイプ 説明
    savedQueryName 文字列 実行の詳細を取得するクエリの名前。保存済みクエリ [qb_saved_query] テーブルのクエリレコードの [名前] フィールドにあります。
    executeQuery ブーリアン オプション。指定したクエリを実行するかどうかを示すフラグ。

    有効な値：

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

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

    単位：秒

    デフォルト：5 分
    表 : 6. 返される内容
    タイプ 説明
    オブジェクト クエリの実行とエラーに関する詳細を含むオブジェクト。
    {
   "error": "String",
   "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>.message エラーコードの詳細を含むメッセージ。クエリー実行が失敗した場合、または指定されたクエリーが見つからない場合に返されます。

    考えられるメッセージ:

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

    データタイプ：文字列
    <Object>.query_id クエリ実行のSys_id。クエリステータス [qb_query_status] テーブルにあります。

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

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

    データタイプ：文字列

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

    SNC.CMDBQueryBuilderAPI.getSavedQueryExecutionDetails('Test', true, 600);

    出力:

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

    CMDBQueryBuilderAPI - saveQuery(文字列 savedQueryName, 文字列 queryJson)

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

    表 : 7. パラメーター
    名前 タイプ 説明
    savedQueryName 文字列 クエリを保存する名前。名前は、保存済みクエリ [qb_saved_query] テーブルのクエリレコードの [名前] フィールドに保存されます。
    クエリ JSON 文字列 クエリを定義する 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 ステータスコード。保存操作が成功したときに返されます。

    値: 成功

    データタイプ：文字列

    この例では、Saved Queries [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}}";
SNC.CMDBQueryBuilderAPI.saveQuery('CMDBQueryTest1', queryJson);

    出力:

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

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

    var queryJson = "Test";
SNC.CMDBQueryBuilderAPI.saveQuery('Test', queryJson);

    出力:

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

    CMDBQueryBuilderAPI - updateQuery(文字列 savedQueryId, 文字列 savedQueryName, 文字列 queryJson)

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

    表 : 9. パラメーター
    名前 タイプ 説明
    savedQueryId 文字列 更新するクエリのSys_id。保存済みクエリ [qb_saved_query] テーブルにあります。

    クエリ名が指定されている場合、このパラメーターは必要ありません。
    savedQueryName 文字列 更新するクエリの名前。保存済みクエリ [qb_saved_query] テーブルのクエリレコードの [名前] フィールドにあります。

    クエリー sys_idが指定されている場合、このパラメーターは必要ありません。
    クエリ JSON 文字列 クエリの更新に使用する 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}}";
gs.log(SNC.CMDBQueryBuilderAPI.updateQuery('', 'CMDBQueryTest1', queryJson));

    出力:

    {
   "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}}";
SNC.CMDBQueryBuilderAPI.updateQuery('', '', queryJson);

    出力:

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