AccAgentsAPI - 범위 지정됨

Xanadu API 참조

Release

xanadu

ft:locale

ko-KR

ft:publication_title

Xanadu API 참조

ft:clusterId

crapiref

bundleId

crapiref

workflow

Creator

AccAgentsAPI - 범위 지정됨

릴리스 버전: Xanadu

업데이트 날짜 2024년 08월 01일

읽기17분

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

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

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

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

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

AccAgentsAPI - AccAgentsAPI()

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

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

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

var agentsApi = new sn_agent.AccAgentsAPI();

AccAgentsAPI - checkGrabLogRequestProgress(문자열 requestId)

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

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

표 2. 매개변수
이름	유형	설명
requestId	문자열	Agent Client Collector 요청 [sn_agent_request] 테이블의 요청 Sys_id입니다.

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

다음 예제에서는 요청 ID를 사용하여 grab 로그 요청의 상태를 가져오는 방법을 보여 줍니다.

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

표 4. 매개변수
이름	유형	설명
agentID	문자열	Agent Client Collector [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(문자열 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(문자열 agentID)

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

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

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

에이전트 ID 목록을 가져오려면 다음을 수행합니다.

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

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

표 10. 매개변수
이름	유형	설명
agentID	문자열	Agent Client Collector [sn_agent_cmdb_ci_agent] 테이블의 에이전트 ID 열에 나열된 에이전트의 고유 ID입니다.

표 11. 반환
유형	설명
문자열	해당하는 경우 오류 메시지이고, 그렇지 않으면 null입니다. 예를 들어 `ID가 있는 에이전트: <agentID> is not up: 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 Collector [sn_agent_cmdb_ci_agent] 테이블의 에이전트 ID 열을 확인합니다.
에이전트 클라이언트 수집기 GET 목록 REST API를 실행합니다.

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

표 13. 반환
유형	설명
문자열	해당하는 경우 오류 메시지이고, 그렇지 않으면 null입니다. 예를 들어 `ID가 있는 에이전트: <agentID> is not up: 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. 매개변수
이름	유형	설명
agentID	문자열	Agent Client Collector [sn_agent_cmdb_ci_agent] 테이블의 에이전트 ID 열에 나열된 에이전트의 고유 ID입니다.

표 15. 반환
속성	설명
<Object>	요청 ID 및 오류 정보를 포함하는 JSON 객체입니다. `{ "error": "String", "request_id": "String" }`
오류	오류 메시지. 오류가 없는 경우 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>