--- sourceDocument: Referência de API do Xanadu sourceDocumentLink: https://servicenow-prod.fluidtopics.net/r/pt-BR/xanadu/api-reference Release : - xanadu ft:locale : - pt-BR ft:publication_title : - Referência de API do Xanadu ft:clusterId : - crapiref bundleId : - crapiref workflow : - Creator --- # AccAgentsAPI - com escopo # AccAgentsAPI - com escopo {#ariaid-title1} * Versão de lançamento: Xanadu * * Atualizado 1 de ago. de 2024 * * ![](https://www.servicenow.com/docs/portal-asset/ico-clock) 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](https://www.servicenow.com/docs/access?context=acc-landing-page&version=xanadu&pubname=xanadu-it-operations-management&ft:locale=en-US). Para a solução REST API, consulte [Agent Client Collector API](https://servicenow-prod.fluidtopics.net/0hS64SPtXLuUBX2LjwGOfg#agnt_clnt_cll-api "A API Agent Client Collector fornece endpoints para gerenciar ações em agentes disponíveis e gerenciar políticas."). 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() {#ariaid-title2} Cria uma instância AccAgentsAPI. {#AccA-AccAgentsAPI__table_ohr_4qd_bpb__entry__3} | Nome | Tipo | Descrição | |-|-|-| | Nenhum(a) | | | [Tabela 1. Parâmetros] {#AccA-AccAgentsAPI__table_ohr_4qd_bpb} O exemplo a seguir mostra como inicializar AccAgentsAPI. var agentsApi = new sn_agent.AccAgentsAPI(); ## AccAgentsAPI -- checkGrabLogRequestProgress(cadeia de caracteres requestId) {#ariaid-title3} Verifica o status de uma solicitação de log de captura. Execute o método [submitGrabLogRequest()](https://servicenow-prod.fluidtopics.net/r5lIs5FfvACLpZ8xd8s5hg#AccA-submitGrabLogRequest_S "Solicita o log de um agente especificado com status ativo/ativo.") para obter um ID de solicitação. {#AccA-checkGrabLogRequestProgress_S__table_zk2_2g2_z4b__entry__3}{#AccA-checkGrabLogRequestProgress_S__accAgents-parm-desc-requestID} | 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 2. Parâmetros] {#AccA-checkGrabLogRequestProgress_S__table_zk2_2g2_z4b} {#AccA-checkGrabLogRequestProgress_S__table_al2_2g2_z4b__entry__2} | Propriedades | Descrição | |-|-| | \ | 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. {#AccA-checkGrabLogRequestProgress_S__ul_orq_4qr_bpb} | | saída | Informações que descrevem o status. | [Tabela 3. Retorna] {#AccA-checkGrabLogRequestProgress_S__table_al2_2g2_z4b} 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(""); gs.info(JSON.stringify(logRequestStatus, null, 2)); Saída: { "status": 2, "output": "Grab Log Request Timed Out" } ## AccAgentsAPI - getAgent(cadeia de caracteres agentID) {#ariaid-title4} 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](https://servicenow-prod.fluidtopics.net/0hS64SPtXLuUBX2LjwGOfg#agnt_clnt_cll-GET-list "Obtém uma lista de agentes com informações relacionadas."). {#AccA-getAgent_S__ul_yqc_3kj_z4b} {#AccA-getAgent_S__table_zk2_2g2_z4b__entry__3}{#AccA-getAgent_S__accAgents-parm-desc-agentID} | 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 4. Parâmetros] {#AccA-getAgent_S__table_zk2_2g2_z4b} {#AccA-getAgent_S__table_al2_2g2_z4b__entry__2}{#AccA-getAgent_S__accAgents-rtrns-error} | Propriedades | Descrição | |-|-| | \ | 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 {#AccA-getAgent_S__ul_w4n_53p_bpb} 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. {#AccA-getAgent_S__ul_b34_ffl_bpb} 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. {#AccA-getAgent_S__ul_bvp_dfl_bpb} 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. {#AccA-getAgent_S__ul_adg_ffp_bpb} 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](https://servicenow-prod.fluidtopics.net/rM63LHg6OGy~hBdWP_QdHA#c_GlideDateTimeScoped "A classe GlideDateTime com escopo fornece métodos para executar operações em objetos 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 | [Tabela 5. Retorna] {#AccA-getAgent_S__table_al2_2g2_z4b} O exemplo a seguir mostra como exibir o status de um agente. var agentsApi = new sn_agent.AccAgentsAPI(); var agentInfo = agentsAPI.getAgent(""); 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(""); gs.info(JSON.stringify(agentInfo, null, 2)); Saída: { "error": null, "agent": { "name": "win2016-dc-64bit", "status": 0, "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) {#ariaid-title5} Obtém uma lista de agentes com informações relacionadas. {#AccA-getAgentsList_S_N__table_zk2_2g2_z4b__entry__3} | 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](https://www.servicenow.com/docs/access?context=c_EncodedQueryStrings&version=xanadu&pubname=xanadu-platform-user-interface&ft:locale=en-US). | | 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 6. Parâmetros] {#AccA-getAgentsList_S_N__table_zk2_2g2_z4b} {#AccA-getAgentsList_S_N__table_al2_2g2_z4b__entry__2}{#AccA-getAgentsList_S_N__accAgents-parm-agent-obj-id-entry}{#AccA-getAgentsList_S_N__accAgents-parm-agent-obj-dataCollect-entry}{#AccA-getAgentsList_S_N__accAgents-parm-agent-obj-ip-entry}{#AccA-getAgentsList_S_N__accAgents-parm-agent-obj-dup-entry}{#AccA-getAgentsList_S_N__accAgents-parm-agent-obj-restart-entry}{#AccA-getAgentsList_S_N__accAgents-parm-agent-obj-name-entry}{#AccA-getAgentsList_S_N__accAgents-parm-agent-obj-numChecks-entry}{#AccA-getAgentsList_S_N__accAgents-parm-agent-obj-status-entry}{#AccA-getAgentsList_S_N__accAgents-parm-agent-obj-up-entry}{#AccA-getAgentsList_S_N__accAgents-parm-agent-obj-version-entry} | Propriedade | Descrição | |-|-| | \ | 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 {#AccA-getAgentsList_S_N__ul_w4n_53p_bpb} 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. {#AccA-getAgentsList_S_N__ul_b34_ffl_bpb} 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. {#AccA-getAgentsList_S_N__ul_bvp_dfl_bpb} 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. {#AccA-getAgentsList_S_N__ul_adg_ffp_bpb} 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](https://servicenow-prod.fluidtopics.net/rM63LHg6OGy~hBdWP_QdHA#c_GlideDateTimeScoped "A classe GlideDateTime com escopo fornece métodos para executar operações em objetos 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 | [Tabela 7. Retorna] {#AccA-getAgentsList_S_N__table_al2_2g2_z4b} 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) {#ariaid-title6} 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 {#AccA-restartAgent_S__ul_zzv_z4q_dpb} 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](https://servicenow-prod.fluidtopics.net/0hS64SPtXLuUBX2LjwGOfg#agnt_clnt_cll-GET-list "Obtém uma lista de agentes com informações relacionadas."). {#AccA-restartAgent_S__ul_yqc_3kj_z4b} {#AccA-restartAgent_S__table_zk2_2g2_z4b__entry__3}{#AccA-restartAgent_S__accAgents-parm-desc-agentID} | 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 8. Parâmetros] {#AccA-restartAgent_S__table_zk2_2g2_z4b} {#AccA-restartAgent_S__table_al2_2g2_z4b__entry__2} | Tipo | Descrição | |-|-| | Cadeia de caracteres | Mensagem de erro se aplicável, caso contrário, nula. | [Tabela 9. Retorna] {#AccA-restartAgent_S__table_al2_2g2_z4b} O exemplo a seguir mostra como reiniciar um agente. var agentsApi = new sn_agent.AccAgentsAPI(); var err = agentsApi.restartAgent(""); if (!gs.nil(err)) gs.error(err); ## AccAgentsAPI - runDiscovery(cadeia de caracteres agentID) {#ariaid-title7} 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](https://servicenow-prod.fluidtopics.net/0hS64SPtXLuUBX2LjwGOfg#agnt_clnt_cll-GET-list "Obtém uma lista de agentes com informações relacionadas."). {#AccA-runDiscovery_S__ul_yqc_3kj_z4b} {#AccA-runDiscovery_S__table_zk2_2g2_z4b__entry__3}{#AccA-runDiscovery_S__accAgents-parm-desc-agentID} | 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 10. Parâmetros] {#AccA-runDiscovery_S__table_zk2_2g2_z4b} {#AccA-runDiscovery_S__table_al2_2g2_z4b__entry__2} | Tipo | Descrição | |-|-| | Cadeia de caracteres | Mensagem de erro se aplicável, caso contrário, nula. Por exemplo, `Agente com ID:`\ Não está ativo: nenhum erro gerado . | [Tabela 11. Retorna] {#AccA-runDiscovery_S__table_al2_2g2_z4b} 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(""); if (!gs.nil(err)) gs.error(err); ## AccAgentsAPI - setDataCollectionStatus (cadeia de caracteres agentID, status booliano) {#ariaid-title8} 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](https://servicenow-prod.fluidtopics.net/0hS64SPtXLuUBX2LjwGOfg#agnt_clnt_cll-GET-list "Obtém uma lista de agentes com informações relacionadas."). {#AccA-setDataCollectionStatus_S_B__ul_yqc_3kj_z4b} {#AccA-setDataCollectionStatus_S_B__table_zk2_2g2_z4b__entry__3}{#AccA-setDataCollectionStatus_S_B__accAgents-parm-desc-agentID} | 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. {#AccA-setDataCollectionStatus_S_B__ul_iv2_jcz_bpb} Padrão: verdadeiro | [Tabela 12. Parâmetros] {#AccA-setDataCollectionStatus_S_B__table_zk2_2g2_z4b} {#AccA-setDataCollectionStatus_S_B__table_al2_2g2_z4b__entry__2} | Tipo | Descrição | |-|-| | Cadeia de caracteres | Mensagem de erro se aplicável, caso contrário, nula. Por exemplo, `Agente com ID:`\ Não está ativo: nenhum erro gerado . | [Tabela 13. Retorna] {#AccA-setDataCollectionStatus_S_B__table_al2_2g2_z4b} O exemplo a seguir mostra como ativar a coleta de dados do agente. var agentsApi = new sn_agent.AccAgentsAPI(); var err = agentsApi.setDataCollectionStatus("", 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("", false); if (!gs.nil(err)) gs.error(err); ## AccAgentsAPI - submitGrabLogRequest(cadeia de caracteres agentId) {#ariaid-title9} 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(). {#AccA-submitGrabLogRequest_S__table_zk2_2g2_z4b__entry__3}{#AccA-submitGrabLogRequest_S__accAgents-parm-desc-agentID} | 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 14. Parâmetros] {#AccA-submitGrabLogRequest_S__table_zk2_2g2_z4b} {#AccA-submitGrabLogRequest_S__table_al2_2g2_z4b__entry__2} | Propriedades | Descrição | |-|-| | \ | 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 | [Tabela 15. Retorna] {#AccA-submitGrabLogRequest_S__table_al2_2g2_z4b} O exemplo a seguir mostra como obter um ID de solicitação de log. var agentsApi = new sn_agent.AccAgentsAPI(); var submittedRequest = agentsApi.submitGrabLogRequest(""); if (!gs.nil(submittedRequest.error)) gs.error(submittedRequest.error); else gs.info("Request ID: " + submittedRequest.request_id); Saída: Request ID: