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

  • リリースバージョン: Xanadu
  • 更新日 2024年08月01日
  • 所要時間：11分

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

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

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

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

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

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

    REST 呼び出しの形式も、標準の REST 実装とは異なります。Kafka、データベースモニター、その他のアプリケーションなど、この API を使用する各外部システムは、最初に ServiceNow プラットフォームに登録する必要があります。また、登録時に提供された情報を使用して、このエンドポイントを呼び出すために必要な署名を生成する独自の Webhook ( instance_name、アプリケーション scope_id、一意の GUID など) を用意する必要があります。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. 要求本文パラメーター
    名前 Description (説明)
    イベント 発生したイベントの詳細。

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

    "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 の場合は必須です。eventType が AlarmDeleteEvent の場合、または Id パラメーターが指定されていない場合は 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 eventType が AlarmDeleteEvent または AlarmChangeEvent (externalAlarmId が指定されていない場合) に必要です。

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

    例:「8675399」

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

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

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

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

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

    可能な値は、ITU-T 勧告 X.733 または 3GPP TS 32.111-2 Annex B に準拠しています。

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

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

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

    例:「SOURCE_SYSTEM_vManage_00000_000_00」

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

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

    データタイプ：文字列
    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"
      }
    }
  }
}

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