AccAgentsAPI - com escopo

  • Versão de lançamento: Xanadu
  • Atualizado 1 de ago. de 2024
  • 10 min. de leitura

    • A inclusão de script AccAgentsAPI permite que você execute ações de gerenciamento em agentes disponíveis.

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

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

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

    AccAgentsAPI - AccAgentsAPI()

    Cria uma instância AccAgentsAPI.

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

    O exemplo a seguir mostra como inicializar AccAgentsAPI.

    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 método submitGrabLogRequest() 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. Retorna
    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 log de captura foi concluída.
    • 1: solicitação de log de captura em andamento.
    • 2: a solicitação de log de obtenção expirou.
    • 3: a solicitação de log de captura tem um erro.
    • 4: a solicitação de log 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 método getAgentsList().
    • Verifique a coluna ID do agente da tabela Agent Client Collectors [sn_agent_cmdb_ci_agent].
    • Execute a API REST da lista GET do Agent Client Collector.
    Tabela 4. Parâmetros
    Nome Tipo Descrição
    ID do agente Cadeia de caracteres ID exclusivo de um agente listado na coluna ID do agente da tabela Agent Client Collectors [sn_agent_cmdb_ci_agent].
    Tabela 5. Retorna
    Propriedades Descrição
    <Object> Objeto que contém informações do agente estendido.
    {
  "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
    agente.coleção_de_dados 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: Desativado (manual) – As verificações foram desativadas manualmente.
    • 2: Desativado (automático) – As verificações foram desativadas automaticamente devido ao alto consumo de CPU pelo

    Tipo de dados: número
    agente.endereço_ip Endereço IP do agente.

    Tipo de dados: cadeia de caracteres
    agente.é_duplicado

    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. Desativar ou desinstalar 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 sistema operacional e da versão do sistema operacional 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
    agente.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
    agente.status Status do agente.
    Valores possíveis:
    • 0: Ativo/Ativo – O agente está ativo.
    • 1: Aviso – O agente não recebeu uma mensagem de manutenção de atividade nos últimos minutos.
    • 2: Inativo – O agente não recebe uma mensagem de manutenção de atividade 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á no formato GlideDateTime.

    Tipo de dados: cadeia de caracteres
    agent.version Versão de Agent Client Collector que o agente está executando.

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

    AccAgentsAPI – getAgentsList(cadeia de caracteres 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 não forem necessários.

    Padrão/Máx.: 20.000
    Tabela 7. Retorna
    Propriedade Descrição
    <Array> Matriz de objetos JSON que contém informações do agente estendido.
    [
 {
   "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
    coleta_dados 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: Desativado (manual) – As verificações foram desativadas manualmente.
    • 2: Desativado (automático) – As verificações foram desativadas 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
    está_duplicado

    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. Desativar ou desinstalar a duplicata
    • falso: este agente não tem duplicatas no estado Ativo/Ativo.

    Tipo de dados: booliano
    is_restart_enabled

    Sinalizador que indica se a reinicialização está habilitada. A reinicialização do agente não é configurável. Depende do sistema operacional e da versão do sistema operacional 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
    número_de_verificações_em_execução 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:
    • 0: Ativo/Ativo – O agente está ativo.
    • 1: Aviso – O agente não recebeu uma mensagem de manutenção de atividade nos últimos minutos.
    • 2: Inativo – O agente não recebe uma mensagem de manutenção de atividade há muito tempo.
    • 3: Reiniciando – O agente está reiniciando.

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

    Tipo de dados: cadeia de caracteres
    versão Versão de Agent Client Collector que o agente está executando.

    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 um máximo de 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 do sistema. Este exemplo não usa nenhuma 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 o ID de cada 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 ocorrerem Agent Client Collector problemas de desempenho, você poderá 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 método getAgentsList().
    • Verifique a coluna ID do agente da tabela Agent Client Collectors [sn_agent_cmdb_ci_agent].
    • Execute a API REST da lista GET do Agent Client Collector.
    Tabela 8. Parâmetros
    Nome Tipo Descrição
    ID do agente Cadeia de caracteres ID exclusivo de um agente listado na coluna ID do agente da tabela Agent Client Collectors [sn_agent_cmdb_ci_agent].
    Tabela 9. Retorna
    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 método getAgentsList().
    • Verifique a coluna ID do agente da tabela Agent Client Collectors [sn_agent_cmdb_ci_agent].
    • Execute a API REST da lista GET do Agent Client Collector.
    Tabela 10. Parâmetros
    Nome Tipo Descrição
    ID do agente Cadeia de caracteres ID exclusivo de um agente listado na coluna ID do agente da tabela Agent Client Collectors [sn_agent_cmdb_ci_agent].
    Tabela 11. Retorna
    Tipo Descrição
    Cadeia de caracteres Mensagem de erro se aplicável, caso contrário, nula. Por exemplo, Agente com ID:<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 método getAgentsList().
    • Verifique a coluna ID do agente da tabela Agent Client Collectors [sn_agent_cmdb_ci_agent].
    • Execute a API REST da lista GET do Agent Client Collector.
    Tabela 12. Parâmetros
    Nome Tipo Descrição
    ID do agente Cadeia de caracteres ID exclusivo de um agente listado na coluna ID do agente da tabela Agent Client Collectors [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. Retorna
    Tipo Descrição
    Cadeia de caracteres Mensagem de erro se aplicável, caso contrário, nula. Por exemplo, Agente com ID:<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 de solicitação retornado para o método checkGrabLogRequestProgress().
    Tabela 14. Parâmetros
    Nome Tipo Descrição
    ID do agente Cadeia de caracteres ID exclusivo de um agente listado na coluna ID do agente da tabela Agent Client Collectors [sn_agent_cmdb_ci_agent].
    Tabela 15. Retorna
    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 GET /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>