AccAgentsAPI :スコープ対象

  • リリースバージョン: Yokohama
  • 更新日 2025年01月30日
  • 所要時間：18分

    • AccAgentsAPI スクリプトインクルードを使用すると、利用可能なエージェントで管理アクションを実行できます。

    このスクリプトインクルードは、 エージェントクライアントコレクター Framework (sn_agent) ストアアプリケーションを必要とし、 sn_agent 名前空間内で提供されます。詳細については、「 エージェントクライアントコレクター」を参照してください。

    REST API ソリューションについては、「 エージェントクライアントコレクター API」を参照してください。

    このスクリプトインクルードは、以下を可能にするメソッドを提供します。
    • 1 つ以上のエージェントの詳細情報を取得
    • 要求を送信してエージェントログを取得し、要求の進捗状況に関する情報を取得
    • データ収集を開始または停止
    • エージェントを再起動
    • エージェントで検出を実行

    AccAgentsAPI - AccAgentsAPI()

    AccAgentsAPI インスタンスを作成します。

    表 : 1. パラメーター
    名前 タイプ 説明
    なし

    次の例は、AccAgentsAPI を初期化する方法を示しています。

    var agentsApi = new sn_agent.AccAgentsAPI();

    AccAgentsAPI - checkGrabLogRequestProgress(文字列 requestId)

    ログ取得要求のステータスを確認します。

    submitGrabLogRequest() メソッドを実行して、要求 ID を取得します。

    表 : 2. パラメーター
    名前 タイプ 説明
    requestId 文字列 Agent Client Collector Requests [sn_agent_request] テーブル内の要求の sys_id。
    表 : 3. 返される内容
    プロパティ 説明
    <Object> ログ取得要求のステータスを含む JSON オブジェクト。
    {
  "status": Number,
  "output": "String"
}
    status ログ取得要求のステータスを示す数値。
    可能な値：
    • 0：ログ取得要求が完了しました。
    • 1：ログ取得要求は処理中です。
    • 2：ログ取得要求はタイムアウトしました。
    • 3：ログ取得要求でエラーが発生しました。
    • 4：ログ取得要求が見つかりませんでした。
    output ステータスを説明する情報。

    次の例は、要求 ID を使用してログ取得要求のステータスを取得する方法を示しています。

    var agentsApi = new sn_agent.AccAgentsAPI();
var logRequestStatus = agentsApi.checkGrabLogRequestProgress("<request_ID>");

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

    出力 :

    {
  "status": 2,
  "output": "Grab Log Request Timed Out"
}

    AccAgentsAPI - getAgent(文字列 agentID)

    指定されたエージェントの情報を取得します。

    エージェント ID のリストを取得するには：
    • getAgentsList() メソッドを実行します。
    • Agent Client Collector [sn_agent_cmdb_ci_agent] テーブルの [Agent ID] 列を確認します。
    • Agent Client Collector GET list REST API を実行します。
    表 : 4. パラメーター
    名前 タイプ 説明
    agentID 文字列 Agent Client Collector [sn_agent_cmdb_ci_agent] テーブルの [Agent ID] 列にリストされるエージェントの一意の ID。
    表 : 5. 返される内容
    プロパティ 説明
    <Object> エージェントの詳細情報を含むオブジェクト。
    {
  "error": String,
  "agent": Object
}
    error エラーメッセージ。エラーがない場合は Null。

    データタイプ：文字列
    エージェント 
    "agent": {
   "agent_id": "String",
   "data_collection": Number,
   "ip_address": "String",
   "is_duplicate": Boolean,
   "is_restart_enabled": Boolean,
   "name": "String",
   "number_of_running_checks": Number,
   "status": Number,
   "up_since": "String",
   "version": "String"
 }
    agent.agent_id 送信されたエージェントの ID。

    データタイプ：文字列
    agent.data_collection データ収集は、スケジュールされたチェックを実行するかどうかを示します。これらのチェックは、このエージェントが実行されるようにスケジュールされたポリシーの一部です。
    可能な値：
    • 0：オン - チェックがスケジュールどおりに実行されます。
    • 1：オフ (手動) – チェックは手動で無効にされています。
    • 2：オフ (自動) - CPU の消費量が多いため、チェックが自動的に無効になりました

    データタイプ：数値
    agent.ip_address エージェントの IP アドレス。

    データタイプ：文字列
    agent.is_duplicate

    このエージェントが別のエージェントの複製であるかどうかを示すフラグ。指定されたホストには 1 つのエージェントのみが存在している必要があります。

    可能な値：
    • true：エージェントは、異なるエージェント ID を持つアライブ/稼動エージェントと同じホストを持っています。重複をオフにするかアンインストールします
    • false：このエージェントには、アライブ/稼働ステータスの重複はありません。

    データタイプ：ブール
    agent.is_restart_enabled

    再起動が有効かどうかを示すフラグ。エージェントの再起動は構成できません。OS と、エージェントが実行されている OS のバージョンによって異なります。

    可能な値：
    • true：このエージェントの再起動が有効です。
    • false：このエージェントの再起動が無効です。

    データタイプ：ブール
    agent.name エージェントの名前。

    データタイプ：文字列
    agent.number_of_running_checks エージェントの実行がスケジュールされているチェックの数。これらのチェックは、このエージェントが実行されるようにスケジュールされたポリシーの一部です。

    データタイプ：数値
    agent.status エージェントのステータス。
    可能な値：
    • 0：アライブ/稼動 – エージェントはアクティブです。
    • 1：警告 - エージェントは過去数分間にキープアライブメッセージを受信していません。
    • 2：停止 - エージェントが長期間にわたってキープアライブメッセージを受信していません。
    • 3：再起動中 - エージェントを再起動しています。

    データタイプ：数値
    agent.up_since エージェントのステータスがアライブ/稼働になってからの UTC 時間。値は GlideDateTime 形式です。

    データタイプ：文字列
    agent.version エージェントが実行している エージェントクライアントコレクター のバージョン。

    データタイプ：文字列

    次の例は、エージェントのステータスを表示する方法を示しています。

    var agentsApi = new sn_agent.AccAgentsAPI();
