AccAgentsAPI – Scoped

  • Freigeben Version: Washingtondc
  • Aktualisiert 1. Februar 2024
  • 9 Minuten Lesedauer

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

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

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

    Diese API enthält Methoden, die Folgendes ermöglichen:
    • Umfangreiche Informationen zu einem oder mehreren Service Desk-Mitarbeitern abrufen
    • Senden einer Anforderung zum Abrufen eines Agent-Protokolls und Abrufen von Informationen über den Fortschritt der Anforderung.
    • Datenerfassung starten oder stoppen
    • Agent wird neu gestartet.
    • Erkennung 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 AccAgentsAPIinitialisiert wird.

    var agentsApi = new sn_agent.AccAgentsAPI();

    AccAgentsAPI – checkGrabLogRequestProgress(String requestId)

    Überprüft den Status einer Grab-Protokollanforderung.

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

    Das folgende Beispiel zeigt, wie eine Anforderungs-ID verwendet wird, um den Status einer Grab-Protokollanforderung 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 Agent-IDs ab:
    • Führen Sie die Methode getAgentsList() aus.
    • Überprüfen Sie die Spalte „Agent ID“ der Tabelle „Agent Client Collectors“ [sn_agent_cmdb_ci_agent].
    • Führen Sie die REST-API Agent Client Collector GET list aus.
    Tabelle : 4. Parameter
    Name Typ Beschreibung
    agentID Zeichenfolge Eindeutige ID eines Agent, der in der Spalte „Agent-ID“ der Tabelle „Agent Client Collectors“ [sn_agent_cmdb_ci_agent] aufgeführt ist.
    Tabelle : 5. Ergebnisse
    Eigenschaften Beschreibung
    <Object> Objekt mit erweiterten Agent-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 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 (automatisch) – Prüfungen wurden aufgrund des hohen CPU-Verbrauchs durch den automatisch deaktiviert

    Datentyp: Zahl
    agent.ip_address Agent-IP-Adresse

    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:
    • true: Der Agent hat denselben Host wie ein Alive/Up-Agent mit einer anderen Agent-ID. Deaktivieren oder deinstallieren Sie das Duplikat
    • false: Dieser Agent hat keine Duplikate im Status „Alive/Up“.

    Datentyp: Boolesch
    agent.is_restart_enabled

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

    Mögliche Werte:
    • true: Neustart ist für diesen Agent aktiviert.
    • false: 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 Agent ausführen soll. 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/In Betrieb – Der Agent ist aktiv.
    • 1: Warnung – Der Agent hat in den letzten Minuten keine Keep-Alive-Nachricht erhalten.
    • 2: Ausgefallen – Der Agent hat seit längerer Zeit keine Keep-Alive-Nachricht erhalten.
    • 3: Wird neu gestartet – Der Agent wird neu gestartet.

    Datentyp: Zahl
    agent.up_seit UTC-Zeit, seit der Status des Service Desk-Mitarbeiters aktiviert wurde. Der Wert liegt im GlideDateTime -Format vor.

    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 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, Number limit)

    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. Weitere Informationen finden Sie unter 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. Ergebnisse
    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 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 (automatisch) – Prüfungen wurden aufgrund des hohen CPU-Verbrauchs durch den automatisch deaktiviert

    Datentyp: Zahl
    ip_address Agent-IP-Adresse

    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:
    • true: Der Agent hat denselben Host wie ein Alive/Up-Agent mit einer anderen Agent-ID. Deaktivieren oder deinstallieren Sie das Duplikat
    • false: Dieser Agent hat keine Duplikate im Status „Alive/Up“.

    Datentyp: Boolesch
    is_restart_enabled

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

    Mögliche Werte:
    • true: Neustart ist für diesen Agent aktiviert.
    • false: 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 Agent ausführen soll. 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/In Betrieb – Der Agent ist aktiv.
    • 1: Warnung – Der Agent hat in den letzten Minuten keine Keep-Alive-Nachricht erhalten.
    • 2: Ausgefallen – Der Agent hat seit längerer Zeit keine Keep-Alive-Nachricht erhalten.
    • 3: Wird neu gestartet – Der Agent wird neu gestartet.

    Datentyp: Zahl
    up_seit UTC-Zeit, seit der Status des Service Desk-Mitarbeiters aktiviert wurde. Der Wert liegt im GlideDateTime -Format vor.

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

    Datentyp: Zeichenfolge

    Das folgende Beispiel zeigt, wie die 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 alle Service Desk-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 durchlaufen 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 – restartAgent(String agentID)

    Startet einen angegebenen Agent mit dem Status „Alive/In Betrieb“ 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“ der Tabelle „Agent Client Collectors“ [sn_agent_cmdb_ci_agent].
    • Führen Sie die REST-API Agent Client Collector GET list aus.
    Tabelle : 8. Parameter
    Name Typ Beschreibung
    agentID Zeichenfolge Eindeutige ID eines Agent, 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 Agent 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 Erkennungsprüfung aus, um CIs zu finden, die zu einem Agent gehören. Der angegebene Agent muss sich im Status „Alive/In Betrieb“ befinden.

    So rufen Sie eine Liste der Agent-IDs ab:
    • Führen Sie die Methode getAgentsList() aus.
    • Überprüfen Sie die Spalte „Agent ID“ der Tabelle „Agent Client Collectors“ [sn_agent_cmdb_ci_agent].
    • Führen Sie die REST-API Agent Client Collector GET list aus.
    Tabelle : 10. Parameter
    Name Typ Beschreibung
    agentID Zeichenfolge Eindeutige ID eines Agent, 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 ausgelöster Fehler .

    Das folgende Beispiel zeigt, wie die Erkennung für einen Agent mit dem Status „Alive/In Betrieb“ 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, Boolean status)

    Legen Sie den angegebenen Datenerfassungsstatus (wahr/falsch, falls aktiviert oder nicht) für einen angegebenen 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“ der Tabelle „Agent Client Collectors“ [sn_agent_cmdb_ci_agent].
    • Führen Sie die REST-API Agent Client Collector GET list aus.
    Tabelle : 12. Parameter
    Name Typ Beschreibung
    agentID Zeichenfolge Eindeutige ID eines Agent, 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.
    • false: Deaktiviert die Datenerfassung für diesen Agent.

    Standardwert: true
    Tabelle : 13. Ergebnisse
    Typ Beschreibung
    Zeichenfolge Fehlermeldung, falls zutreffend, andernfalls NULL. Beispiel: Agent mit ID:<agentID> Ist nicht aktiv: 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 „Alive/In Betrieb“ an.

    Hinweis:
    Um das Protokoll abzurufen und seinen Fortschritt zu überprüfen, übergeben Sie die zurückgegebene Anforderungs-ID an die checkGrabLogRequestProgress()- Methode.
    Tabelle : 14. Parameter
    Name Typ Beschreibung
    agentID Zeichenfolge Eindeutige ID eines Agent, der in der Spalte „Agent-ID“ der Tabelle „Agent Client Collectors“ [sn_agent_cmdb_ci_agent] aufgeführt ist.
    Tabelle : 15. Ergebnisse
    Eigenschaften Beschreibung
    <Object> JSON-Objekt mit der Anforderungs-ID und etwaigen 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 GET /agents/{request_id}/ abzurufen.

    Datentyp: Zeichenfolge

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

    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>