Offene API zur Verwaltung von Ereignisbenachrichtigungen

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

    • Die Event Notification Management Open API bietet einen Endpunkt zum Erstellen, Aktualisieren und Löschen von Ereignissen in der Ereignistabelle [em_event].

    Die Event Notification Management Open API (sn_ind_tmf688) ist eine ServiceNow Implementierung der Spezifikation TM Forum Open API. Diese API basiert auf dem TMF688 Event Management API-Benutzerhandbuch 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, die Validierung des Anforderungstexts, zusätzliche REST-Vorgänge und Feldzuordnungen vorzunehmen. Weitere Informationen finden Sie unter den Entwicklerhandbuch für die Open API für Event Notification Management.

    Offene API für Event Notification Management – POST instance_name/scope_id/GUID

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

    Dieser Endpunkt unterscheidet sich von anderen Endpunkten in der Plattform ServiceNow. Anstatt für jede bestimmte Aufgabe einen Endpunkt 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 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überwachungsanwendungen oder andere Anwendungen, muss sich zuerst bei der Plattform ServiceNow registrieren. 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 Instanzname, Anwendungsbereich_IDund eindeutiger GUID. Die GUID gibt das externe Netzwerksystem an, 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 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 Ereignis.

    Datentyp: Objekt

    "event": {
  "alarm": {Object}
}
    Ereignis.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 von mindestens einem Service, der vom Alarm betroffen ist.

    Datentyp: Array von Objekten

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

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

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

    Datentyp: Objekt

    "alarmedObject":
{
  "href": "String",
  "id": "String"
}
    event.alarm.alarmedObject.href Erforderlich beim Erstellen eines Ereignisses.
    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
    Ereignis.Alarm.AlarmTyp 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 verursacht hat.

    Datentyp: Zeichenfolge
    event.alarm.externalAlarmId Erforderlich, wenn eventTypeAlarmCreateEventist. Erforderlich, wenn eventTypeAlarmDeleteEvent oder AlarmChangeEvent ist, wenn 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 für den Alarm Verantwortlichen System angegeben.

    Beispiel: „8675399“

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

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

    Gültige Werte:
    • CLEAR
    • KRITISCH
    • GRÜNDLICH
    • Geringfügig
    • WARNUNG

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

    Wahrscheinlichste Situation, die den Alarm auslöst. Verwenden Sie mit alarmType, um den Alarm zu qualifizieren.

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

    Beispiel: „Schwellenwert überschritten“

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

    Eindeutiger Bezeichner des Quellsystems des Alarms.

    Beispiel: „SOURCE_SYSTEM_vManage_00000_000_00“

    Datentyp: Zeichenfolge
    event.alarm.specificProblem Spezifisches Problem, das den Alarm auslöst. Mit dem tParameter probableCause verwenden, um den Alarm zu qualifizieren.

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

    Datentyp: Zeichenfolge
    eventType Erforderlich. Typ des zu verarbeitenden Ereignisses.
    Gültige Werte:
    • AlarmChangeBenachrichtigung
    • AlarmErstellenBenachrichtigung
    • 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-Antwortcodes der 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 Ereignis „Alarm erstellen“ 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

    Im Folgenden ist die mögliche Nutzlast für ein Change-Alarm-Ereignis dargestellt. 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 ist die mögliche Nutzlast für das Alarmereignis Löschen (Löschen) dargestellt. 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.