var agentInfo = agentsAPI.getAgent("<agent_ID>");

if (!gs.nil(agentInfo.error))
	gs.error(agentInfo.error);
else
	gs.info("agent status: " + agentInfo.agent.status);

    出力 :

    agent status: 2

    次の例は、すべてのエージェントの詳細を取得する方法を示しています。

    var agentsApi = new sn_agent.AccAgentsAPI();
var agentInfo = agentsAPI.getAgent("<agent_ID>");

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

    出力：

    {
  "error": null,
  "agent": {
    "name": "win2016-dc-64bit",
    "status": 0,
    "agent_id": "<agent_ID>",
    "ip_address": "10.222.333.42",
    "number_of_running_checks": 1,
    "data_collection": 0,
    "is_restart_enabled": true,
    "is_duplicate": false,
    "up_since": "2021-03-24 11:04:38",
    "version": "2.4.0"
  }
}

    AccAgentsAPI – getAgentsList(文字列 encodedQuery, 数値 limit)

    関連情報を含むエージェントのリストを取得します。

    表 : 6. パラメーター
    名前 タイプ 説明
    encodedQuery 文字列 標準の Glide 形式のエンコードされたクエリ文字列。「エンコードされたクエリ文字列」を参照してください。
    limit 数値 オプション。結果をエージェントの最大数に制限します。必要ない場合は、両方に null または undefined を使用します。

    デフォルト/最大：20,000
    表 : 7. 返される内容
    プロパティ 説明
    <Array> エージェントの詳細情報を含む JSON オブジェクトのアレイ。
    [
 {
   "agent_id": "String",
   "data_collection": Number,
   "ip_address": "String",
   "is_duplicate": Boolean,
   "is_restart_enabled": Boolean,
   "name": "String",
   "number_of_running_checks": Number,
   "status": Number,
   "up_since": "String",
   "version": "String"
 }
]
    agent_id 送信されたエージェントの ID。

    データタイプ：文字列
    data_collection データ収集は、スケジュールされたチェックを実行するかどうかを示します。これらのチェックは、このエージェントが実行されるようにスケジュールされたポリシーの一部です。
    可能な値：
    • 0：オン - チェックがスケジュールどおりに実行されます。
    • 1：オフ (手動) – チェックは手動で無効にされています。
    • 2：オフ (自動) - CPU の消費量が多いため、チェックが自動的に無効になりました

    データタイプ：数値
    ip_address エージェントの IP アドレス。

    データタイプ：文字列
    is_duplicate

    このエージェントが別のエージェントの複製であるかどうかを示すフラグ。指定されたホストには 1 つのエージェントのみが存在している必要があります。

    可能な値：
    • true：エージェントは、異なるエージェント ID を持つアライブ/稼動エージェントと同じホストを持っています。重複をオフにするかアンインストールします
    • false：このエージェントには、アライブ/稼働ステータスの重複はありません。

    データタイプ：ブール
    is_restart_enabled

    再起動が有効かどうかを示すフラグ。エージェントの再起動は構成できません。OS と、エージェントが実行されている OS のバージョンによって異なります。

    可能な値：
    • true：このエージェントの再起動が有効です。
    • false：このエージェントの再起動が無効です。

    データタイプ：ブール
    name エージェントの名前。

    データタイプ：文字列
    number_of_running_checks エージェントの実行がスケジュールされているチェックの数。これらのチェックは、このエージェントが実行されるようにスケジュールされたポリシーの一部です。

    データタイプ：数値
    status エージェントのステータス。
    可能な値：
    • 0：アライブ/稼動 – エージェントはアクティブです。
    • 1：警告 - エージェントは過去数分間にキープアライブメッセージを受信していません。
    • 2：停止 - エージェントが長期間にわたってキープアライブメッセージを受信していません。
    • 3：再起動中 - エージェントを再起動しています。

    データタイプ：数値
    up_since エージェントのステータスがアライブ/稼働になってからの UTC 時間。値は GlideDateTime 形式です。

    データタイプ：文字列
    version エージェントが実行している エージェントクライアントコレクター のバージョン。

    データタイプ：文字列

    次の例は、クエリーと数値によって結果を制限する方法を示しています。このクエリーは、ダウンステータスでないすべてのエージェントを最大 2 つの結果とともに返します。

    var agentsApi = new sn_agent.AccAgentsAPI();
