AccAgentsAPI : Bereichsbezogen

  • Freigeben Version: Yokohama
  • Aktualisiert 30. Januar 2025
  • 9 Minuten Lesedauer

    • Mit der Skripteinbindung AccAgentsAPI können Sie Verwaltungsaktionen für verfügbare Service Desk-Mitarbeiter ausführen.

    Diese Skripteinbindung erfordert die Store-Anwendung Framework Agent Client Collector (sn_agent) und wird im Namespace sn_agent bereitgestellt. Weitere Informationen finden Sie unter Agent Client Collector.

    Informationen zur REST-API-Lösung finden Sie unter Agent Client Collector API.

    Diese Skripteinbindung stellt Methoden bereit, die Folgendes ermöglichen:
    • Umfangreiche Informationen von einem oder mehreren Service Desk-Mitarbeitern abrufen.
    • Senden einer Anforderung, um ein Agent-Protokoll abzurufen und Informationen über den Fortschritt der Anforderung abzurufen.
    • Datenerfassung wird gestartet oder gestoppt.
    • Ein Agent wird neu gestartet.
    • Discovery wird auf einem Agent ausgeführt.

    AccAgentsAPI: AccAgentsAPI()

    Erstellt eine AccAgentsAPI-Instanz.

    Tabelle : 1. Parameter
    Name Typ Beschreibung
    Keine

    Das folgende Beispiel zeigt, wie AccAgentsAPIinitialisiert wird.

    var agentsApi = new sn_agent.AccAgentsAPI();

    AccAgentsAPI – checkGrabLogRequestProgress(String requestId)

    Überprüft den Status einer Erfassungsprotokollanforderung.

    Führen Sie die Methode „submitGrabLogRequest()“ aus, um eine Anforderungs-ID zu erhalten.

    Tabelle : 2. Parameter
    Name Typ Beschreibung
    requestId Zeichenfolge Sys_id einer Anforderung in der Tabelle „Agent Client Collector-Anforderungen“ [sn_agent_request].
    Tabelle : 3. Rückgaben
    Eigenschaften Beschreibung
    <Object> JSON-Objekt, das den Status der Erfassungsprotokollanforderung enthält.
    {
  "status": Number,
  "output": "String"
}
    status Zahl, die den Status der Anforderung zum Abrufen des Protokolls angibt.
    Mögliche Werte:
    • 0: Anforderung zum Abrufen des Protokolls ist abgeschlossen.
    • 1: Protokollanforderung in Bearbeitung.
    • 2: Zeitüberschreitung bei der Anforderung zum Abrufen des Protokolls.
    • 3: Die Anforderung zum Abrufen des Protokolls weist einen Fehler auf.
    • 4: Die Anforderung für das Abrufprotokoll wurde nicht gefunden.
    Ausgabe Informationen, die den Status beschreiben.

    Das folgende Beispiel zeigt, wie eine Anforderungs-ID verwendet wird, um den Status einer Erfassungsprotokollanforderung abzurufen.

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

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

    Ausgabe:

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

    AccAgentsAPI – getAgent(String agentID)

    Ruft die Informationen eines angegebenen Agent ab.

    So rufen Sie eine Liste der Agent-IDs ab:
    • Führen Sie die Methode getAgentsList() aus.
    • Überprüfen Sie die Spalte „Agent ID“ in der Tabelle „Agent Client Collectors“ [sn_agent_cmdb_ci_agent].
    • Führen Sie die Agent Client Collector GET list REST API aus.
    Tabelle : 4. Parameter
    Name Typ Beschreibung
    agentID Zeichenfolge Eindeutige ID eines Agents, der in der Spalte „Agent ID“ der Tabelle „Agent Client Collectors“ [sn_agent_cmdb_ci_agent] aufgeführt ist.
    Tabelle : 5. Rückgaben
    Eigenschaften Beschreibung
    <Object> Objekt mit erweiterten Informationen zum Service Desk-Mitarbeiter.
    {
  "error": String,
  "agent": Object
}
    Fehler Fehlermeldung. NULL, wenn kein Fehler vorliegt.

    Datentyp: Zeichenfolge
    Service Desk-Mitarbeiter 
    "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 des Agent wie übermittelt.

    Datentyp: Zeichenfolge
    agent.data_collection Die Datenerfassung gibt an, ob geplante Prüfungen ausgeführt werden sollen. Diese Prüfungen sind Teil der Richtlinien, die für diesen Agent geplant sind.
    Mögliche Werte:
    • 0: Ein – Prüfungen werden wie geplant ausgeführt.
    • 1: Aus (manuell) – Prüfungen wurden manuell deaktiviert.
    • 2: Aus (auto) – Prüfungen wurden aufgrund der hohen CPU-Auslastung durch automatisch deaktiviert

    Datentyp: Zahl
    agent.ip_address IP-Adresse des Agents.

    Datentyp: Zeichenfolge
    agent.is_duplicate

    Kennzeichnung, die angibt, ob dieser Agent ein Duplikat eines anderen ist. Auf einem bestimmten Host darf nur ein einzelner Agent vorhanden sein.

    Mögliche Werte:
    • „wahr“: Der Agent hat denselben Host wie ein aktiver Agent mit einer anderen Agent-ID. Deaktivieren oder deinstallieren Sie das Duplikat
    • „false“: Dieser Service Desk-Mitarbeiter weist keine Duplikate im Status „Aktiv“/„Aktiv“ auf.

    Datentyp: Boolesch
    agent.is_restart_enabled

    Kennzeichnung, die angibt, ob der Neustart aktiviert ist. Agent-Neustart ist nicht konfigurierbar. Sie hängt vom Betriebssystem und von der Version des Betriebssystems ab, auf dem der Agent ausgeführt wird.

    Mögliche Werte:
    • true: Neustart ist für diesen Agent aktiviert.
    • „falsch“: Neustart ist für diesen Agent deaktiviert.

    Datentyp: Boolesch
    agent.name Der Name des Außendienstmitarbeiters.

    Datentyp: Zeichenfolge
    agent.number_of_running_checks Die Anzahl der vom Agent geplanten Prüfungen. Diese Prüfungen sind Teil der Richtlinien, die für diesen Agent geplant sind.

    Datentyp: Zahl
    agent.status Status des Service Desk-Mitarbeiters.
    Mögliche Werte:
    • 0: Aktiv/Aktiv: Der Agent ist aktiv.
    • 1: Warnung – Der Service Desk-Mitarbeiter hat in den letzten Minuten keine Keepalive-Nachricht erhalten.
    • 2: Ausgefallen – Der Service Desk-Mitarbeiter hat seit langer Zeit keine Keepalive-Nachricht erhalten.
    • 3: Wird neu gestartet – Der Agent wird neu gestartet.

    Datentyp: Zahl
    agent.up_since UTC-Zeit seit Änderung des Status des Service Desk-Mitarbeiters. Der Wert wird im GlideDateTime -Format angegeben.

    Datentyp: Zeichenfolge
    agent.version Version von Agent Client Collector, die der Agent ausführt.

    Datentyp: Zeichenfolge

    Das folgende Beispiel zeigt, wie der Status eines Service Desk-Mitarbeiters angezeigt wird.

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

    Ausgabe:

    agent status: 2

    Das folgende Beispiel zeigt, wie Sie alle Agent-Details abrufen.

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

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

    Ausgabe:

    {
  "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, Anzahlbegrenzung)

    Ruft eine Liste von Service Desk-Mitarbeitern mit zugehörigen Informationen ab.

    Tabelle : 6. Parameter
    Name Typ Beschreibung
    encodedQuery Zeichenfolge Codierte Abfragezeichenfolge im Standard-Glide-Format. Siehe Codierte Abfragezeichenfolgen.
    limit Nummer Optional. Beschränkt die Ergebnisse auf eine maximale Anzahl von Service Desk-Mitarbeitern. Verwenden Sie null oder undefiniert für beide, wenn sie nicht erforderlich sind.

    Standard/Max.: 20.000
    Tabelle : 7. Rückgaben
    Eigenschaft Beschreibung
    <Array> Array von JSON-Objekten mit erweiterten Agent-Informationen.
    [
 {
   "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 des Agent wie übermittelt.

    Datentyp: Zeichenfolge
    data_collection Die Datenerfassung gibt an, ob geplante Prüfungen ausgeführt werden sollen. Diese Prüfungen sind Teil der Richtlinien, die für diesen Agent geplant sind.
    Mögliche Werte:
    • 0: Ein – Prüfungen werden wie geplant ausgeführt.
    • 1: Aus (manuell) – Prüfungen wurden manuell deaktiviert.
    • 2: Aus (auto) – Prüfungen wurden aufgrund der hohen CPU-Auslastung durch automatisch deaktiviert

    Datentyp: Zahl
    ip_address IP-Adresse des Agents.

    Datentyp: Zeichenfolge
    is_duplicate

    Kennzeichnung, die angibt, ob dieser Agent ein Duplikat eines anderen ist. Auf einem bestimmten Host darf nur ein einzelner Agent vorhanden sein.

    Mögliche Werte:
    • „wahr“: Der Agent hat denselben Host wie ein aktiver Agent mit einer anderen Agent-ID. Deaktivieren oder deinstallieren Sie das Duplikat
    • „false“: Dieser Service Desk-Mitarbeiter weist keine Duplikate im Status „Aktiv“/„Aktiv“ auf.

    Datentyp: Boolesch
    is_restart_enabled

    Kennzeichnung, die angibt, ob der Neustart aktiviert ist. Agent-Neustart ist nicht konfigurierbar. Sie hängt vom Betriebssystem und von der Version des Betriebssystems ab, auf dem der Agent ausgeführt wird.

    Mögliche Werte:
    • true: Neustart ist für diesen Agent aktiviert.
    • „falsch“: Neustart ist für diesen Agent deaktiviert.

    Datentyp: Boolesch
    name Der Name des Außendienstmitarbeiters.

    Datentyp: Zeichenfolge
    number_of_running_checks Die Anzahl der vom Agent geplanten Prüfungen. Diese Prüfungen sind Teil der Richtlinien, die für diesen Agent geplant sind.

    Datentyp: Zahl
    status Status des Service Desk-Mitarbeiters.
    Mögliche Werte:
    • 0: Aktiv/Aktiv: Der Agent ist aktiv.
    • 1: Warnung – Der Service Desk-Mitarbeiter hat in den letzten Minuten keine Keepalive-Nachricht erhalten.
    • 2: Ausgefallen – Der Service Desk-Mitarbeiter hat seit langer Zeit keine Keepalive-Nachricht erhalten.
    • 3: Wird neu gestartet – Der Agent wird neu gestartet.

    Datentyp: Zahl
    up_since UTC-Zeit seit Änderung des Status des Service Desk-Mitarbeiters. Der Wert wird im GlideDateTime -Format angegeben.

    Datentyp: Zeichenfolge
    version Version von Agent Client Collector, die der Agent ausführt.

    Datentyp: Zeichenfolge

    Das folgende Beispiel zeigt, wie Ergebnisse nach Abfrage und Nummer eingeschränkt werden. Die Abfrage gibt alle Service Desk-Mitarbeiter zurück, die sich nicht im Status „Ausgefallen“ befinden, mit maximal zwei Ergebnissen.

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

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

    Ausgabe:

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

    Das folgende Beispiel zeigt, wie alle Mitarbeiter im System aufgelistet werden. In diesem Beispiel wird keine Abfrage und keine maximale Anzahl von Ergebnissen verwendet.

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

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

    Das folgende Beispiel zeigt, wie die bereitgestellten Ergebnisse iteriert werden, und zeigt jede Agent-ID an.

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

    Ausgabe:

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

    AccAgentsAPI – neustartAgent(Zeichenfolge agentID)

    Startet einen angegebenen Agent mit dem Status „Aktiv“/„Aktiv“ neu.

    Wenn Agent Client Collector Leistungsprobleme auftreten, können Sie den Agent neu starten. Der manuelle Neustart wird in den folgenden Umgebungen unterstützt:
    • Linux-basierte Agents mit systemd
    • Windows-Agents
    So rufen Sie eine Liste der Agent-IDs ab:
    • Führen Sie die Methode getAgentsList() aus.
    • Überprüfen Sie die Spalte „Agent ID“ in der Tabelle „Agent Client Collectors“ [sn_agent_cmdb_ci_agent].
    • Führen Sie die Agent Client Collector GET list REST API aus.
    Tabelle : 8. Parameter
    Name Typ Beschreibung
    agentID Zeichenfolge Eindeutige ID eines Agents, der in der Spalte „Agent ID“ der Tabelle „Agent Client Collectors“ [sn_agent_cmdb_ci_agent] aufgeführt ist.
    Tabelle : 9. Ausgabe
    Typ Beschreibung
    Zeichenfolge Fehlermeldung, falls zutreffend, andernfalls NULL.

    Das folgende Beispiel zeigt, wie Sie einen Agent neu starten.

    var agentsApi = new sn_agent.AccAgentsAPI();

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

    AccAgentsAPI – runDiscovery(Zeichenfolge – agentID)

    Führt eine Discovery-Prüfung durch, um CIs zu finden, die sich auf einen Agent beziehen. Der angegebene Agent muss sich im Status „Aktiv“/„Aktiv“ befinden.

    So rufen Sie eine Liste der Agent-IDs ab:
    • Führen Sie die Methode getAgentsList() aus.
    • Überprüfen Sie die Spalte „Agent ID“ in der Tabelle „Agent Client Collectors“ [sn_agent_cmdb_ci_agent].
    • Führen Sie die Agent Client Collector GET list REST API aus.
    Tabelle : 10. Parameter
    Name Typ Beschreibung
    agentID Zeichenfolge Eindeutige ID eines Agents, der in der Spalte „Agent ID“ der Tabelle „Agent Client Collectors“ [sn_agent_cmdb_ci_agent] aufgeführt ist.
    Tabelle : 11. Ausgabe
    Typ Beschreibung
    Zeichenfolge Fehlermeldung, falls zutreffend, andernfalls NULL. Beispiel: Service Desk-Mitarbeiter mit ID:<agentID> Ist nicht in Betrieb: kein ausgelöster Fehler .

    Das folgende Beispiel zeigt, wie Discovery für einen Agent mit dem Status „Aktiv“/„Aktiv“ ausgeführt wird.

    var agentsApi = new sn_agent.AccAgentsAPI();

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

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

    AccAgentsAPI – setDataCollectionStatus(String agentID, boolescher Status)

    Legen Sie den angegebenen Datensammlungsstatus (wahr/falsch, falls aktiviert oder nicht) für einen bestimmten Agent fest.

    So rufen Sie eine Liste der Agent-IDs ab:
    • Führen Sie die Methode getAgentsList() aus.
    • Überprüfen Sie die Spalte „Agent ID“ in der Tabelle „Agent Client Collectors“ [sn_agent_cmdb_ci_agent].
    • Führen Sie die Agent Client Collector GET list REST API aus.
    Tabelle : 12. Parameter
    Name Typ Beschreibung
    agentID Zeichenfolge Eindeutige ID eines Agents, der in der Spalte „Agent ID“ der Tabelle „Agent Client Collectors“ [sn_agent_cmdb_ci_agent] aufgeführt ist.
    status Boolean

    Kennzeichnung, die angibt, ob die Datenerfassung für den Agent aktiviert ist.

    Gültige Werte:
    • true: Aktiviert die Datenerfassung für diesen Agent.
    • „falsch“: Deaktiviert die Datenerfassung für diesen Agent.

    Standardwert: wahr
    Tabelle : 13. Rückgaben
    Typ Beschreibung
    Zeichenfolge Fehlermeldung, falls zutreffend, andernfalls NULL. Beispiel: Service Desk-Mitarbeiter mit ID:<agentID> Ist nicht in Betrieb: kein ausgelöster Fehler .

    Das folgende Beispiel zeigt, wie die Agent-Datenerfassung aktiviert wird.

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

    Das folgende Beispiel zeigt, wie die Agent-Datenerfassung deaktiviert wird.

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

    AccAgentsAPI –submitGrabLogRequest(String agentId)

    Fordert das Protokoll eines angegebenen Agent mit dem Status „Aktiv“/„Aktiv“ an.

    Hinweis:
    Um das Protokoll abzurufen und seinen Fortschritt zu überprüfen, übergeben Sie die zurückgegebene Anforderungs-ID an die Methode checkGrabLogRequestProgress().
    Tabelle : 14. Parameter
    Name Typ Beschreibung
    agentID Zeichenfolge Eindeutige ID eines Agents, der in der Spalte „Agent ID“ der Tabelle „Agent Client Collectors“ [sn_agent_cmdb_ci_agent] aufgeführt ist.
    Tabelle : 15. Rückgaben
    Eigenschaften Beschreibung
    <Object> JSON-Objekt, das die Anforderungs-ID und etwaige Fehlerinformationen enthält.
    {
  "error": "String",
  "request_id": "String"
}
    Fehler Fehlermeldung. NULL, wenn kein Fehler vorliegt.

    Datentyp: Zeichenfolge
    request_id Sys_id einer Anforderung in der Tabelle „Agent Client Collector-Anforderungen“ [sn_agent_request].

    Sie können diese ID verwenden, um den Status der Anforderung mit GET /agents/{request_id}/abzurufen.

    Datentyp: Zeichenfolge

    Das folgende Beispiel zeigt, wie Sie eine Protokollanforderungs-ID abrufen.

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

    Ausgabe:

    Request ID: <sys_id>