Event Notification Management Open API

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

    • Die Event Notification Management Open API bietet einen Endpunkt zum Erstellen, Aktualisieren und Löschen von Events aus der Event-Tabelle [em_event].

    Die Event Notification Management Open API (sn_ind_tmf688) ist eine ServiceNow Implementierung der TM Forum Open API-Spezifikation. Diese API basiert auf TMF688 Event Management API User Guide v4.0.0. Weitere Informationen zu Alarmen finden Sie im TMF642 Alarm Management API-Benutzerhandbuch.

    Diese API kann erweitert werden, um Anpassungen für erforderliche Parameter, Anforderungstextvalidierung, zusätzliche REST-Vorgänge und Feldzuordnungen vorzunehmen. Weitere Informationen finden Sie unter die Event Notification Management Open API-Entwicklerleitfaden.

    Event Notification Management Open API – POST instance_name/scope_id/GUID

    Platziert die Nutzlast der zugeordneten Anforderung in der NowMQ-Warteschlange. Diese Warteschlange wird dann im Hintergrund verarbeitet, um Events in der Tabelle „Events“ [em_event] zu erstellen, zu aktualisieren und zu löschen.

    Dieser Endpunkt unterscheidet sich von anderen Endpunkten in der Plattform ServiceNow. Anstatt einen Endpunkt für jede spezifische Aufgabe zu haben, z. B. Erstellen, Aktualisieren und Löschen, gibt es nur einen einzigen Endpunkt für alle Funktionen. Der Parameter eventType in der Anrufnutzlast bestimmt die auszuführende Aufgabe basierend auf dem übergebenen Wert von AlarmCreateEvent, AlarmUpdateEventoder AlarmDeleteEvent.

    Das Format des REST-Aufrufs unterscheidet sich auch von standardmäßigen REST-Implementierungen. Jedes externe System, das diese API verwendet, z. B. Kafka, Datenbanküberwachungen oder andere Anwendungen, muss zuerst bei der ServiceNow -Plattform registriert werden. Sie müssen auch über einen eigenen Webhook verfügen, der die bei der Registrierung angegebenen Informationen verwendet, um die für den Aufruf dieses Endpunkts erforderliche Signatur zu generieren, einschließlich instance_name, application scope_idund eindeutige GUID. Die GUID identifiziert das externe Netzwerksystem, von dem die Anforderung stammt.

    Die Nutzlast, die Sie für diesen Endpunkt übergeben, muss mit der Nutzlast korrelieren, die in der Skripteinbindung TMFAlarmAPIConstants für den entsprechenden Parameterwert eventType definiert ist. Alle Parameter, die in der Nutzlast übergeben werden und nicht im Schema definiert sind, werden vom Endpunkt ignoriert.
    • AlarmCreateEvent: ALARM_CREATE_EVENT_SCHEMA
    • AlarmUpdateEvent: ALARM_CHANGE_EVENT_SCHEMA
    • AlarmDeleteEvent: ALARM_DELETE_EVENT_SCHEMA

    URL-Format

    Standard-URL:<instance_name> /<scope_id> /<GUID>

    Unterstützte Anforderungsparameter

    Tabelle : 1. Pfadparameter
    Name Beschreibung
    Keine
    Tabelle : 2. Abfrageparameter
    Name Beschreibung
    Keine
    Tabelle : 3. Anforderungstextparameter
    Name Beschreibung
    event Details zum aufgetretenen Event.

    Datentyp: Objekt

    "event": {
    "alarm": {Object}
}
    event.alarm Erforderlich, wenn eventTypeAlarmCreateEventist.

    Details zum zugeordneten Alarm.

    Datentyp: Objekt

    "alarm": {
  "affectedService": [Array],
  "alarmedObject": {Object},
  "alarmType": "String",
  "crossedThresholdInformation": {Object},
  "externalAlarmId": "String",
  "href": "String",
  "id": "String",
  "perceivedSeverity": "String",
  "probableCause": "String",
  "sourceSystemId": "String",
  "specificProblem": "String",
}
    event.alarm.affectedService Liste der Objekte, die einen oder mehrere vom Alarm betroffene Services identifizieren.

    Datentyp: Array

    "affectedService":[
  {
    "href": "String",
    "id": "String"
  },
]
    event.alarm.affectedService.href URL-Referenz mit Details zum betroffenen Service.

    Datentyp: Zeichenfolge
    event.alarm.affectedService.id
    Bezeichner des vom Alarm betroffenen Services. Dieser Wert ist dem betroffenen Configuration Item (CI) in der Warnung zugeordnet.

    Datentyp: Zeichenfolge
    event.alarm.alarmedObject Erforderlich beim Erstellen eines Events.
    Details des Alarmobjekts.

    Datentyp: Objekt

    "alarmedObject":
{
  "href": "String",
  "id": "String"
}
    event.alarm.alarmedObject.href Erforderlich beim Erstellen eines Events.
    URL-Referenz zum Abrufen der Details des Alarmobjekts.

    Datentyp: Zeichenfolge
    event.alarm.alarmedObject.id Erforderlich, wenn eventTypeAlarmCreateEventist.
    Eindeutiger Bezeichner des Alarmobjekts. Dieser Wert ist einem CI im System zugeordnet.

    Datentyp: Zeichenfolge
    event.alarm.alarmType Erforderlich, wenn eventTypeAlarmCreateEventist.

    Typ des Alarms. Wird verwendet, um den Alarm zu kategorisieren.

    Beispiel: „QualityOfServiceAlarm“

    Datentyp: Zeichenfolge
    event.alarm.crossedThresholdInfomation Details zum überschrittenen Schwellenwert.

    Datentyp: Objekt

    "crossedThresholdInformation":
{
  "thresholdId": "String"
}
    event.alarm.crossedThresholdInfomation.thresholdId
    Eindeutiger Bezeichner des Schwellenwerts, der den Alarm ausgelöst hat.

    Datentyp: Zeichenfolge
    event.alarm.externalAlarmId Erforderlich, wenn eventTypeAlarmCreateEventist. Erforderlich, wenn eventTypeAlarmDeleteEvent oder AlarmChangeEvent ist und der Parameter Id nicht angegeben ist.

    Eindeutiger Bezeichner für den Alarm aus dem Quellsystem, das den Alarm sendet.

    Datentyp: Zeichenfolge
    event.alarm.href URL-Verweis auf den Alarm.

    Beispiel: "http://api/alarm/ROUTER_IF@Cisco-0000-0-0-0-0-00-00-0-- Xz0/00@00"

    Datentyp: Zeichenfolge
    event.alarm.id Erforderlich, wenn eventTypeAlarmDeleteEvent oder AlarmChangeEvent ist, wenn externalAlarmId nicht angegeben ist.

    Eindeutiger Bezeichner des Alarms. Wird vom Besitzersystem des Alarms angegeben.

    Beispiel: „8675399“

    Datentyp: Zeichenfolge
    event.alarm.perceivedSeverity Erforderlich, wenn eventTypeAlarmCreateEventist.

    Mögliche Schweregrade, die dem Alarm zugeordnet sind. Die Werte stimmen mit der ITU-T-Empfehlung X.733 überein. Nachdem ein Alarm gelöscht wurde, wird sein wahrgenommener Schweregrad auf „LÖSCHEN“ gesetzt und kann nicht mehr festgelegt werden.

    Mögliche Werte:
    • LÖSCHEN
    • KRITISCH
    • GRÜNDLICH
    • GERINGFÜGIG
    • WARNUNG

    Datentyp: Zeichenfolge
    event.alarm.probableCause Erforderlich, wenn eventTypeAlarmCreateEventist.

    Wahrscheinlichste Situation, um den Alarm auszulösen. Verwenden Sie diese Option mit alarmType, um den Alarm zu qualifizieren.

    Die möglichen Werte stimmen mit der ITU-T-Empfehlung X.733 oder 3GPP TS 32.111-2 Anhang B überein.

    Beispiel: „Schwellenwert überschritten“

    Datentyp: Zeichenfolge
    event.alarm.sourceSystemId Erforderlich, wenn eventTypeAlarmCreateEventist.

    Eindeutiger Identifier des Quellsystems des Alarms.

    Beispiel: „SOURCE_SYSTEM_vManage_00000_000_00“

    Datentyp: Zeichenfolge
    event.alarm.specificProblem Spezifisches Problem, das den Alarm auslöst. Verwenden Sie diese Option mit probableCause, um den Alarm zu qualifizieren.

    Beispiel: „Schwellenwert für eingehenden Datenverkehr überschritten“

    Datentyp: Zeichenfolge
    eventType Erforderlich. Typ des zu verarbeitenden Ereignisses.
    Gültige Werte:
    • AlarmChangeNotification
    • AlarmCreateNotification
    • AlarmDeleteNotification

    Datentyp: Zeichenfolge

    Header

    Die folgenden Anforderungs- und Antwortkopfzeilen gelten nur für diese HTTP-Aktion oder für diese Aktion auf eine bestimmte Weise. Eine Liste der allgemeinen Header, die in der REST-API verwendet werden, finden Sie unter Unterstützte REST-API-Header.

    Tabelle : 4. Anforderungskopfzeilen
    Kopfzeile Beschreibung
    Akzeptieren Datenformat des Antworttexts. Unterstützt nur application/json.
    Tabelle : 5. Antwortkopfzeilen
    Kopfzeile Beschreibung
    Keine

    Statuscodes

    Die folgenden Statuscodes gelten für diese HTTP-Aktion. Eine Liste der möglichen Statuscodes, die in der REST-API verwendet werden, finden Sie unter HTTP-Antwortcodesder REST-API.

    Tabelle : 6. Statuscodes
    Statuscode Beschreibung
    200 Wird für jeden Anruf zurückgegeben, unabhängig vom tatsächlichen Verarbeitungsstatus des Anrufs. Gibt nur an, dass der Endpunkt die Anforderung erhalten hat.

    Parameter des Antwort-Haupttexts

    Name Beschreibung
    Keine Dieser Endpunkt ist asynchron und gibt daher keine Antwortdaten zurück.

    cURL-Anforderung

    Im Folgenden ist die mögliche Nutzlast für das Erstellen eines Alarmereignisses dargestellt. Dieses Beispiel spiegelt die Parameter wider, die in der Standardimplementierung (AlarmCreateEventSchema) enthalten sind.

    
