AccAgentsAPI - com escopo

  • Versão de lançamento: Washingtondc
  • Atualizado 1 de fev. 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 obter a solução REST API, consulte Agent Client Collector API.

    Esta API inclui métodos que permitem o seguinte:
    • Obtenção de informações extensas de um ou mais agentes.
    • Enviar 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

    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: obter solicitação de log 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 REST API 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"
 }
    agente.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 este agente executar.
    Valores possíveis:
    • 0: Ativado – as verificações são 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
    agente.ip_address 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 este agente executar.

    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
    agente.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 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áximo: 20.000
    Tabela 7. Retorna
    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 este agente executar.
    Valores possíveis:
    • 0: Ativado – as verificações são 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
    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. 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
    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 este agente executar.

    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_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
    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 os 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 - reinicialização(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 REST API 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, nulo.

    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 REST API 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, nulo. 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, booliano status)

    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 REST API 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, nulo. 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 da 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 qualquer informação 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>