AcAgentsAPI - Com escopo

  • Versão de lançamento: Zurich
  • Atualizado 31 de jul. de 2025
  • 10 min. de leitura

    • . AcAgentsAPI a inclusão de script permite que você execute ações de gestão nos agentes disponíveis.

    Esta inclusão de script requer Agent Client Collector Estrutura (sn_agent) armazena a aplicação e é fornecida no sn_agent namespace. Para obter mais informações, consulte Agent Client Collector .

    Para obter a solução REST API, consulte API do Agent Client Collector .

    Esta inclusão de script fornece métodos que permitem o seguinte:
    • Obter informações abrangentes de um ou mais agentes.
    • Enviando uma solicitação para obter um log de agente e recuperar informações sobre o andamento da solicitação.
    • Iniciando ou interrompendo a coleta de dados.
    • Reiniciando um agente.
    • Executando descoberta em um agente.

    AccAgentsAPI - AccAgentsAPI()

    Cria uma instância da API AccAgents.

    Tabela 1. Parâmetros
    Nome Tipo Descrição
    Nenhum(a)

    O exemplo a seguir mostra como inicializar AcAgentsAPI .

    var agentsApi = new sn_agent.AccAgentsAPI();

    AccAgentsAPI - checkGrabLogRequestProgress(cadeia de caracteres requestId)

    Verifica o status de uma solicitação de log de captura.

    Execute o. GrabLogRequest() Método para obter um ID de solicitação.

    Tabela 2. Parâmetros
    Nome Tipo Descrição
    requestId Cadeia de caracteres Sys_id de uma solicitação na tabela Solicitações do Agent Client Collector [sn_agent_request].
    Tabela 3. Retornos
    Propriedades Descrição
    <Object> Objeto JSON que contém o status da solicitação de log de captura.
    {
  "status": Number,
  "output": "String"
}
    status Número que indica o status da solicitação de log de captura.
    Valores possíveis:
    • 0: A solicitação de registro de captura está concluída.
    • 1: Obter solicitação de log em andamento.
    • 2: Tempo limite da solicitação de registro de captura esgotado.
    • 3: A solicitação de registro de captura tem um erro.
    • 4: A solicitação de registro de captura não foi encontrada.
    saída Informações que descrevem o status.

    O exemplo a seguir mostra como usar um ID de solicitação para obter o status de uma solicitação de log de captura.

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

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

    Saída:

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

    AccAgentsAPI - getAgent (cadeia de caracteres AgentID)

    Obtém as informações de um agente especificado.

    Para obter uma lista de IDs de agente:
    • Execute o. GetAgentsList() método.
    • Verifique a coluna ID do agente da tabela Coletores de cliente do agente [sn_agent_cmdb_ci_agent].
    • Execute o. OBTER lista do Agent Client Collector REST API.
    Tabela 4. Parâmetros
    Nome Tipo Descrição
    AgentID Cadeia de caracteres ID exclusivo de um agente listado na coluna ID do agente da tabela Coletores de cliente do agente [sn_agent_cmdb_ci_agent].
    Tabela 5. Retornos
    Propriedades Descrição
    <Object> Objeto que contém informações estendidas do agente.
    {
  "error": String,
  "agent": Object
}
    erro Mensagens de erro Nulo se não houver erro.

    Tipo de dados: Cadeia de caracteres
    agente 
    "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 do agente conforme enviado.

    Tipo de dados: Cadeia de caracteres
    agent.data_collection A coleta de dados indica se as verificações programadas devem ser executadas. Essas verificações fazem parte das políticas programadas para a execução deste agente.
    Valores possíveis:
    • 0: Ativado - Verificações executadas conforme programado.
    • 1: Desligado (manual) - As verificações foram desabilitadas manualmente.
    • 2: Desligado (automático) - As verificações foram desabilitadas automaticamente devido ao alto consumo de CPU pelo

    Tipo de dados: Número
    agent.ip_address Endereço IP do agente.

    Tipo de dados: Cadeia de caracteres
    agent.is_duplicate

    Sinalizador que indica se este agente é uma duplicata de outro. Deve haver apenas um único agente em um determinado host.

    Valores possíveis:
    • Verdadeiro: O agente tem o mesmo host que um agente Ativo/Ativo com um ID de agente diferente. Desative ou desinstale a duplicata
    • Falso: Este agente não tem duplicatas no estado Ativo/Ativo.

    Tipo de dados: Booliano
    agent.is_restart_enabled

    Sinalizador que indica se a reinicialização está habilitada. A reinicialização do agente não é configurável. Depende do SO e da versão do SO em que o agente está sendo executado.

    Valores possíveis:
    • Verdadeiro: A reinicialização está habilitada para este agente.
    • Falso: A reinicialização está desabilitada para este agente.

    Tipo de dados: Booliano
    agent.name Nome do agente.

    Tipo de dados: Cadeia de caracteres
    agent.number_of_running_checks O número de verificações que o agente está programado para executar. Essas verificações fazem parte das políticas programadas para a execução deste agente.

    Tipo de dados: Número
    agent.status Status do agente.
    Valores possíveis:
    • Ativo/Ativo - O agente está ativo 0.
    • 1: Aviso - O agente não recebeu uma mensagem de keep-alive nos últimos minutos.
    • 2: Inativo - O agente não recebeu uma mensagem de keep-alive há muito tempo.
    • 3: Reiniciando - O agente está reiniciando.

    Tipo de dados: Número
    agent.up_since Hora UTC desde que o status do agente se tornou ativo/ativo. O valor está em GlideDateTime formato.

    Tipo de dados: Cadeia de caracteres
    agent.version Versão de Agent Client Collector o agente está em execução.

    Tipo de dados: Cadeia de caracteres

    O exemplo a seguir mostra como exibir o status de um agente.

    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);

    Saída:

    agent status: 2

    O exemplo a seguir mostra como obter todos os detalhes do agente.

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

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

    Saída:

    {
  "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"
  }
}

    AccAgentsList – getAgentsList(String encodedQuery, limite de número)

    Obtém uma lista de agentes com informações relacionadas.

    Tabela 6. Parâmetros
    Nome Tipo Descrição
    encodedQuery Cadeia de caracteres Cadeia de caracteres de consulta codificada no formato Glide padrão. Consulte Cadeias de caracteres de consulta codificadas .
    limite Número Opcional. Restringe os resultados a um número máximo de agentes. Use nulo ou indefinido para ambos se eles não forem necessários.

    Padrão/Máximo: 20 000
    Tabela 7. Retornos
    Propriedade Descrição
    <Array> Matriz de objetos JSON que contém informações estendidas do agente.
    [
 {
   "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 do agente conforme enviado.

    Tipo de dados: Cadeia de caracteres
    data_collection A coleta de dados indica se as verificações programadas devem ser executadas. Essas verificações fazem parte das políticas programadas para a execução deste agente.
    Valores possíveis:
    • 0: Ativado - Verificações executadas conforme programado.
    • 1: Desligado (manual) - As verificações foram desabilitadas manualmente.
    • 2: Desligado (automático) - As verificações foram desabilitadas automaticamente devido ao alto consumo de CPU pelo

    Tipo de dados: Número
    ip_address Endereço IP do agente.

    Tipo de dados: Cadeia de caracteres
    _duplicate

    Sinalizador que indica se este agente é uma duplicata de outro. Deve haver apenas um único agente em um determinado host.

    Valores possíveis:
    • Verdadeiro: O agente tem o mesmo host que um agente Ativo/Ativo com um ID de agente diferente. Desative ou desinstale a duplicata
    • Falso: Este agente não tem duplicatas no estado Ativo/Ativo.

    Tipo de dados: Booliano
    _restart_enabled

    Sinalizador que indica se a reinicialização está habilitada. A reinicialização do agente não é configurável. Depende do SO e da versão do SO em que o agente está sendo executado.

    Valores possíveis:
    • Verdadeiro: A reinicialização está habilitada para este agente.
    • Falso: A reinicialização está desabilitada para este agente.

    Tipo de dados: Booliano
    nome Nome do agente.

    Tipo de dados: Cadeia de caracteres
    number_of_running_checks O número de verificações que o agente está programado para executar. Essas verificações fazem parte das políticas programadas para a execução deste agente.

    Tipo de dados: Número
    status Status do agente.
    Valores possíveis:
    • Ativo/Ativo - O agente está ativo 0.
    • 1: Aviso - O agente não recebeu uma mensagem de keep-alive nos últimos minutos.
    • 2: Inativo - O agente não recebeu uma mensagem de keep-alive há muito tempo.
    • 3: Reiniciando - O agente está reiniciando.

    Tipo de dados: Número
    up_since Hora UTC desde que o status do agente se tornou ativo/ativo. O valor está em GlideDateTime formato.

    Tipo de dados: Cadeia de caracteres
    versão Versão de Agent Client Collector o agente está em execução.

    Tipo de dados: Cadeia de caracteres

    O exemplo a seguir mostra como restringir resultados por consulta e número. A consulta retorna todos os agentes que não estão no estado inativo com no máximo dois resultados.

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

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

    Saída:

    [
  {
    "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"
  }
]

    O exemplo a seguir mostra como listar todos os agentes no sistema. Este exemplo não usa consulta e nenhum número máximo de resultados.

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

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

    O exemplo a seguir mostra como iterar os resultados fornecidos e exibe cada ID de agente.

    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);

    Saída:

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

    AccAgentsAPI - restartAgent (cadeia de caracteres AgentID)

    Reinicia um agente especificado com status ativo/ativo.

    Se Agent Client Collector ocorrem problemas de desempenho, você pode reiniciar o agente. A reinicialização manual é compatível com os seguintes ambientes:
    • Agentes baseados em Linux usando systemd
    • Agentes do Windows
    Para obter uma lista de IDs de agente:
    • Execute o. GetAgentsList() método.
    • Verifique a coluna ID do agente da tabela Coletores de cliente do agente [sn_agent_cmdb_ci_agent].
    • Execute o. OBTER lista do Agent Client Collector REST API.
    Tabela 8. Parâmetros
    Nome Tipo Descrição
    AgentID Cadeia de caracteres ID exclusivo de um agente listado na coluna ID do agente da tabela Coletores de cliente do agente [sn_agent_cmdb_ci_agent].
    Tabela 9. Retornos
    Tipo Descrição
    Cadeia de caracteres Mensagem de erro, se aplicável, caso contrário, nula.

    O exemplo a seguir mostra como reiniciar um agente.

    var agentsApi = new sn_agent.AccAgentsAPI();

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

    AccAgentsAPI - runDiscovery (cadeia de caracteres AgentID)

    Executa uma verificação de descoberta para localizar ICs relacionados a um agente. O agente especificado deve estar no status ativo/ativo.

    Para obter uma lista de IDs de agente:
    • Execute o. GetAgentsList() método.
    • Verifique a coluna ID do agente da tabela Coletores de cliente do agente [sn_agent_cmdb_ci_agent].
    • Execute o. OBTER lista do Agent Client Collector REST API.
    Tabela 10. Parâmetros
    Nome Tipo Descrição
    AgentID Cadeia de caracteres ID exclusivo de um agente listado na coluna ID do agente da tabela Coletores de cliente do agente [sn_agent_cmdb_ci_agent].
    Tabela 11. Retornos
    Tipo Descrição
    Cadeia de caracteres Mensagem de erro, se aplicável, caso contrário, nula. Por exemplo, Agente com ID: O <agentID> não está ativo: nenhum erro gerado .

    O exemplo a seguir mostra como executar a descoberta em um agente com status ativo/ativo.

    var agentsApi = new sn_agent.AccAgentsAPI();

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

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

    AccAgentsAPI - setDataCollectionStatus(cadeia de caracteres AgentID, status booliano)

    Defina o status de coleta de dados fornecido (verdadeiro/falso se habilitado ou não) para um agente especificado.

    Para obter uma lista de IDs de agente:
    • Execute o. GetAgentsList() método.
    • Verifique a coluna ID do agente da tabela Coletores de cliente do agente [sn_agent_cmdb_ci_agent].
    • Execute o. OBTER lista do Agent Client Collector REST API.
    Tabela 12. Parâmetros
    Nome Tipo Descrição
    AgentID Cadeia de caracteres ID exclusivo de um agente listado na coluna ID do agente da tabela Coletores de cliente do agente [sn_agent_cmdb_ci_agent].
    status Booliano

    Sinalizador que indica se a coleta de dados está habilitada para o agente.

    Valores válidos:
    • Verdadeiro: Habilita a coleta de dados para este agente.
    • Falso: Desabilita a coleta de dados para este agente.

    Padrão: verdadeiro
    Tabela 13. Retornos
    Tipo Descrição
    Cadeia de caracteres Mensagem de erro, se aplicável, caso contrário, nula. Por exemplo, Agente com ID: O <agentID> não está ativo: nenhum erro gerado .

    O exemplo a seguir mostra como ativar a coleta de dados do agente.

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

    O exemplo a seguir mostra como desativar a coleta de dados do agente.

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

    AccAgentsAPI - submitGrabLogRequest(cadeia de caracteres agentId)

    Solicita o log de um agente especificado com status ativo/ativo.

    Nota:
    Para recuperar o log e verificar seu andamento, passe o ID da solicitação retornado para GrabLogRequestProgress() método.
    Tabela 14. Parâmetros
    Nome Tipo Descrição
    AgentID Cadeia de caracteres ID exclusivo de um agente listado na coluna ID do agente da tabela Coletores de cliente do agente [sn_agent_cmdb_ci_agent].
    Tabela 15. Retornos
    Propriedades Descrição
    <Object> Objeto JSON que contém o ID da solicitação e todas as informações de erro.
    {
  "error": "String",
  "request_id": "String"
}
    erro Mensagens de erro Nulo se não houver erro.

    Tipo de dados: Cadeia de caracteres
    request_id Sys_id de uma solicitação na tabela Solicitações do Agent Client Collector [sn_agent_request].

    Você pode usar este ID para obter o status da solicitação usando OBTENHA /agents/request_id/ .

    Tipo de dados: Cadeia de caracteres

    O exemplo a seguir mostra como obter um ID de solicitação de log.

    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);

    Saída:

    Request ID: <sys_id>