--data "{
  "eventType": "AlarmCreateNotification",
  "event": {
    "alarm": {
      "id": "",
      "externalAlarmId": "ext123456",
      "alarmType": "QualityOfServiceAlarm",
      "perceivedSeverity": "MINOR",
      "alarmedObject": {
        "id": "vManage_000000",
        "href": " http://api/alarmedobject/000000"
      },
      "probableCause": "Threshold crossed",
      "sourceSystemId": "SOURCE_SYSTEM_vManage_00000_000_00",
      "href": "http://api/alarm/ROUTER_IF@Cisco-0000-0-0-0-0-00-00-0-- Xz0/00@00",
      "specificProblem": "Inbound Traffic threshold crossed",
      "crossedThresholdInformation": {
        "thresholdId": "12fasdfasdfasd"
      },
      "affectedService": [
        {
          "id": "SD WAN Enterprise Solutions",
          "href": "http://api/service/vlan_dot0_dot0"
        }
      ]
    }
  }
}

    Keine Antwort zurückgegeben.

    cURL-Anforderung

    Das Folgende zeigt die mögliche Nutzlast für ein Change-Alarm-Event. Dieses Beispiel spiegelt die Parameter wider, die in der Standardimplementierung (AlarmChangeEventSchema) enthalten sind.

    
