AccAgentsAPI : dans le champ d’application

  • Rversion finale: Zurich
  • Mis à jour 31 juil. 2025
  • 10 minutes de lecture

    • L’include de script AccAgentsAPI vous permet d’effectuer des actions de gestion sur les agents disponibles.

    Cet include de script nécessite l’application Agent Client Collector de stockage Framework (sn_agent) et est fourni dans l’espace de noms sn_agent . Pour plus d’informations, reportez-vous à Agent Client Collector.

    Pour la solution REST API, consultez API Agent Client Collector.

    Cet include de script fournit des méthodes qui activent les éléments suivants :
    • Obtention d’informations détaillées sur un ou plusieurs agents.
    • Envoi d’une demande pour récupérer un journal d’agent et récupération d’informations sur la progression de la demande.
    • Démarrage ou arrêt de la collecte de données.
    • Redémarrage d’un agent.
    • Exécution de Découverte sur un agent.

    AccAgentsAPI : AccAgentsAPI()

    Crée une instance d’API AccAgents.

    Tableau 1. Paramètres
    Nom Type Description
    Aucun

    L’exemple suivant montre comment initialiser AccAgentsAPI.

    var agentsApi = new sn_agent.AccAgentsAPI();

    AccAgentsAPI : checkGrabLogRequestProgress(String requestId)

    Vérifie l’état d’une demande de journal d’empreinte.

    Exécutez la méthode submitGrabLogRequest() pour obtenir un ID de demande.

    Tableau 2. Paramètres
    Nom Type Description
    requestId Chaîne Sys_id d’une demande dans la table Demandes d’Agent Client Collector [sn_agent_request].
    Tableau 3. Renvoie
    Propriétés Description
    <Object> Objet JSON contenant l’état de la demande de journal d’importation.
    {
  "status": Number,
  "output": "String"
}
    état Numéro indiquant l’état de la demande de journal d’importation.
    Valeurs possibles :
    • 0 : la demande d’extraction du journal est terminée.
    • 1 : demande de saisie du journal en cours.
    • 2 : la demande de saisie du journal a expiré.
    • 3 : la demande de saisie du journal comporte une erreur.
    • 4 : la demande de capture du journal est introuvable.
    sortie Informations décrivant l’état.

    L’exemple suivant montre comment utiliser un ID de demande pour obtenir l’état d’une demande de journal d’extraction.

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

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

    Sortie :

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

    AccAgentsAPI : getAgent(String agentID)

    Obtient les informations d’un agent spécifié.

    Pour obtenir une liste des ID d’agent :
    • Exécutez la méthode getAgentsList( ).
    • Vérifiez la colonne ID de l’agent de la table Agent Client Collectors [sn_agent_cmdb_ci_agent].
    • Exécutez l’API REST GET list d’Agent Client Collector .
    Tableau 4. Paramètres
    Nom Type Description
    agentID Chaîne ID unique d’un agent répertorié dans la colonne ID de l’agent de la table Agent Client Collectors [sn_agent_cmdb_ci_agent].
    Tableau 5. Renvoie
    Propriétés Description
    <Object> Objet contenant les informations étendues sur l’agent.
    {
  "error": String,
  "agent": Object
}
    erreur Message d'erreur. Nul s’il n’y a pas d’erreur.

    Type de données : chaîne
    agent 
    "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 de l’agent tel que soumis.

    Type de données : chaîne
    agent.data_collection La collecte de données indique si des vérifications planifiées doivent être exécutées. Ces vérifications font partie des politiques planifiées pour l’exécution de cet agent.
    Valeurs possibles :
    • 0 : Activé : les vérifications s’exécutent comme prévu.
    • 1 : Désactivé (manuel) – Les vérifications ont été désactivées manuellement.
    • 2 : Désactivé (auto) – Les vérifications ont été désactivées automatiquement en raison de la consommation élevée du processeur par le

    Type de données : nombre
    agent.ip_address Adresse IP de l’agent.

    Type de données : chaîne
    agent.is_duplicate

    Marqueur indiquant si cet agent est un doublon d’un autre. Il ne doit y avoir qu’un seul agent sur un hôte donné.

    Valeurs possibles :
    • vrai : l’agent a le même hôte qu’un agent Alive/Up avec un ID d’agent différent. Désactiver ou désinstaller le doublon
    • faux : cet agent n’a pas de doublons à l’état Actif/En service.

    Type de données : booléennes
    agent.is_restart_enabled

    Marqueur indiquant si le redémarrage est activé. Le redémarrage de l’agent n’est pas configurable. Cela dépend du système d’exploitation et de la version du système d’exploitation sur lequel l’agent s’exécute.

    Valeurs possibles :
    • vrai : le redémarrage est activé pour cet agent.
    • faux : le redémarrage est désactivé pour cet agent.

    Type de données : booléennes
    agent.name Nom de l’agent.

    Type de données : chaîne
    agent.number_of_running_checks Le nombre de vérifications dont l’exécution est planifiée pour l’agent. Ces vérifications font partie des politiques planifiées pour l’exécution de cet agent.

    Type de données : nombre
    agent.status État de l’agent.
    Valeurs possibles :
    • 0 : actif/actif : l’agent est actif.
    • 1 : avertissement – L’agent n’a pas reçu de message de maintien de connexion au cours des dernières minutes.
    • 2 : Inactif : l’agent n’a pas reçu de message de maintien de connexion depuis longtemps.
    • 3 : Redémarrage – L’agent redémarre.

    Type de données : nombre
    agent.up_since Heure UTC depuis que le statut de l’agent est activé/augmenté. La valeur est au format GlideDateTime .

    Type de données : chaîne
    agent.version La version de l’agent est en cours d’exécution Agent Client Collector .

    Type de données : chaîne

    L’exemple suivant montre comment afficher l’état d’un agent.

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

    Sortie :

    agent status: 2

    L’exemple suivant montre comment obtenir tous les détails de l’agent.

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

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

    Sortie :

    {
  "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 (chaîne encodedQuery, limite de nombre)

    Obtient une liste d’agents avec des informations connexes.

    Tableau 6. Paramètres
    Nom Type Description
    encodedQuery Chaîne Chaîne de requête codée au format Glide standard. Voir Chaînes de requête codées.
    limite Numéro Facultatif. Limite les résultats à un nombre maximal d’agents. Utilisez null ou undefined pour les deux s’ils ne sont pas requis.

    Par défaut/max : 20 000
    Tableau 7. Renvoie
    Propriété Description
    <Tableau> Tableau d’objets JSON contenant des informations étendues sur l’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_id ID de l’agent tel que soumis.

    Type de données : chaîne
    data_collection La collecte de données indique si des vérifications planifiées doivent être exécutées. Ces vérifications font partie des politiques planifiées pour l’exécution de cet agent.
    Valeurs possibles :
    • 0 : Activé : les vérifications s’exécutent comme prévu.
    • 1 : Désactivé (manuel) – Les vérifications ont été désactivées manuellement.
    • 2 : Désactivé (auto) – Les vérifications ont été désactivées automatiquement en raison de la consommation élevée du processeur par le

    Type de données : nombre
    ip_address Adresse IP de l’agent.

    Type de données : chaîne
    is_duplicate

    Marqueur indiquant si cet agent est un doublon d’un autre. Il ne doit y avoir qu’un seul agent sur un hôte donné.

    Valeurs possibles :
    • vrai : l’agent a le même hôte qu’un agent Alive/Up avec un ID d’agent différent. Désactiver ou désinstaller le doublon
    • faux : cet agent n’a pas de doublons à l’état Actif/En service.

    Type de données : booléennes
    is_restart_enabled

    Marqueur indiquant si le redémarrage est activé. Le redémarrage de l’agent n’est pas configurable. Cela dépend du système d’exploitation et de la version du système d’exploitation sur lequel l’agent s’exécute.

    Valeurs possibles :
    • vrai : le redémarrage est activé pour cet agent.
    • faux : le redémarrage est désactivé pour cet agent.

    Type de données : booléennes
    nom Nom de l’agent.

    Type de données : chaîne
    number_of_running_checks Le nombre de vérifications dont l’exécution est planifiée pour l’agent. Ces vérifications font partie des politiques planifiées pour l’exécution de cet agent.

    Type de données : nombre
    état État de l’agent.
    Valeurs possibles :
    • 0 : actif/actif : l’agent est actif.
    • 1 : avertissement – L’agent n’a pas reçu de message de maintien de connexion au cours des dernières minutes.
    • 2 : Inactif : l’agent n’a pas reçu de message de maintien de connexion depuis longtemps.
    • 3 : Redémarrage – L’agent redémarre.

    Type de données : nombre
    up_since Heure UTC depuis que le statut de l’agent est activé/augmenté. La valeur est au format GlideDateTime .

    Type de données : chaîne
    version La version de l’agent est en cours d’exécution Agent Client Collector .

    Type de données : chaîne

    L’exemple suivant montre comment restreindre les résultats par requête et par numéro. La requête renvoie tous les agents qui ne sont pas dans l’état arrêté avec un maximum de deux résultats.

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

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

    Sortie :

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

    L’exemple suivant montre comment répertorier tous les agents du système. Cet exemple n’utilise aucune requête et aucun nombre maximal de résultats.

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

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

    L’exemple suivant montre comment itérer sur les résultats fournis et affiche chaque ID d’agent.

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

    Sortie :

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

    AccAgentsAPI : restartAgent(String agentID)

    Redémarre un agent spécifié avec l’état actif/actif.

    Si Agent Client Collector des problèmes de performances surviennent, vous pouvez redémarrer l’agent. Le redémarrage manuel est pris en charge dans les environnements suivants :
    • Agents basés sur Linux utilisant systemd
    • Agents Windows
    Pour obtenir une liste des ID d’agent :
    • Exécutez la méthode getAgentsList( ).
    • Vérifiez la colonne ID de l’agent de la table Agent Client Collectors [sn_agent_cmdb_ci_agent].
    • Exécutez l’API REST GET list d’Agent Client Collector .
    Tableau 8. Paramètres
    Nom Type Description
    agentID Chaîne ID unique d’un agent répertorié dans la colonne ID de l’agent de la table Agent Client Collectors [sn_agent_cmdb_ci_agent].
    Tableau 9. Renvoie
    Type Description
    Chaîne Message d’erreur le cas échéant, nul dans le cas contraire.

    L’exemple suivant montre comment redémarrer un agent.

    var agentsApi = new sn_agent.AccAgentsAPI();

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

    AccAgentsAPI : runDiscovery(String agentID)

    Exécute une vérification de détection pour localiser les CI liés à un agent. L’agent spécifié doit être à l’état actif/actif.

    Pour obtenir une liste des ID d’agent :
    • Exécutez la méthode getAgentsList( ).
    • Vérifiez la colonne ID de l’agent de la table Agent Client Collectors [sn_agent_cmdb_ci_agent].
    • Exécutez l’API REST GET list d’Agent Client Collector .
    Tableau 10. Paramètres
    Nom Type Description
    agentID Chaîne ID unique d’un agent répertorié dans la colonne ID de l’agent de la table Agent Client Collectors [sn_agent_cmdb_ci_agent].
    Tableau 11. Renvoie
    Type Description
    Chaîne Message d’erreur le cas échéant, nul dans le cas contraire. Par exemple, l’agent avec l’ID : <agentID> n’est pas opérationnel : aucune erreur levée.

    L’exemple suivant montre comment exécuter la détection sur un agent avec l’état actif/actif.

    var agentsApi = new sn_agent.AccAgentsAPI();

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

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

    AccAgentsAPI : setDataCollectionStatus(String agentID, état booléen)

    Définissez l’état de la collecte de données donné (vrai/faux si activé ou non) pour un agent spécifié.

    Pour obtenir une liste des ID d’agent :
    • Exécutez la méthode getAgentsList( ).
    • Vérifiez la colonne ID de l’agent de la table Agent Client Collectors [sn_agent_cmdb_ci_agent].
    • Exécutez l’API REST GET list d’Agent Client Collector .
    Tableau 12. Paramètres
    Nom Type Description
    agentID Chaîne ID unique d’un agent répertorié dans la colonne ID de l’agent de la table Agent Client Collectors [sn_agent_cmdb_ci_agent].
    état Booléen

    Marqueur indiquant si la collecte de données est activée pour l’agent.

    Valeurs valides :
    • vrai : active la collecte de données pour cet agent.
    • faux : désactive la collecte de données pour cet agent.

    Par défaut : true
    Tableau 13. Renvoie
    Type Description
    Chaîne Message d’erreur le cas échéant, nul dans le cas contraire. Par exemple, l’agent avec l’ID : <agentID> n’est pas opérationnel : aucune erreur levée.

    L’exemple suivant montre comment activer la collecte de données d’agent.

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

    L’exemple suivant montre comment désactiver la collecte de données d’agent.

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

    AccAgentsAPI : submitGrabLogRequest(String agentId)

    Demande le journal d’un agent spécifié avec l’état actif/actif.

    Remarque :
    Pour récupérer le journal et vérifier sa progression, transmettez l’ID de demande renvoyé à la méthode checkGrabLogRequestProgress( ).
    Tableau 14. Paramètres
    Nom Type Description
    agentID Chaîne ID unique d’un agent répertorié dans la colonne ID de l’agent de la table Agent Client Collectors [sn_agent_cmdb_ci_agent].
    Tableau 15. Renvoie
    Propriétés Description
    <Object> Objet JSON contenant l’ID de demande et toute information relative à l’erreur.
    {
  "error": "String",
  "request_id": "String"
}
    erreur Message d'erreur. Nul s’il n’y a pas d’erreur.

    Type de données : chaîne
    request_id Sys_id d’une demande dans la table Demandes d’Agent Client Collector [sn_agent_request].

    Vous pouvez utiliser cet ID pour obtenir l’état de la demande à l’aide de GET /agents/{request_id}/.

    Type de données : chaîne

    L’exemple suivant montre comment obtenir un ID de demande de journal.

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

    Sortie :

    Request ID: <sys_id>