Ereignismanagement-Thema – Offene API

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

    • Die Event Management Topic Open API bietet einen Endpunkt, mit dem Sie ein Thema über Ihren Nachrichten-Broker senden und in einer Instanz ServiceNow speichern können.

    Mit dieser API können Sie über Ihren Nachrichten-Broker erstellte Themen in der Tabelle ServiceNow Thema [topic] speichern.

    Diese API wird im Namespace sn-api-notif-mgmt ausgeführt und erfordert die Rolle sn_api_notif_mgmt.event_mgmt_integration.

    Ereignismanagement-Thema offen – POST /sn_api_notif_mgmt/topic

    Erstellt einen neuen Datensatz in der Thementabelle [sn_api_notif_mgmt_topic] und speichert die übergebenen Themeninformationen in diesem Datensatz.

    Verwenden Sie diesen Endpunkt, um in Ihrer Nachrichtenbus-Middleware erstellte Themen mit denen in Ihrer -Instanz ServiceNow zu synchronisieren.

    Wenn Themen mit diesem Endpunkt erstellt werden, wird das Feld user_created im zugehörigen Themendatensatz auf „false“ und das Feld „type“ auf „egress“festgelegt.

    URL-Format

    URL mit Versionsnummer: /api/sn_api_notif_mgmt/{api_version}/topic

    Standard-URL: /api/sn_api_notif_mgmt/topic

    Hinweis:
    Verfügbare Versionen werden im REST-API-Explorerangegeben. Für geskriptete REST APIs finden Sie zusätzliche Versionsinformationen im Formular „Geskripteter REST-Service“.

    Unterstützte Anforderungsparameter

    Tabelle : 1. Pfadparameter
    Name Beschreibung
    api_version Optional. Version des Endpunkts, auf den zugegriffen werden soll. Zum Beispiel v1 oder v2. Geben Sie diesen Wert nur an, um eine andere Endpunktversion als die neueste zu verwenden.

    Datentyp: Zeichenfolge
    Tabelle : 2. Abfrageparameter
    Name Beschreibung
    Keine
    Tabelle : 3. Anforderungstextparameter
    Name Beschreibung
    contentQuery Filter, der auf die Nutzlast des Ereignisse angewendet werden soll. Diese Abfrage ist ein tieferer Ereignisfilter, mit dem Informationen wie Ereignisschweregrad oder Tickettyp ermittelt werden. Sie können diesen Parameter als geschachtelte Abfrage übergeben.
    Für die folgende Nutzlast des Problemticketereignisses gilt diese Abfrage beispielsweise für die Attribute, die sich im Objekt „event“ der Nutzlast befinden:
    {
  "eventId":"dc2003c2c3bb3550054e20bdc0013136",
  "@type":"Troubleticket",
  "eventType":"TroubleTicketCreateEvent",
  "event":{
    "troubleTicket":{
      "short_description":"Test payload",
      "severity":3,
      "ticketType":"incident"
    }
  }
}
    Dieser Parameter unterstützt die folgenden Bedingungen:
    • UND: wie Variable1=Wert1&Variable2=Wert2&Variable3=Wert3
    • ODER: wie variable1=Wert1,Wert2,Wert3
    • Hierarchische Variablen: wie Variable1.Variable2.Variable3 = Wert1

    Beispiel: "contentQuery": "troubleTicket.ticketType=incident&troubleTicket.severity=1",

    Dieses Feld wird dem Feld „content_query“ im zugehörigen Themendatensatz zugeordnet.

    Weitere Informationen finden Sie im TMF688 Ereignismanagement-API-Benutzerhandbuch.

    Datentyp: Zeichenfolge
    externalId Eindeutiger externer Bezeichner für das Thema, z. B. eine GUID. Dieses Feld wird dem Feld „topic_id“ im zugehörigen Themendatensatz zugeordnet.

    Datentyp: Zeichenfolge
    headerQuery Filter, die auf die Eigenschaften des Ereignis-Headers angewendet werden sollen. Diese Abfrage definiert den Typ der Ereignisse, die für das zugeordnete Thema belauscht werden sollen. Sie können diesen Parameter als geschachtelte Abfrage übergeben.
    Dieser Parameter unterstützt die folgenden Bedingungen:
    • UND: wie Variable1=Wert1&Variable2=Wert2&Variable3=Wert3
    • ODER: wie variable1=Wert1,Wert2,Wert3
    • Hierarchische Variablen: wie Variable1.Variable2.Variable3 = Wert1

    Beispiel: „headerQuery“: „eventType=TroubleTicketStatusChangeEvent,TroubleTicketAttributeChangeEvent“

    Dieses Feld wird dem Feld „header_query“ im zugehörigen Themendatensatz zugeordnet.

    Weitere Informationen finden Sie im TMF688 Ereignismanagement-API-Benutzerhandbuch.

    Datentyp: Zeichenfolge
    name Der Name des Themas.

    Dieses Feld wird dem Feld „topic_name“ im zugehörigen Themendatensatz zugeordnet.

    Datentyp: Zeichenfolge
    namespace Namespace für das Thema. Leer, wenn kein Namespace zugeordnet ist.

    Dieses Feld wird dem Namespace-Feld im zugehörigen Themendatensatz zugeordnet.

    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.
    Content-Type Datenformat des Anforderungstexts. 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
    201 Erfolgreich. Die Anforderung wurde erfolgreich verarbeitet.
    400 Die übergebene externe ID des Themas ist bereits vorhanden. Übergeben Sie die eindeutige externe ID des Themas: Gibt an, dass die übergebene externe ID bereits in der Thementabelle vorhanden ist.

    Übergeben Sie die eindeutige Kombination aus Themenname, Header-Abfrage, Inhaltsabfrage und Namespace : Gibt an, dass die Kombination aus Themenname, Namespace, Header-Abfrage und Inhaltsabfrage bereits vorhanden ist.
    500 Interner Serverfehler. Beim Verarbeiten der Anforderung ist ein unerwarteter Fehler aufgetreten. Der Antworttext enthält Informationen zum Fehler.

    Parameter des Antwort-Haupttexts

    Name Beschreibung
    contentQuery Wert des Felds „content_query“ im erstellten Themendatensatz.

    Datentyp: Zeichenfolge
    externalId Wert des Felds „topic_id“ im erstellten Themendatensatz.

    Datentyp: Zeichenfolge
    headerQuery Wert des Felds „header_query“ im erstellten Themendatensatz. Dieses Feld wird vom Themenauswahl-Framework verwendet, um zu bestimmen, welche Ereignisnachrichten an ein Thema gesendet werden sollen.

    Datentyp: Zeichenfolge
    id Sys_id des erstellten Themendatensatzes.

    Datentyp: Zeichenfolge
    name Der Name des Themas.

    Datentyp: Zeichenfolge
    namespace Wert des Namespace-Felds im erstellten Themendatensatz.

    Datentyp: Zeichenfolge

    cURL-Anforderung

    Das folgende Codebeispiel zeigt, wie dieser Endpunkt aufgerufen wird.

    curl "http://instance.servicenow.com/api/sn_api_notif_mgmt/topic" \
--request POST \
--header "Accept:application/json" \
--user 'username':'password'
--data
{
  "name": "HighPriorityTroubleTicket",
  "headerQuery": "eventType=TroubleTicketStatusChangeEvent,TroubleTicketAttributeChangeEvent",
  "contentQuery": "troubleTicket.ticketType=incident&troubleTicket.severity=1",
  "externalId": "ext001",
  "namespace": "telecomEvents"
}

    Antwort:

    
{
  "externalId": "ext001",
  "name": "HighPriorityTroubleTicket",
  "headerQuery": "eventType=TroubleTicketStatusChangeEvent,TroubleTicketAttributeChangeEvent",
  "contentQuery": "troubleTicket.ticketType=incident&troubleTicket.severity=1",
  "namespace": "telecomEvents",
  "id": "7ee9850443c3f550461f99612bb8f223"
}