--- sourceDocument: Xanadu API リファレンス sourceDocumentLink: https://servicenow-prod.fluidtopics.net/r/ja-JP/xanadu/api-reference Release : - xanadu ft:locale : - ja-JP ft:publication_title : - Xanadu API リファレンス ft:clusterId : - crapiref bundleId : - crapiref workflow : - Creator --- # AccAgentsAPI :スコープ指定 # AccAgentsAPI :スコープ指定 {#ariaid-title1} * リリースバージョン: Xanadu * * 更新日 2024年08月01日 * * ![](https://www.servicenow.com/docs/portal-asset/ico-clock) 所要時間：18分 AccAgentsAPI スクリプトインクルードを使用すると、利用可能なエージェントで管理アクションを実行できます。 このスクリプトインクルードには エージェントクライアントコレクター Framework (sn_agent) ストアアプリケーションが必要であり、 `sn_agent` 名前空間内で提供されます。詳細については、「 [エージェントクライアントコレクター](https://www.servicenow.com/docs/access?context=acc-landing-page&version=xanadu&pubname=xanadu-it-operations-management&ft:locale=en-US)」を参照してください。 REST API ソリューションについては、「 [エージェントクライアントコレクター API](https://servicenow-prod.fluidtopics.net/Id71AT_lAinkjm~KVoTIag#agnt_clnt_cll-api "Agent Client Collector API は、利用可能なエージェントのアクションと管理ポリシーを管理するためのエンドポイントを提供します。")」を参照してください。 このスクリプトインクルードは、以下を有効にするメソッドを提供します。 * 1 つ以上のエージェントの詳細情報を取得 * 要求を送信してエージェントログを取得し、要求の進捗状況に関する情報を取得 * データ収集を開始または停止 * エージェントを再起動 * エージェントで検出を実行 ## AccAgentsAPI - AccAgentsAPI() {#ariaid-title2} AccAgentsAPI インスタンスを作成します。 {#AccA-AccAgentsAPI__table_ohr_4qd_bpb__entry__3} | 名前 | タイプ | 説明 | |-|-|-| | なし | | | [表 : 1. パラメーター] {#AccA-AccAgentsAPI__table_ohr_4qd_bpb} 次の例は、AccAgentsAPI を初期化する方法を示しています。 var agentsApi = new sn_agent.AccAgentsAPI(); ## AccAgentsAPI - checkGrabLogRequestProgress(文字列 requestId) {#ariaid-title3} ログ取得要求のステータスを確認します。 [submitGrabLogRequest()](https://servicenow-prod.fluidtopics.net/DH5ZZba5kmu9lWbruqi~MA#AccA-submitGrabLogRequest_S "アライブ/稼働ステータスの指定されたエージェントのログを要求します。") メソッドを実行して、要求 ID を取得します。 {#AccA-checkGrabLogRequestProgress_S__table_zk2_2g2_z4b__entry__3}{#AccA-checkGrabLogRequestProgress_S__accAgents-parm-desc-requestID} | 名前 | タイプ | 説明 | |-|-|-| | requestId | 文字列 | Agent Client Collector Requests \[sn_agent_request\] テーブル内の要求の sys_id。 | [表 : 2. パラメーター] {#AccA-checkGrabLogRequestProgress_S__table_zk2_2g2_z4b} {#AccA-checkGrabLogRequestProgress_S__table_al2_2g2_z4b__entry__2} | プロパティ | 説明 | |-|-| | \ | ログ取得要求のステータスを含む JSON オブジェクト。 { "status": Number, "output": "String" } | | status | ログ取得要求のステータスを示す数値。 可能な値： * 0：ログ取得要求が完了しました。 * 1：ログ取得要求は処理中です。 * 2：ログ取得要求はタイムアウトしました。 * 3：ログ取得要求でエラーが発生しました。 * 4：ログ取得要求が見つかりませんでした。 {#AccA-checkGrabLogRequestProgress_S__ul_orq_4qr_bpb} | | output | ステータスを説明する情報。 | [表 : 3. 返される内容] {#AccA-checkGrabLogRequestProgress_S__table_al2_2g2_z4b} 次の例は、要求 ID を使用してログ取得要求のステータスを取得する方法を示しています。 var agentsApi = new sn_agent.AccAgentsAPI(); var logRequestStatus = agentsApi.checkGrabLogRequestProgress(""); gs.info(JSON.stringify(logRequestStatus, null, 2)); 出力 : { "status": 2, "output": "Grab Log Request Timed Out" } ## AccAgentsAPI - getAgent(文字列 agentID) {#ariaid-title4} 指定されたエージェントの情報を取得します。 エージェント ID のリストを取得するには： * getAgentsList() メソッドを実行します。 * Agent Client Collector \[sn_agent_cmdb_ci_agent\] テーブルの \[Agent ID\] 列を確認します。 * [Agent Client Collector GET list](https://servicenow-prod.fluidtopics.net/Id71AT_lAinkjm~KVoTIag#agnt_clnt_cll-GET-list "関連情報を含むエージェントのリストを取得します。") REST API を実行します。 {#AccA-getAgent_S__ul_yqc_3kj_z4b} {#AccA-getAgent_S__table_zk2_2g2_z4b__entry__3}{#AccA-getAgent_S__accAgents-parm-desc-agentID} | 名前 | タイプ | 説明 | |-|-|-| | agentID | 文字列 | Agent Client Collector \[sn_agent_cmdb_ci_agent\] テーブルの \[Agent ID\] 列にリストされるエージェントの一意の ID。 | [表 : 4. パラメーター] {#AccA-getAgent_S__table_zk2_2g2_z4b} {#AccA-getAgent_S__table_al2_2g2_z4b__entry__2}{#AccA-getAgent_S__accAgents-rtrns-error} | プロパティ | 説明 | |-|-| | \ | エージェントの詳細情報を含むオブジェクト。 { "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 の消費量が多いため、チェックが自動的に無効になりました {#AccA-getAgent_S__ul_w4n_53p_bpb} データタイプ：数値 | | agent.ip_address | エージェントの IP アドレス。 データタイプ：文字列 | | agent.is_duplicate | このエージェントが別のエージェントの複製であるかどうかを示すフラグ。指定されたホストには 1 つのエージェントのみが存在している必要があります。 可能な値： * true：エージェントは、異なるエージェント ID を持つアライブ/稼動エージェントと同じホストを持っています。重複をオフにするかアンインストールします * false：このエージェントには、アライブ/稼働ステータスの重複はありません。 {#AccA-getAgent_S__ul_b34_ffl_bpb} データタイプ：ブール | | agent.is_restart_enabled | 再起動が有効かどうかを示すフラグ。エージェントの再起動は構成できません。OS と、エージェントが実行されている OS のバージョンによって異なります。 可能な値： * true：このエージェントの再起動が有効です。 * false：このエージェントの再起動が無効です。 {#AccA-getAgent_S__ul_bvp_dfl_bpb} データタイプ：ブール | | agent.name | エージェントの名前。 データタイプ：文字列 | | agent.number_of_running_checks | エージェントの実行がスケジュールされているチェックの数。これらのチェックは、このエージェントが実行されるようにスケジュールされたポリシーの一部です。 データタイプ：数値 | | agent.status | エージェントのステータス。 可能な値： * 0：アライブ/稼動 -- エージェントはアクティブです。 * 1：警告 - エージェントは過去数分間にキープアライブメッセージを受信していません。 * 2：停止 - エージェントが長期間にわたってキープアライブメッセージを受信していません。 * 3：再起動中 - エージェントを再起動しています。 {#AccA-getAgent_S__ul_adg_ffp_bpb} データタイプ：数値 | | agent.up_since | エージェントのステータスがアライブ/稼働になってからの UTC 時間。値は [GlideDateTime](https://servicenow-prod.fluidtopics.net/xWri1nmJyGLw7m~IPzfcdg#c_GlideDateTimeScoped "スコープ指定された GlideDateTime クラスは、GlideDateTime オブジェクトに対する操作を実行するためのメソッドを提供します。") 形式です。 データタイプ：文字列 | | agent.version | エージェントが実行している エージェントクライアントコレクター のバージョン。 データタイプ：文字列 | [表 : 5. 返される内容] {#AccA-getAgent_S__table_al2_2g2_z4b} 次の例は、エージェントのステータスを表示する方法を示しています。 var agentsApi = new sn_agent.AccAgentsAPI(); var agentInfo = agentsAPI.getAgent(""); 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(""); gs.info(JSON.stringify(agentInfo, null, 2)); 出力： { "error": null, "agent": { "name": "win2016-dc-64bit", "status": 0, "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) {#ariaid-title5} 関連情報を含むエージェントのリストを取得します。 {#AccA-getAgentsList_S_N__table_zk2_2g2_z4b__entry__3} | 名前 | タイプ | 説明 | |-|-|-| | encodedQuery | 文字列 | 標準の Glide 形式のエンコードされたクエリ文字列。「 [エンコードされたクエリ文字列](https://www.servicenow.com/docs/access?context=c_EncodedQueryStrings&version=xanadu&pubname=xanadu-platform-user-interface&ft:locale=en-US)」を参照してください。 | | limit | 数値 | オプション。結果をエージェントの最大数に制限します。必要ない場合は、両方に null または undefined を使用します。 デフォルト/最大：20,000 | [表 : 6. パラメーター] {#AccA-getAgentsList_S_N__table_zk2_2g2_z4b} {#AccA-getAgentsList_S_N__table_al2_2g2_z4b__entry__2}{#AccA-getAgentsList_S_N__accAgents-parm-agent-obj-id-entry}{#AccA-getAgentsList_S_N__accAgents-parm-agent-obj-dataCollect-entry}{#AccA-getAgentsList_S_N__accAgents-parm-agent-obj-ip-entry}{#AccA-getAgentsList_S_N__accAgents-parm-agent-obj-dup-entry}{#AccA-getAgentsList_S_N__accAgents-parm-agent-obj-restart-entry}{#AccA-getAgentsList_S_N__accAgents-parm-agent-obj-name-entry}{#AccA-getAgentsList_S_N__accAgents-parm-agent-obj-numChecks-entry}{#AccA-getAgentsList_S_N__accAgents-parm-agent-obj-status-entry}{#AccA-getAgentsList_S_N__accAgents-parm-agent-obj-up-entry}{#AccA-getAgentsList_S_N__accAgents-parm-agent-obj-version-entry} | プロパティ | 説明 | |-|-| | \ | エージェントの詳細情報を含む 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 の消費量が多いため、チェックが自動的に無効になりました {#AccA-getAgentsList_S_N__ul_w4n_53p_bpb} データタイプ：数値 | | ip_address | エージェントの IP アドレス。 データタイプ：文字列 | | is_duplicate | このエージェントが別のエージェントの複製であるかどうかを示すフラグ。指定されたホストには 1 つのエージェントのみが存在している必要があります。 可能な値： * true：エージェントは、異なるエージェント ID を持つアライブ/稼動エージェントと同じホストを持っています。重複をオフにするかアンインストールします * false：このエージェントには、アライブ/稼働ステータスの重複はありません。 {#AccA-getAgentsList_S_N__ul_b34_ffl_bpb} データタイプ：ブール | | is_restart_enabled | 再起動が有効かどうかを示すフラグ。エージェントの再起動は構成できません。OS と、エージェントが実行されている OS のバージョンによって異なります。 可能な値： * true：このエージェントの再起動が有効です。 * false：このエージェントの再起動が無効です。 {#AccA-getAgentsList_S_N__ul_bvp_dfl_bpb} データタイプ：ブール | | name | エージェントの名前。 データタイプ：文字列 | | number_of_running_checks | エージェントの実行がスケジュールされているチェックの数。これらのチェックは、このエージェントが実行されるようにスケジュールされたポリシーの一部です。 データタイプ：数値 | | status | エージェントのステータス。 可能な値： * 0：アライブ/稼動 -- エージェントはアクティブです。 * 1：警告 - エージェントは過去数分間にキープアライブメッセージを受信していません。 * 2：停止 - エージェントが長期間にわたってキープアライブメッセージを受信していません。 * 3：再起動中 - エージェントを再起動しています。 {#AccA-getAgentsList_S_N__ul_adg_ffp_bpb} データタイプ：数値 | | up_since | エージェントのステータスがアライブ/稼働になってからの UTC 時間。値は [GlideDateTime](https://servicenow-prod.fluidtopics.net/xWri1nmJyGLw7m~IPzfcdg#c_GlideDateTimeScoped "スコープ指定された GlideDateTime クラスは、GlideDateTime オブジェクトに対する操作を実行するためのメソッドを提供します。") 形式です。 データタイプ：文字列 | | version | エージェントが実行している エージェントクライアントコレクター のバージョン。 データタイプ：文字列 | [表 : 7. 返される内容] {#AccA-getAgentsList_S_N__table_al2_2g2_z4b} 次の例は、クエリーと数値によって結果を制限する方法を示しています。このクエリーは、ダウンステータスでないすべてのエージェントを最大 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) {#ariaid-title6} アライブ/稼働ステータスの指定されたエージェントを再起動します。 エージェントクライアントコレクター のパフォーマンスの問題が発生した場合は、エージェントを再起動できます。手動再起動は次の環境でサポートされています。 * `systemd` を使用する Linux ベースのエージェント * Windows エージェント {#AccA-restartAgent_S__ul_zzv_z4q_dpb} エージェント ID のリストを取得するには： * getAgentsList() メソッドを実行します。 * Agent Client Collector \[sn_agent_cmdb_ci_agent\] テーブルの \[Agent ID\] 列を確認します。 * [Agent Client Collector GET list](https://servicenow-prod.fluidtopics.net/Id71AT_lAinkjm~KVoTIag#agnt_clnt_cll-GET-list "関連情報を含むエージェントのリストを取得します。") REST API を実行します。 {#AccA-restartAgent_S__ul_yqc_3kj_z4b} {#AccA-restartAgent_S__table_zk2_2g2_z4b__entry__3}{#AccA-restartAgent_S__accAgents-parm-desc-agentID} | 名前 | タイプ | 説明 | |-|-|-| | agentID | 文字列 | Agent Client Collector \[sn_agent_cmdb_ci_agent\] テーブルの \[Agent ID\] 列にリストされるエージェントの一意の ID。 | [表 : 8. パラメーター] {#AccA-restartAgent_S__table_zk2_2g2_z4b} {#AccA-restartAgent_S__table_al2_2g2_z4b__entry__2} | タイプ | 説明 | |-|-| | 文字列 | 該当する場合はエラーメッセージ、それ以外の場合は null | [表 : 9. 返される内容] {#AccA-restartAgent_S__table_al2_2g2_z4b} 次の例は、 エージェントを再起動する方法を示しています。 var agentsApi = new sn_agent.AccAgentsAPI(); var err = agentsApi.restartAgent(""); if (!gs.nil(err)) gs.error(err); ## AccAgentsAPI - runDiscovery(文字列 agentID) {#ariaid-title7} 検出チェックを実行して、エージェントに関連する CI を特定します。指定されたエージェントは、アライブ/稼働ステータスである必要があります。 エージェント ID のリストを取得するには： * getAgentsList() メソッドを実行します。 * Agent Client Collector \[sn_agent_cmdb_ci_agent\] テーブルの \[Agent ID\] 列を確認します。 * [Agent Client Collector GET list](https://servicenow-prod.fluidtopics.net/Id71AT_lAinkjm~KVoTIag#agnt_clnt_cll-GET-list "関連情報を含むエージェントのリストを取得します。") REST API を実行します。 {#AccA-runDiscovery_S__ul_yqc_3kj_z4b} {#AccA-runDiscovery_S__table_zk2_2g2_z4b__entry__3}{#AccA-runDiscovery_S__accAgents-parm-desc-agentID} | 名前 | タイプ | 説明 | |-|-|-| | agentID | 文字列 | Agent Client Collector \[sn_agent_cmdb_ci_agent\] テーブルの \[Agent ID\] 列にリストされるエージェントの一意の ID。 | [表 : 10. パラメーター] {#AccA-runDiscovery_S__table_zk2_2g2_z4b} {#AccA-runDiscovery_S__table_al2_2g2_z4b__entry__2} | タイプ | 説明 | |-|-| | 文字列 | 該当する場合はエラーメッセージ、それ以外の場合は null。例：`Agent With ID: Is Not Up: no thrown error` | [表 : 11. 返される内容] {#AccA-runDiscovery_S__table_al2_2g2_z4b} 次の例は、アライブ/稼働ステータスのエージェントで検出を実行する方法を示しています。 var agentsApi = new sn_agent.AccAgentsAPI(); var err = agentsApi.runDiscovery(""); if (!gs.nil(err)) gs.error(err); ## AccAgentsAPI - setDataCollectionStatus(文字列 agentID, ブール status) {#ariaid-title8} 指定されたエージェントの指定されたデータ収集ステータス (true/false、有効かどうか) を設定します。 エージェント ID のリストを取得するには： * getAgentsList() メソッドを実行します。 * Agent Client Collector \[sn_agent_cmdb_ci_agent\] テーブルの \[Agent ID\] 列を確認します。 * [Agent Client Collector GET list](https://servicenow-prod.fluidtopics.net/Id71AT_lAinkjm~KVoTIag#agnt_clnt_cll-GET-list "関連情報を含むエージェントのリストを取得します。") REST API を実行します。 {#AccA-setDataCollectionStatus_S_B__ul_yqc_3kj_z4b} {#AccA-setDataCollectionStatus_S_B__table_zk2_2g2_z4b__entry__3}{#AccA-setDataCollectionStatus_S_B__accAgents-parm-desc-agentID} | 名前 | タイプ | 説明 | |-|-|-| | agentID | 文字列 | Agent Client Collector \[sn_agent_cmdb_ci_agent\] テーブルの \[Agent ID\] 列にリストされるエージェントの一意の ID。 | | status | ブーリアン | エージェントのデータ収集が有効かどうかを示すフラグ。 有効な値： * true：このエージェントのデータ収集を有効にします。 * false：このエージェントのデータ収集を無効にします。 {#AccA-setDataCollectionStatus_S_B__ul_iv2_jcz_bpb} デフォルト：true | [表 : 12. パラメーター] {#AccA-setDataCollectionStatus_S_B__table_zk2_2g2_z4b} {#AccA-setDataCollectionStatus_S_B__table_al2_2g2_z4b__entry__2} | タイプ | 説明 | |-|-| | 文字列 | 該当する場合はエラーメッセージ、それ以外の場合は null。例：`Agent With ID: Is Not Up: no thrown error` | [表 : 13. 返される内容] {#AccA-setDataCollectionStatus_S_B__table_al2_2g2_z4b} 次の例は、エージェントのデータ収集を有効にする方法を示しています。 var agentsApi = new sn_agent.AccAgentsAPI(); var err = agentsApi.setDataCollectionStatus("", true); if (!gs.nil(err)) gs.error(err); 次の例は、エージェントのデータ収集を無効にする方法を示しています。 var agentsApi = new sn_agent.AccAgentsAPI(); var err = agentsApi.setDataCollectionStatus("", false); if (!gs.nil(err)) gs.error(err); ## AccAgentsAPI - sendGrabLogRequest(文字列 agentId) {#ariaid-title9} アライブ/稼働ステータスの指定されたエージェントのログを要求します。 注: ログを取得してその進捗状況を確認するには、返された要求 ID を checkGrabLogRequestProgress() メソッドに渡します。 {#AccA-submitGrabLogRequest_S__table_zk2_2g2_z4b__entry__3}{#AccA-submitGrabLogRequest_S__accAgents-parm-desc-agentID} | 名前 | タイプ | 説明 | |-|-|-| | agentID | 文字列 | Agent Client Collector \[sn_agent_cmdb_ci_agent\] テーブルの \[Agent ID\] 列にリストされるエージェントの一意の ID。 | [表 : 14. パラメーター] {#AccA-submitGrabLogRequest_S__table_zk2_2g2_z4b} {#AccA-submitGrabLogRequest_S__table_al2_2g2_z4b__entry__2} | プロパティ | 説明 | |-|-| | \ | 要求 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}/ により要求のステータスを取得できます。 データタイプ：文字列 | [表 : 15. 返される内容] {#AccA-submitGrabLogRequest_S__table_al2_2g2_z4b} 次の例は、ログ要求 ID を取得する方法を示しています。 var agentsApi = new sn_agent.AccAgentsAPI(); var submittedRequest = agentsApi.submitGrabLogRequest(""); if (!gs.nil(submittedRequest.error)) gs.error(submittedRequest.error); else gs.info("Request ID: " + submittedRequest.request_id); 出力： Request ID: