イベント通知管理オープン API

  • リリースバージョン: Washingtondc
  • 更新日 2024年02月01日
  • 読む11読むのに数分

    • イベント通知管理オープン API は、イベント [em_event] テーブルのイベントを作成、更新、および削除するためのエンドポイントを提供します。

    Event Notification Management Open API (sn_ind_tmf688) は、ServiceNowTM Forum Open API 仕様の実装です。この API は、 TMF688 Event Management API User Guide v4.0.0 に基づいています。追加のアラーム情報については、 『TMF642 アラーム管理 API ユーザー・ガイド』を参照してください。

    この API を拡張して、必要なパラメーター、要求本文の検証、追加の REST 操作、およびフィールドマッピングに関するカスタマイズを実行できます。詳細については、次を参照してください： です イベント通知管理オープン API 開発者ガイド。

    イベント通知管理オープン API – POST instance_name/scope_id/GUID

    関連する要求のペイロードを NowMQ キューに配置します。このキューはバックグラウンドで処理され、イベント [em_event] テーブル内のイベントを作成、更新、および削除します。

    このエンドポイントは、プラットフォーム内の ServiceNow 他のエンドポイントとは異なります。作成、更新、削除などの特定のタスクごとにエンドポイントを持つ代わりに、すべての機能に対して 1 つのエンドポイントのみがあります。呼び出しペイロードのパラメーターeventTypeは、渡された AlarmCreateEvent、AlarmUpdateEvent、または AlarmDeleteEvent の値に基づいて、実行するタスクを決定します。

    REST 呼び出しの形式も、標準の REST 実装とは異なります。Kafka、データベースモニター、その他のアプリケーションなど、この API を使用する各外部システムは、最初にプラットフォームに登録 ServiceNow する必要があります。また、登録時に提供された情報を使用して、 instance_name、アプリケーション scope_id、一意の GUID など、このエンドポイントを呼び出すために必要な署名を生成する独自の Webhook を配置する必要もあります。GUID は、要求の送信元の外部ネットワーク システムを識別します。

    このエンドポイントに渡すペイロードは、対応するeventTypeパラメーター値の TMFAlarmAPIConstants スクリプトインクルードで定義されているペイロードに関連付けられている必要があります。ペイロードで渡され、スキーマで定義されていないパラメーターは、エンドポイントによって無視されます。
    • AlarmCreateEvent: ALARM_CREATE_EVENT_SCHEMA
    • AlarmUpdateEvent: ALARM_CHANGE_EVENT_SCHEMA
    • AlarmDeleteEvent: ALARM_DELETE_EVENT_SCHEMA

    URL 形式

    デフォルトの URL: <instance_name>/<scope_id>/<GUID>

    サポートされている要求パラメーター

    表 : 1. パスパラメーター
    名前 説明
    なし
    表 : 2. クエリパラメータ
    名前 説明
    なし
    表 : 3. 要求本文パラメーター
    名前 説明
    イベント 発生したイベントの詳細。

    データタイプ: オブジェクト

    "event": {
    "alarm": {Object}
}
    event.alarm は AlarmCreateEvent の場合はeventType必須です。

    関連付けられたアラームに関する詳細。

    データタイプ: オブジェクト

    "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 アラームの影響を受ける 1 つ以上のサービスを識別するオブジェクトのリスト。

    データタイプ：アレイ

    "affectedService":[
  {
    "href": "String",
    "id": "String"
  },
]
    event.alarm.affectedService.href 影響を受けるサービスの詳細を提供する URL 参照。

    データタイプ：文字列
    event.alarm.affectedService.id
    アラームの影響を受けるサービスの識別子。この値は、アラートの影響を受ける構成アイテム (CI) にマップされます。

    データタイプ：文字列
    event.alarm.alarmedObject イベントを作成するときに必須です。
    アラームオブジェクトの詳細。

    データタイプ: オブジェクト

    "alarmedObject":
{
  "href": "String",
  "id": "String"
}
    event.alarm.alarmedObject.href イベントを作成するときに必須です。
    アラームオブジェクトの詳細を取得するための URL 参照。

    データタイプ：文字列
    event.alarm.alarmedObject.id は AlarmCreateEvent の場合はeventType必須です。
    アラームオブジェクトの一意の識別子。この値はシステム内の CI にマップされます。

    データタイプ：文字列
    event.alarm.alarmType は AlarmCreateEvent の場合はeventType必須です。

    アラームのタイプ。アラームを分類するために使用されます。

    例:「QualityOfServiceAlarm」

    データタイプ：文字列
    event.alarm.crossedThresholdInfomation 超過したしきい値に関する詳細。

    データタイプ: オブジェクト

    "crossedThresholdInformation":
{
  "thresholdId": "String"
}
    event.alarm.crossedThresholdInfomation.thresholdId
    アラームを発生させたしきい値の一意の識別子。

    データタイプ：文字列
    event.alarm.externalAlarmId は AlarmCreateEvent の場合はeventType必須です。パラメーターが指定されていない場合は、AlarmDeleteEvent または AlarmChangeEvent の場合はeventType必須ですId。

    アラームを投稿しているソースシステムからのアラームの一意の識別子。

    データタイプ：文字列
    event.alarm.href アラームへの URL 参照。

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

    データタイプ：文字列
    event.alarm.id は AlarmDeleteEvent または AlarmChangeEvent が指定されeventTypeていない場合はexternalAlarmId必須です。

    アラームの一意の識別子。アラーム所有システムによって指定されます。

    例:「8675399」

    データタイプ：文字列
    event.alarm.perceivedSeverity は AlarmCreateEvent の場合はeventType必須です。

    アラームに関連する可能性のある重大度。値は、ITU-T 勧告 X.733 と一致しています。アラームがクリアされると、その認識された重大度は「CLEAR」に設定され、設定できなくなります。

    可能な値：
    • CLEAR
    • CRITICAL
    • MAJOR
    • MINOR
    • 警告

    データタイプ：文字列
    event.alarm.probableCause は AlarmCreateEvent の場合はeventType必須です。

    アラームをトリガーする可能性が最も高い状況。alarmType とともに使用してアラームを認定します。

    可能な値は、ITU-T 勧告 X.733 または 3GPP TS 32.111-2 附属書 B と一致しています。

    例:「しきい値を超えました」

    データタイプ：文字列
    event.alarm.sourceSystemId は AlarmCreateEvent の場合はeventType必須です。

    アラームのソースシステムの一意の識別子。

    例:「SOURCE_SYSTEM_vManage_00000_000_00」

    データタイプ：文字列
    event.alarm.specificProblem アラームをトリガーする特定の問題。probableCause とともに使用してアラームを認定します。

    例:「受信トラフィックのしきい値を超えました」

    データタイプ：文字列
    eventType 必須です。処理するイベントのタイプ。
    有効な値：
    • アラーム変更通知
    • AlarmCreateNotification
    • AlarmDeleteNotification

    データタイプ：文字列

    ヘッダー

    次のリクエストや応答ヘッダーは、この HTTP アクションにのみ適用されるか、またはこのアクションに別個の方法で適用されます。REST API で使用される一般的なヘッダーのリストについては、「 サポートされている REST API ヘッダー」を参照してください。

    表 : 4. 要求ヘッダー
    ヘッダー 説明
    承認 応答本文のデータフォーマット。application/json のみをサポートします。
    表 : 5. 応答ヘッダー
    ヘッダー 説明
    なし

    ステータスコード

    この HTTP アクションには、次のステータスコードが適用されます。REST API で使用される可能性のあるステータスコードのリストについては、「 REST API HTTP 応答コード」を参照してください。

    表 : 6. ステータスコード
    ステータスコード 説明
    200 呼び出しの実際の処理ステータスに関係なく、すべての呼び出しに対して返されます。エンドポイントが要求を受信したことを示すだけです。

    応答本文のパラメーター

    名前 説明
    なし このエンドポイントは非同期であるため、応答データは返されません。

    cURL 要求

    次に、アラーム作成イベントの可能なペイロードを示します。この例は、デフォルト実装 (AlarmCreateEventSchema) のパラメーターを反映しています。

    
--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"
        }
      ]
    }
  }
}

    応答が返されませんでした。

    cURL 要求

    次に、変更アラームイベントの可能なペイロードを示します。この例は、デフォルトの実装 (AlarmChangeEventSchema) にあるパラメーターを反映しています。

    
--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"
        }
      ]
    }
  }
}

    応答が返されませんでした。

    cURL 要求

    次に、削除(クリア)アラーム イベントの可能なペイロードを示します。この例は、デフォルト実装 (AlarmDeleteEventSchema) にあるパラメーターを反映しています。

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

    応答が返されませんでした。