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

  • リリースバージョン: Yokohama
  • 更新日 2025年01月30日
  • 所要時間：11分

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

    イベント通知管理オープン API (sn_ind_tmf688) は、TM フォーラムオープン API 仕様のServiceNow実装です。この API は、 TMF688 イベント管理 API ユーザーガイド 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 eventTypeが AlarmCreateEvent の場合は必須です。

    関連付けられたアラームの詳細。

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

    "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 eventTypeが AlarmCreateEvent の場合は必須です。
    アラームオブジェクトの一意の識別子。この値はシステム内の CI にマップされます。

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

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

    例:"QualityOfServiceAlarm"

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

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

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

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

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

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

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

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

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

    例:「8675399」

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

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

    有効な値：
    • CLEAR
    • CRITICAL
    • MAJOR
    • MINOR
    • 警告

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

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

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

    例:「しきい値超過」

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

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

    例:「SOURCE_SYSTEM_vManage_00000_000_00」

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

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

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

    データタイプ：文字列

    ヘッダー

    次のリクエストや応答ヘッダーは、この 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"
      }
    }
  }
}

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