var agentList = agentsApi.getAgentsList("agent_extended_info.status!=2", 2);

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

    出力：

    [
  {
    "name": "007-175",
    "status": 0,
    "agent_id": "007-175",
    "ip_address": "11.222.63.66",
    "number_of_running_checks": 0,
    "data_collection": 0,
    "is_restart_enabled": false,
    "is_duplicate": false,
    "up_since": "2021-03-24 14:36:45",
    "version": "2.4.0"
  },
  {
    "name": "win2016-dc-64bit",
    "status": 0,
    "agent_id": "007-64",
    "ip_address": "10.222.333.42",
    "number_of_running_checks": 1,
    "data_collection": 0,
    "is_restart_enabled": true,
    "is_duplicate": false,
    "up_since": "2021-03-24 11:04:38",
    "version": "2.4.0"
  }
]

    次の例は、システム内のすべてのエージェントを一覧表示する方法を示しています。この例では、クエリーと結果の最大数を使用していません。

    var agentsApi = new sn_agent.AccAgentsAPI();
var agentList = agentsApi.getAgentsList(null, 0);

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

    次の例は、提供された結果を反復処理して各エージェント ID を表示する方法を示しています。

    var agentsApi = new sn_agent.AccAgentsAPI();

var agentsList = agentsApi.getAgentsList(null, 0);
for (var i = 0; i < agentsList.length; i++)
   gs.info("agent with id: " + agentsList[i].agent_id);

    出力：

    sn_agent: agent with id: 000a00e0aa1aa3a4
sn_agent: agent with id: 000a00e1aa1aa3a4
sn_agent: agent with id: 000a00e2aa1aa3a4

    AccAgentsAPI - restartAgent(文字列 agentID)

    アライブ/稼働ステータスの指定されたエージェントを再起動します。

    エージェントクライアントコレクター のパフォーマンスの問題が発生した場合は、エージェントを再起動できます。手動再起動は次の環境でサポートされています。
    • systemd を使用する Linux ベースのエージェント
    • Windows エージェント
    エージェント ID のリストを取得するには：
    • getAgentsList() メソッドを実行します。
    • Agent Client Collector [sn_agent_cmdb_ci_agent] テーブルの [Agent ID] 列を確認します。
    • Agent Client Collector GET list REST API を実行します。
    表 : 8. パラメーター
    名前 タイプ 説明
    agentID 文字列 Agent Client Collector [sn_agent_cmdb_ci_agent] テーブルの [Agent ID] 列にリストされるエージェントの一意の ID。
    表 : 9. 返される内容
    タイプ 説明
    文字列 該当する場合はエラーメッセージ、それ以外の場合は null

    次の例は、 エージェントを再起動する方法を示しています。

    var agentsApi = new sn_agent.AccAgentsAPI();

