AccAgentsAPI – Umfang

  • Freigeben Version: Zurich
  • Aktualisiert 31. Juli 2025
  • 9 Minuten Lesedauer

    • Die AccAgentsAPI Mit der Skripteinbindung können Sie Verwaltungsaktionen für verfügbare Agents ausführen.

    Diese Skripteinbindung erfordert Agent Client Collector Framework (sn_Agent) speichert die Anwendung und wird in bereitgestellt sn_Agent Namespace. 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:
    • Umfassende Informationen zu einem oder mehreren Service Desk-Mitarbeitern werden abgerufen.
    • Senden einer Anforderung zum Abrufen eines Agent-Protokolls und Abrufen von Informationen zum Anforderungsfortschritt.
    • Datenerfassung wird gestartet oder gestoppt.
    • Agent wird neu gestartet.
    • Discovery für einen Agent wird ausgeführt.

    AccAgentsAPI: AccAgentsAPI()

    Erstellt eine AccAgentsAPI-Instanz.

    Tabelle : 1. Parameter
    Name Typ Beschreibung
    Keine

    Das folgende Beispiel zeigt, wie Sie initialisieren AccAgentsAPI .

    var agentsApi = new sn_agent.AccAgentsAPI();

    AccAgentsAPI – checkGrabLogRequestProgress(Zeichenfolge requestId)

    Überprüft den Status einer Anforderung zum Abrufen eines Protokolls.

    Führen Sie aus SubmitGrabLogRequest() Methode zum Abrufen einer Anforderungs-ID.

    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 Anforderung zum Abrufen des Protokolls enthält.
    {
  "status": Number,
  "output": "String"
}
    status Nummer, die den Status der Anforderung zum Abrufen des Protokolls angibt.
    Mögliche Werte:
    • 0: Anforderung zum Abrufen des Protokolls ist abgeschlossen.
    • 1: Anforderung zum Abrufen des Protokolls wird ausgeführt.
    • 2: Zeitüberschreitung bei Anforderung zum Abrufen des Protokolls.
    • 3: Die Anforderung zum Abrufen des Protokolls weist einen Fehler auf.
    • 4: Anforderung zum Abrufen des Protokolls wurde nicht gefunden.
    Ausgabe Informationen, die den Status beschreiben.

    Das folgende Beispiel zeigt, wie Sie eine Anforderungs-ID verwenden, um den Status einer Anforderung zum Abrufen eines Abrufprotokolls 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 Service Desk-Mitarbeiters ab.

    So rufen Sie eine Liste der Service Desk-Mitarbeiter-IDs ab:
    • Führen Sie aus GetAgentsList() Methode.
    • Überprüfen Sie die Spalte „Agent-ID“ der Tabelle „Agent Client Collectors“ [sn_Agent_cmdb_ci_Agent].
    • Führen Sie aus Agent Client Collector – Liste ABRUFEN REST-API.
    Tabelle : 4. Parameter
    Name Typ Beschreibung
    AGENTID Zeichenfolge Eindeutige ID eines Service Desk-Mitarbeiters, 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 Service Desk-Mitarbeiter-Informationen.
    {
  "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 Service Desk-Mitarbeiters wie übermittelt.

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

    Datentyp: Zahl
    Agent.ip_address Service Desk-Mitarbeiter-IP-Adresse.

    Datentyp: Zeichenfolge
    Agent.is_Duplikat

    Kennzeichnung, die angibt, ob dieser Service Desk-Mitarbeiter 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/aktiver Agent mit einer anderen Agent-ID. Deaktivieren oder deinstallieren Sie das Duplikat
    • Falsch: Dieser Agent hat keine Duplikate im Status „aktiv“/„aktiv“.

    Datentyp: Boolesch
    Agent.is_restart_enabled

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

    Mögliche Werte:
    • Wahr: 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 Prüfungen, die der Service Desk-Mitarbeiter ausführen soll. Diese Prüfungen sind Teil der Richtlinien, die für diesen Service Desk-Mitarbeiter ausgeführt werden sollen.

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

    Datentyp: Zahl
    Agent.up_seit UTC-Zeit, seit der Status des Service Desk-Mitarbeiters „aktiv“/„aktiv“ wurde. Der Wert ist in GlideDateTime Format.

    Datentyp: Zeichenfolge
    Agent.Version Version von Agent Client Collector Der Service Desk-Mitarbeiter wird ausgefü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 alle Agent-Details abgerufen werden.

    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, Nummernlimit)

    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 Anzahl Optional. Beschränkt die Ergebnisse auf eine maximale Anzahl von Service Desk-Mitarbeitern. Verwenden Sie null oder nicht definiert 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 Service Desk-Mitarbeiters wie übermittelt.

    Datentyp: Zeichenfolge
    Data_Collection Die Datensammlung gibt an, ob geplante Prüfungen ausgeführt werden sollen. Diese Prüfungen sind Teil der Richtlinien, die für diesen Service Desk-Mitarbeiter ausgeführt werden sollen.
    Mögliche Werte:
    • 0: Ein: Prüfungen werden wie geplant ausgeführt.
    • 1: Aus (manuell): Prüfungen wurden manuell deaktiviert.
    • 2: Aus (automatisch): Prüfungen wurden aufgrund eines hohen CPU-Verbrauchs durch automatisch deaktiviert

    Datentyp: Zahl
    ip_address Service Desk-Mitarbeiter-IP-Adresse.

    Datentyp: Zeichenfolge
    Ist_Duplikat

    Kennzeichnung, die angibt, ob dieser Service Desk-Mitarbeiter 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/aktiver Agent mit einer anderen Agent-ID. Deaktivieren oder deinstallieren Sie das Duplikat
    • Falsch: Dieser Agent hat keine Duplikate im Status „aktiv“/„aktiv“.

    Datentyp: Boolesch
    Ist_restart_enabled

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

    Mögliche Werte:
    • Wahr: 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 Prüfungen, die der Service Desk-Mitarbeiter ausführen soll. Diese Prüfungen sind Teil der Richtlinien, die für diesen Service Desk-Mitarbeiter ausgeführt werden sollen.

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

    Datentyp: Zahl
    Up_since UTC-Zeit, seit der Status des Service Desk-Mitarbeiters „aktiv“/„aktiv“ wurde. Der Wert ist in GlideDateTime Format.

    Datentyp: Zeichenfolge
    Version Version von Agent Client Collector Der Service Desk-Mitarbeiter wird ausgeführt.

    Datentyp: Zeichenfolge

    Das folgende Beispiel zeigt, wie Ergebnisse nach Abfrage und Nummer eingeschränkt werden. Die Abfrage gibt alle Agents 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 Sie jeden Service Desk-Mitarbeiter im System auflisten. In diesem Beispiel werden 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 über die bereitgestellten Ergebnisse iteriert wird, und zeigt die einzelnen Service Desk-Mitarbeiter-IDs 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 – restartAgent(String AGENTID)

    Startet einen angegebenen Agent mit Status „aktiv“/„aktiv“ neu.

    Wenn Agent Client Collector Leistungsprobleme treten auf. Sie können den Service Desk-Mitarbeiter neu starten. Manueller Neustart wird in den folgenden Umgebungen unterstützt:
    • Linux-basierte Agents mit System-ID
    • Windows-Agents
    So rufen Sie eine Liste der Service Desk-Mitarbeiter-IDs ab:
    • Führen Sie aus GetAgentsList() Methode.
    • Überprüfen Sie die Spalte „Agent-ID“ der Tabelle „Agent Client Collectors“ [sn_Agent_cmdb_ci_Agent].
    • Führen Sie aus Agent Client Collector – Liste ABRUFEN REST-API.
    Tabelle : 8. Parameter
    Name Typ Beschreibung
    AGENTID Zeichenfolge Eindeutige ID eines Service Desk-Mitarbeiters, 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 ein Service Desk-Mitarbeiter neu gestartet wird.

    var agentsApi = new sn_agent.AccAgentsAPI();

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

    AccAgentsAPI – runDiscovery(String AGENTID)

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

    So rufen Sie eine Liste der Service Desk-Mitarbeiter-IDs ab:
    • Führen Sie aus GetAgentsList() Methode.
    • Überprüfen Sie die Spalte „Agent-ID“ der Tabelle „Agent Client Collectors“ [sn_Agent_cmdb_ci_Agent].
    • Führen Sie aus Agent Client Collector – Liste ABRUFEN REST-API.
    Tabelle : 10. Parameter
    Name Typ Beschreibung
    AGENTID Zeichenfolge Eindeutige ID eines Service Desk-Mitarbeiters, 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: Agent mit ID: <agentID> ist nicht aktiv: Kein Fehler ausgelöst .

    Das folgende Beispiel zeigt, wie die 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(Zeichenfolge AGENTID, boolescher Status)

    Legen Sie den angegebenen Datensammlungsstatus (wahr/falsch, wenn aktiviert oder nicht) für einen angegebenen Service Desk-Mitarbeiter fest.

    So rufen Sie eine Liste der Service Desk-Mitarbeiter-IDs ab:
    • Führen Sie aus GetAgentsList() Methode.
    • Überprüfen Sie die Spalte „Agent-ID“ der Tabelle „Agent Client Collectors“ [sn_Agent_cmdb_ci_Agent].
    • Führen Sie aus Agent Client Collector – Liste ABRUFEN REST-API.
    Tabelle : 12. Parameter
    Name Typ Beschreibung
    AGENTID Zeichenfolge Eindeutige ID eines Service Desk-Mitarbeiters, 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 Datensammlung für den Service Desk-Mitarbeiter aktiviert ist.

    Gültige Werte:
    • Wahr: Aktiviert die Datensammlung für diesen Service Desk-Mitarbeiter.
    • Falsch: Deaktiviert die Datensammlung für diesen Agent.

    Standardwert: wahr
    Tabelle : 13. Rückgaben
    Typ Beschreibung
    Zeichenfolge Fehlermeldung, falls zutreffend, andernfalls Null. Beispiel: Agent mit ID: <agentID> ist nicht aktiv: Kein Fehler ausgelöst .

    Das folgende Beispiel zeigt, wie die Datensammlung für Service Desk-Mitarbeiter 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 Datensammlung für Service Desk-Mitarbeiter 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 Service Desk-Mitarbeiters mit Status „aktiv“/„aktiv“ an.

    Hinweis:
    Um das Protokoll abzurufen und seinen Fortschritt zu überprüfen, übergeben Sie die an zurückgegebene Anforderungs-ID CheckGrabLogRequestProgress() Methode.
    Tabelle : 14. Parameter
    Name Typ Beschreibung
    AGENTID Zeichenfolge Eindeutige ID eines Service Desk-Mitarbeiters, 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 mit der Anforderungs-ID und Fehlerinformationen.
    {
  "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 abzurufen /Agents/{Request_ID}/ ABRUFEN .

    Datentyp: Zeichenfolge

    Das folgende Beispiel zeigt, wie eine Protokollanforderungs-ID abgerufen wird.

    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>