AccAgentsAPI - 범위 지정됨

Yokohama API 참조

Release

yokohama

ft:locale

ko-KR

ft:publication_title

Yokohama API 참조

ft:clusterId

crapiref

bundleId

crapiref

workflow

Creator

AccAgentsAPI - 범위 지정됨

릴리스 버전: Yokohama

업데이트 날짜 2025년 01월 30일

읽기16분

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

이 스크립트 포함에는 프레임워크(sn_agent) 스토어 애플리케이션이 필요하며 에이전트 클라이언트 수집기sn_agent 네임스페이스 내에서 제공됩니다. 자세한 내용은 에이전트 클라이언트 수집기를 참조하십시오.

REST API 솔루션은 에이전트 클라이언트 수집기 API를 참조하십시오.

이 스크립트 포함은 다음을 가능하게 하는 메서드를 제공합니다.

하나 이상의 에이전트에 대한 광범위한 정보 가져오기
에이전트 로그를 가져오는 요청을 제출하고 요청 진행 상황에 대한 정보를 검색합니다.
데이터 수집 시작 또는 중지 중
에이전트를 다시 시작합니다.
에이전트에서 검색 실행

AccAgentsAPI - AccAgentsAPI()

AccAgentsAPI 인스턴스를 작성합니다.

표 1. 매개변수
이름	유형	설명
안 함

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

var agentsApi = new sn_agent.AccAgentsAPI();

AccAgentsAPI - checkGrabLogRequestProgress(문자열 requestId)

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

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

표 2. 매개변수
이름	유형	설명
requestId	문자열	에이전트 클라이언트 수집기 요청 [sn_agent_request] 테이블의 요청 Sys_id입니다.

표 3. 반환
속성	설명
<Object>	그랩 로그 요청 상태를 포함하는 JSON 객체입니다. `{ "status": Number, "output": "String" }`
상태	그랩 로그 요청의 상태를 나타내는 번호입니다. 가능한 값: 0: 로그 요청 가져오기가 완료되었습니다. 1: 진행 중인 로그 요청을 가져옵니다. 2: 로그 요청 가져오기 시간이 초과되었습니다. 3: 로그 요청 가져오기에 오류가 있습니다. 4: 로그 요청 확보를 찾을 수 없습니다.
출력	상태를 설명하는 정보입니다.

다음 예제에서는 요청 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 Collectors [sn_agent_cmdb_ci_agent] 테이블의 에이전트 ID 열을 확인합니다.
에이전트 클라이언트 수집기 GET 목록 REST API를 실행합니다.

표 4. 매개변수
이름	유형	설명
에이전트 ID	문자열	에이전트 클라이언트 수집기 [sn_agent_cmdb_ci_agent] 테이블의 에이전트 ID 열에 나열된 에이전트의 고유 ID입니다.

표 5. 반환
속성	설명
<Object>	확장된 에이전트 정보를 포함하는 객체입니다. `{ "error": String, "agent": Object }`
오류	오류 메시지. 오류가 없는 경우 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: 이 에이전트에는 활성/가동 상태의 중복 항목이 없습니다. 데이터 유형: 부울
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	에이전트의 에이전트 클라이언트 수집기 버전이 실행 중입니다. 데이터 유형: 문자열

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

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(String encodedQuery, 개수 제한)

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

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