var err = agentsApi.restartAgent("<agent_ID>");
if (!gs.nil(err))
	gs.error(err);

    AccAgentsAPI - runDiscovery(文字列 agentID)

    検出チェックを実行して、エージェントに関連する CI を特定します。指定されたエージェントは、アライブ/稼働ステータスである必要があります。

    エージェント ID のリストを取得するには：
    • getAgentsList() メソッドを実行します。
    • Agent Client Collector [sn_agent_cmdb_ci_agent] テーブルの [Agent ID] 列を確認します。
    • Agent Client Collector GET list REST API を実行します。
    表 : 10. パラメーター
    名前 タイプ 説明
    agentID 文字列 Agent Client Collector [sn_agent_cmdb_ci_agent] テーブルの [Agent ID] 列にリストされるエージェントの一意の ID。
    表 : 11. 返される内容
    タイプ 説明
    文字列 該当する場合はエラーメッセージ、それ以外の場合は null。例：Agent With ID: <agentID> Is Not Up: no thrown error

    次の例は、アライブ/稼働ステータスのエージェントで検出を実行する方法を示しています。

    var agentsApi = new sn_agent.AccAgentsAPI();

var err = agentsApi.runDiscovery("<agent_ID>");

if (!gs.nil(err))
	gs.error(err);

    AccAgentsAPI - setDataCollectionStatus(文字列 agentID, ブール status)

    指定されたエージェントの指定されたデータ収集ステータス (true/false、有効かどうか) を設定します。

    エージェント ID のリストを取得するには：
    • getAgentsList() メソッドを実行します。
    • Agent Client Collector [sn_agent_cmdb_ci_agent] テーブルの [Agent ID] 列を確認します。
    • Agent Client Collector GET list REST API を実行します。
    表 : 12. パラメーター
    名前 タイプ 説明
    agentID 文字列 Agent Client Collector [sn_agent_cmdb_ci_agent] テーブルの [Agent ID] 列にリストされるエージェントの一意の ID。
    status ブーリアン

    エージェントのデータ収集が有効かどうかを示すフラグ。

    有効な値：
    • true：このエージェントのデータ収集を有効にします。
    • false：このエージェントのデータ収集を無効にします。

    デフォルト：true
    表 : 13. 返される内容
    タイプ 説明
    文字列 該当する場合はエラーメッセージ、それ以外の場合は null。例：Agent With ID: <agentID> Is Not Up: no thrown error

    次の例は、エージェントのデータ収集を有効にする方法を示しています。

    var agentsApi = new sn_agent.AccAgentsAPI();
var err = agentsApi.setDataCollectionStatus("<agentID>", true);
if (!gs.nil(err))
   gs.error(err);

    次の例は、エージェントのデータ収集を無効にする方法を示しています。

    var agentsApi = new sn_agent.AccAgentsAPI();
var err = agentsApi.setDataCollectionStatus("<agentID>", false);
if (!gs.nil(err))
   gs.error(err);

    AccAgentsAPI - sendGrabLogRequest(文字列 agentId)

    アライブ/稼働ステータスの指定されたエージェントのログを要求します。

    注:
    ログを取得してその進捗状況を確認するには、返された要求 ID を checkGrabLogRequestProgress() メソッドに渡します。
    表 : 14. パラメーター
    名前 タイプ 説明
    agentID 文字列 Agent Client Collector [sn_agent_cmdb_ci_agent] テーブルの [Agent ID] 列にリストされるエージェントの一意の ID。
    表 : 15. 返される内容
    プロパティ 説明
    <Object> 要求 ID とエラー情報を含む JSON オブジェクト。
    {
  "error": "String",
  "request_id": "String"
}
    error エラーメッセージ。エラーがない場合は Null。

    データタイプ：文字列
    request_id Agent Client Collector Requests [sn_agent_request] テーブル内の要求の sys_id。

    この ID を使用し、GET /agents/{request_id}/ により要求のステータスを取得できます。

    データタイプ：文字列

    次の例は、ログ要求 ID を取得する方法を示しています。

    var agentsApi = new sn_agent.AccAgentsAPI();
var submittedRequest = agentsApi.submitGrabLogRequest("<agentID>");

if (!gs.nil(submittedRequest.error))
   gs.error(submittedRequest.error);
else
   gs.info("Request ID: " + submittedRequest.request_id);

    出力：

    Request ID: <sys_id>