AccAgentsAPI - 범위 지정됨

  • 릴리스 버전: Washingtondc
  • 업데이트 날짜 2024년 02월 01일
  • 읽기17분

    • AccAgentsAPI 스크립트 포함을 사용하면 사용 가능한 에이전트에 대한 관리 작업을 수행할 수 있습니다.

    이 API에는 Framework(sn_agent) 스토어 애플리케이션이 필요 Agent Client Collector 하며 sn_agent 네임스페이스 내에서 제공됩니다. 자세한 내용은 Agent Client Collector를 참조하십시오.

    REST API 솔루션은 Agent Client Collector API 를 참조하십시오 .

    이 API에는 다음을 가능하게 하는 메서드가 포함되어 있습니다.
    • 한 명 이상의 에이전트에 대한 광범위한 정보를 가져옵니다.
    • 에이전트 로그를 가져오기 위한 요청을 제출하고 요청 진행에 대한 정보를 검색합니다.
    • 데이터 수집을 시작 또는 중지합니다.
    • 에이전트를 다시 시작합니다.
    • 에이전트에서 검색 실행

    AccAgentsAPI - AccAgentsAPI()

    AccAgentsAPI 인스턴스를 만듭니다.

    표 1. 매개변수
    이름 유형 설명
    없음

    다음 예제에서는 AccAgentsAPI를 초기화하는 방법을 보여 줍니다.

    var agentsApi = new sn_agent.AccAgentsAPI();

    AccAgentsAPI - checkGrabLogRequestProgress(requestId 문자열)

    그랩 로그 요청의 상태를 확인합니다.

    submitGrabLogRequest() 메서드를 실행하여 요청 ID를 가져옵니다.

    표 2. 매개변수
    이름 유형 설명
    requestId 문자열 Agent Client Collector 요청 [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] 테이블의 에이전트 ID 열을 확인합니다.
    • Agent Client Collector GET 목록 REST API를 실행합니다.
    표 4. 매개변수
    이름 유형 설명
    에이전트 ID 문자열 Agent Client Collector [sn_agent_cmdb_ci_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

    이 에이전트가 다른 에이전트와 중복되는지 여부를 나타내는 플래그입니다. 지정된 호스트에는 에이전트가 하나만 있어야 합니다.

    가능한 값:
    • true: 에이전트는 다른 에이전트 ID를 사용하여 Alive/Up 에이전트와 동일한 호스트를 가지고 있습니다. 복제본 끄기 또는 제거
    • false: 이 에이전트에 Alive/Up 상태의 중복 항목이 없습니다.

    데이터 유형: 부울
    agent.is_restart_enabled

    다시 시작할 수 있는지 여부를 나타내는 플래그입니다. 에이전트 다시 시작은 구성할 수 없습니다. OS 및 에이전트가 실행 중인 OS 버전에 따라 다릅니다.

    가능한 값:
    • true: 이 에이전트에 대해 다시 시작이 활성화됩니다.
    • false: 이 에이전트에 대해 다시 시작이 비활성화됩니다.

    데이터 유형: 부울
    agent.name 에이전트의 이름입니다.

    데이터 유형: 문자열
    agent.number_of_running_checks 에이전트가 실행되도록 예약된 검사 수입니다. 이러한 검사는 이 에이전트가 실행되도록 예약된 정책의 일부입니다.

    데이터 유형: 숫자
    agent.status 에이전트의 상태입니다.
    가능한 값:
    • 0: Alive/Up – 에이전트가 활성 상태입니다.
    • 1: 경고 – 에이전트가 지난 몇 분 동안 연결 유지 메시지를 받지 못했습니다.
    • 2: 다운 – 에이전트가 오랫동안 연결 유지 메시지를 받지 못했습니다.
    • 3: 다시 시작 중 – 에이전트가 다시 시작됩니다.

    데이터 유형: 숫자
    agent.up_since 에이전트의 상태가 활성/작동 상태가 된 이후의 UTC 시간입니다. 값은 GlideDateTime 형식입니다.

    데이터 유형: 문자열
    agent.version 에이전트의 Agent Client Collector 버전이 실행 중입니다.

    데이터 유형: 문자열

    다음 예제에서는 에이전트의 상태를 표시하는 방법을 보여줍니다.

    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 문자열, 숫자 제한)

    관련 정보가 있는 에이전트 목록을 가져옵니다.

    표 6. 매개변수
    이름 유형 설명
    encodedQuery 문자열 표준 Glide 형식으로 인코딩된 쿼리 문자열입니다. 인코딩된 쿼리 문자열을 참조하세요.
    제한 번호 옵션입니다. 결과를 최대 에이전트 수로 제한합니다. 필요하지 않은 경우 둘 다에 대해 null 또는 undefined를 사용합니다.

    기본/최대: 20,000
    표 7. 반환
    속성 설명
    &lt;배열> 확장 에이전트 정보를 포함하는 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

    이 에이전트가 다른 에이전트와 중복되는지 여부를 나타내는 플래그입니다. 지정된 호스트에는 에이전트가 하나만 있어야 합니다.

    가능한 값:
    • true: 에이전트는 다른 에이전트 ID를 사용하여 Alive/Up 에이전트와 동일한 호스트를 가지고 있습니다. 복제본 끄기 또는 제거
    • false: 이 에이전트에 Alive/Up 상태의 중복 항목이 없습니다.

    데이터 유형: 부울
    is_restart_enabled

    다시 시작할 수 있는지 여부를 나타내는 플래그입니다. 에이전트 다시 시작은 구성할 수 없습니다. OS 및 에이전트가 실행 중인 OS 버전에 따라 다릅니다.

    가능한 값:
    • true: 이 에이전트에 대해 다시 시작이 활성화됩니다.
    • false: 이 에이전트에 대해 다시 시작이 비활성화됩니다.

    데이터 유형: 부울
    name 에이전트의 이름입니다.

    데이터 유형: 문자열
    number_of_running_checks 에이전트가 실행되도록 예약된 검사 수입니다. 이러한 검사는 이 에이전트가 실행되도록 예약된 정책의 일부입니다.

    데이터 유형: 숫자
    status 에이전트의 상태입니다.
    가능한 값:
    • 0: Alive/Up – 에이전트가 활성 상태입니다.
    • 1: 경고 – 에이전트가 지난 몇 분 동안 연결 유지 메시지를 받지 못했습니다.
    • 2: 다운 – 에이전트가 오랫동안 연결 유지 메시지를 받지 못했습니다.
    • 3: 다시 시작 중 – 에이전트가 다시 시작됩니다.

    데이터 유형: 숫자
    up_since 에이전트의 상태가 활성/작동 상태가 된 이후의 UTC 시간입니다. 값은 GlideDateTime 형식입니다.

    데이터 유형: 문자열
    version 에이전트의 Agent Client Collector 버전이 실행 중입니다.

    데이터 유형: 문자열

    다음 예제에서는 쿼리 및 번호로 결과를 제한하는 방법을 보여 줍니다. 쿼리는 최대 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(String agentID)

    지정된 에이전트를 활성/작동 상태로 다시 시작합니다.

    Agent Client Collector 성능 문제가 발생하면 에이전트를 다시 시작할 수 있습니다. 수동 다시 시작은 다음 환경에서 지원됩니다.
    • systemd를 사용하는 Linux 기반 에이전트
    • Windows 에이전트
    에이전트 ID 목록을 가져오려면 다음을 수행합니다.
    • getAgentsList() 메서드를 실행합니다.
    • Agent Client Collector [sn_agent_cmdb_ci_agent] 테이블의 에이전트 ID 열을 확인합니다.
    • Agent Client Collector GET 목록 REST API를 실행합니다.
    표 8. 매개변수
    이름 유형 설명
    에이전트 ID 문자열 Agent Client Collector [sn_agent_cmdb_ci_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] 테이블의 에이전트 ID 열을 확인합니다.
    • Agent Client Collector GET 목록 REST API를 실행합니다.
    표 10. 매개변수
    이름 유형 설명
    에이전트 ID 문자열 Agent Client Collector [sn_agent_cmdb_ci_agent] 테이블의 에이전트 ID 열에 나열된 에이전트의 고유 ID입니다.
    표 11. 반환
    유형 설명
    문자열 해당하는 경우 오류 메시지이고, 그렇지 않으면 null입니다. 예를 들어 , ID가 있는 에이전트: &lt;agentID>가 작동 중이 아님: 오류가 발생하지 않습니다.

    다음 예제에서는 활성/작동 중인 상태의 에이전트에서 검색을 실행하는 방법을 보여줍니다.

    var agentsApi = new sn_agent.AccAgentsAPI();

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

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

    AccAgentsAPI - setDataCollectionStatus(문자열, agentID, 부울 상태)

    지정된 에이전트에 대해 지정된 데이터 수집 상태(사용 여부와 관계없이 참/거짓)를 설정합니다.

    에이전트 ID 목록을 가져오려면 다음을 수행합니다.
    • getAgentsList() 메서드를 실행합니다.
    • Agent Client Collector [sn_agent_cmdb_ci_agent] 테이블의 에이전트 ID 열을 확인합니다.
    • Agent Client Collector GET 목록 REST API를 실행합니다.
    표 12. 매개변수
    이름 유형 설명
    에이전트 ID 문자열 Agent Client Collector [sn_agent_cmdb_ci_agent] 테이블의 에이전트 ID 열에 나열된 에이전트의 고유 ID입니다.
    status 부울

    에이전트에 데이터 수집을 사용할 수 있는지 여부를 나타내는 플래그입니다.

    유효한 값은 다음과 같습니다.
    • true: 이 에이전트에 대해 데이터 수집을 사용하도록 설정합니다.
    • false: 이 에이전트에 대한 데이터 수집을 사용하지 않도록 설정합니다.

    기본값: true
    표 13. 반환
    유형 설명
    문자열 해당하는 경우 오류 메시지이고, 그렇지 않으면 null입니다. 예를 들어 , ID가 있는 에이전트: &lt;agentID>가 작동 중이 아님: 오류가 발생하지 않습니다.

    다음 예는 에이전트 데이터 수집을 켜는 방법을 보여줍니다.

    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 - submitGrabLogRequest(agentId 문자열)

    활성/작동 상태인 지정된 에이전트의 로그를 요청합니다.

    주:
    로그를 검색하고 진행률을 확인하려면 반환된 요청 ID를 checkGrabLogRequestProgress() 메서드에 전달합니다.
    표 14. 매개변수
    이름 유형 설명
    에이전트 ID 문자열 Agent Client Collector [sn_agent_cmdb_ci_agent] 테이블의 에이전트 ID 열에 나열된 에이전트의 고유 ID입니다.
    표 15. 반환
    속성 설명
    <Object> 요청 ID 및 오류 정보를 포함하는 JSON 객체입니다.
    {
  "error": "String",
  "request_id": "String"
}
    error 오류 메시지. 오류가 없는 경우 Null입니다.

    데이터 유형: 문자열
    request_id Agent Client Collector 요청 [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>