표 7. 반환
속성	설명
<배열>	확장 에이전트 정보를 포함하는 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: 이 에이전트에는 활성/가동 상태의 중복 항목이 없습니다. 데이터 유형: 부울
is_restart_enabled	다시 시작을 사용할 수 있는지 여부를 나타내는 플래그입니다. 에이전트 다시 시작은 구성할 수 없습니다. OS 및 에이전트가 실행 중인 OS 버전에 따라 다릅니다. 가능한 값: true: 이 에이전트에 대해 다시 시작이 활성화됩니다. false: 이 에이전트에 대한 다시 시작이 비활성화되었습니다. 데이터 유형: 부울
이름	에이전트의 이름입니다. 데이터 유형: 문자열
number_of_running_checks	에이전트가 실행하도록 예약된 검사 수입니다. 이러한 검사는 이 에이전트가 실행되도록 예약된 정책의 일부입니다. 데이터 유형: 숫자
상태	에이전트의 상태입니다. 가능한 값: 0: Alive/Up – 에이전트가 활성 상태입니다. 1: 경고 – 에이전트가 지난 몇 분 동안 연결 유지 메시지를 받지 못했습니다. 2: 다운 – 에이전트가 오랫동안 연결 유지 메시지를 받지 못했습니다. 3: 다시 시작 – 에이전트가 다시 시작됩니다. 데이터 유형: 숫자
up_since	에이전트 상태가 활성 상태가 된 이후의 UTC 시간입니다. 값은 GlideDateTime 형식입니다. 데이터 유형: 문자열
버전	에이전트의 에이전트 클라이언트 수집기 버전이 실행 중입니다. 데이터 유형: 문자열

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

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

성능 문제가 발생하면 에이전트 클라이언트 수집기 에이전트를 다시 시작할 수 있습니다. 수동 다시 시작은 다음 환경에서 지원됩니다.

systemd를 사용하는 Linux 기반 에이전트
Windows 에이전트

에이전트 ID 목록을 얻으려면 다음을 수행합니다.

getAgentsList() 메서드를 실행합니다.
Agent Client Collectors [sn_agent_cmdb_ci_agent] 테이블의 에이전트 ID 열을 확인합니다.
에이전트 클라이언트 수집기 GET 목록 REST API를 실행합니다.

표 8. 매개변수
이름	유형	설명
에이전트 ID	문자열	에이전트 클라이언트 수집기 [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 Collectors [sn_agent_cmdb_ci_agent] 테이블의 에이전트 ID 열을 확인합니다.
에이전트 클라이언트 수집기 GET 목록 REST API를 실행합니다.

표 10. 매개변수
이름	유형	설명
에이전트 ID	문자열	에이전트 클라이언트 수집기 [sn_agent_cmdb_ci_agent] 테이블의 에이전트 ID 열에 나열된 에이전트의 고유 ID입니다.

표 11. 반환
유형	설명
문자열	해당하는 경우 오류 메시지, 그렇지 않으면 null입니다. 예를 들어 `ID가 <agentID인 에이전트가 > 상태가 좋지 않음: throw 오류가 없습니다`.

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

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 Collectors [sn_agent_cmdb_ci_agent] 테이블의 에이전트 ID 열을 확인합니다.
에이전트 클라이언트 수집기 GET 목록 REST API를 실행합니다.

표 12. 매개변수
이름	유형	설명
에이전트 ID	문자열	에이전트 클라이언트 수집기 [sn_agent_cmdb_ci_agent] 테이블의 에이전트 ID 열에 나열된 에이전트의 고유 ID입니다.
상태	부울	에이전트에 대해 데이터 수집이 활성화되어 있는지 여부를 나타내는 플래그입니다. 유효한 값은 다음과 같습니다. true: 이 에이전트에 대해 데이터 수집을 활성화합니다. false: 이 에이전트에 대한 데이터 수집을 비활성화합니다. 기본값: true

표 13. 반환
유형	설명
문자열	해당하는 경우 오류 메시지, 그렇지 않으면 null입니다. 예를 들어 `ID가 <agentID인 에이전트가 > 상태가 좋지 않음: throw 오류가 없습니다`.

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

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	문자열	에이전트 클라이언트 수집기 [sn_agent_cmdb_ci_agent] 테이블의 에이전트 ID 열에 나열된 에이전트의 고유 ID입니다.

표 15. 반환
속성	설명
<Object>	요청 ID 및 오류 정보를 포함하는 JSON 객체입니다. `{ "error": "String", "request_id": "String" }`
오류	오류 메시지. 오류가 없는 경우 Null입니다. 데이터 유형: 문자열
request_id	에이전트 클라이언트 수집기 요청 [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>