AccAgentsAPI : inclus dans le champ d’application

  • Rversion finale: Xanadu
  • Mis à jour 1 août 2024
  • 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, consultez Agent Client Collector.

    Pour la solution d’API REST, consultez l’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 d’obtention d’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 Discovery sur un agent.

    AccAgentsAPI : AccAgentsAPI()

    Crée une instance AccAgentsAPI.

    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 de capture.

    Exécuter 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 de saisie.
    {
  "status": Number,
  "output": "String"
}
    statut Numéro indiquant l’état de la demande de journal de capture.
    Valeurs possibles :
    • 0 : la demande de capture du journal est terminée.
    • 1 : demande de journal de saisie en cours.
    • 2 : la demande de journal de saisie a expiré.
    • 3 : la demande de capture du journal comporte une erreur.
    • 4 : la demande de journal de saisie 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 de capture.

    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 :
    Tableau 4. Paramètres
    Nom Type Description
    ID de l’agent Chaîne ID unique d’un agent répertorié dans la colonne ID d’agent de la table Agent Client Collectors [sn_agent_cmdb_ci_agent].
    Tableau 5. Renvoie
    Propriétés Description
    <Object> Objet contenant des 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 :
    • true : 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
    • false : cet agent n’a aucun doublon à 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 Nombre de vérifications que l’agent doit exécuter. 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 : En panne – L’agent n’a pas reçu de message de maintien depuis longtemps.
    • 3 : Redémarrage – L’agent est en cours de redémarrage.

    Type de données : nombre
    agent.up_since Temps UTC depuis que l’état de l’agent est activé/opérationnel. La valeur est au format GlideDateTime .

    Type de données : chaîne
    agent.version Version de l’agent 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(String encodedQuery, Number limit)

    Obtient une liste d’agents contenant des informations connexes.

    Tableau 6. Paramètres
    Nom Type Description
    encodedQuery Chaîne Chaîne de requête codée au format Glide standard. Reportez-vous à la section Chaînes de requêtes 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 obligatoires.

    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 :
    • true : 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
    • false : cet agent n’a aucun doublon à 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 Nombre de vérifications que l’agent doit exécuter. Ces vérifications font partie des politiques planifiées pour l’exécution de cet agent.

    Type de données : nombre
    statut É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 : En panne – L’agent n’a pas reçu de message de maintien depuis longtemps.
    • 3 : Redémarrage – L’agent est en cours de redémarrage.

    Type de données : nombre
    up_since Temps UTC depuis que l’état de l’agent est activé/opérationnel. La valeur est au format GlideDateTime .

    Type de données : chaîne
    version Version de l’agent 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 Indisponibilité 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 maximum 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 se produisent, 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 :
    Tableau 8. Paramètres
    Nom Type Description
    ID de l’agent Chaîne ID unique d’un agent répertorié dans la colonne ID d’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 les autres cas.

    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écouverte pour localiser les CI associés à un agent. L’agent spécifié doit être dans l’état actif/opérationnel.

    Pour obtenir une liste des ID d’agent :
    Tableau 10. Paramètres
    Nom Type Description
    ID de l’agent Chaîne ID unique d’un agent répertorié dans la colonne ID d’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 les autres cas. Par exemple, l’agent avec l’ID : <agentID > n’est pas en place : aucune erreur levée.

    L’exemple suivant montre comment exécuter Discovery sur un agent dont l’état est 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 :
    Tableau 12. Paramètres
    Nom Type Description
    ID de l’agent Chaîne ID unique d’un agent répertorié dans la colonne ID d’agent de la table Agent Client Collectors [sn_agent_cmdb_ci_agent].
    statut 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.

    Valeur par défaut : true
    Tableau 13. Renvoie
    Type Description
    Chaîne Message d’erreur le cas échéant, nul dans les autres cas. Par exemple, l’agent avec l’ID : <agentID > n’est pas en place : 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 de l’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
    ID de l’agent Chaîne ID unique d’un agent répertorié dans la colonne ID d’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 la demande et toute information sur 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>