--data "{
  "eventType": "AlarmChangeEventSchema",
  "event": {
    "alarm": {
      "id": "",
      "externalAlarmId": "ext123456",
      "perceivedSeverity": "MAJOR",
      "probableCause": "Threshold crossed",
      "crossedThresholdInformation": {
        "thresholdId": "12fasdfasdfasd"
      },
      "affectedService": [
        {
          "id": "SD WAN Enterprise Solutions",
          "href": "http://api/service/vlan_dot0_dot0"
        }
      ]
    }
  }
}

    Keine Antwort zurückgegeben.

    cURL-Anforderung

    Im Folgenden wird die mögliche Nutzlast für ein Alarmereignis vom Typ „Löschen“ (löschen) angezeigt. Dieses Beispiel spiegelt die Parameter wider, die in der Standardimplementierung (AlarmDeleteEventSchema) enthalten sind.

    
--data "{
  "eventType": "AlarmDeleteEventSchema",
  "event": {
    "alarm": {
      "id": "",
      "externalAlarmId": "ext123456",
      "perceivedSeverity": "MAJOR",
      "probableCause": "Threshold crossed",
      "crossedThresholdInformation": {
        "thresholdId": "12fasdfasdfasd"
      }
    }
  }
}

    Keine Antwort zurückgegeben.