이벤트 알림 관리 개방형 API

  • 릴리스 버전: Yokohama
  • 업데이트 날짜 2025년 01월 30일
  • 읽기10분

    • Event Notification Management Open API는 이벤트 [em_event] 테이블에서 이벤트를 생성, 업데이트 및 삭제할 수 있는 엔드포인트를 제공합니다.

    Event Notification Management Open API(sn_ind_tmf688)는 ServiceNow TM Forum Open API 사양을 구현한 것입니다. 이 API는 TMF688 이벤트 관리 API 사용자 가이드 v4.0.0을 기반으로 합니다. TMF642 알람 관리 API 사용자 가이드에서 추가 알람 정보를 찾을 수 있습니다.

    이 API는 필수 매개변수, 요청 본문 확인, 추가 REST 작업 및 필드 매핑에 대한 사용자 지정을 수행하도록 확장할 수 있습니다. 자세한 내용은 는 Event Notification Management Open API 개발자 가이드.

    이벤트 알림 관리 개방형 API – POST instance_name/scope_id/GUID

    관련 요청의 페이로드를 NowMQ 큐에 배치합니다. 그런 다음 이 큐는 백그라운드에서 처리되어 이벤트 [em_event] 테이블 내에서 이벤트를 생성, 업데이트 및 삭제합니다.

    이 엔드포인트는 플랫폼의 다른 엔드포인트와 ServiceNow 다릅니다. 만들기, 업데이트 및 삭제와 같은 각 특정 작업에 대한 엔드포인트가 있는 대신 모든 기능에 대해 하나의 엔드포인트만 있습니다. 호출 페이로드의 매개변수는 eventType전달된 AlarmCreateEvent, AlarmUpdateEvent 또는 AlarmDeleteEvent 값에 따라 수행할 작업을 결정합니다.

    REST 호출의 형식도 표준 REST 구현과 다릅니다. 이 API를 사용할 각 외부 시스템(예: Kafka, 데이터베이스 모니터 또는 기타 애플리케이션)은 ServiceNow 먼저 플랫폼에 등록해야 합니다. 또한 등록 중에 제공된 정보를 사용하여 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. 요청 본문 매개변수
    이름 설명
    이벤트 발생한 이벤트에 대한 상세 정보입니다.

    데이터 유형: 객체

    "event": {
  "alarm": {Object}
}
    이벤트.경보 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 경보의 영향을 받는 하나 이상의 서비스 목록입니다.

    데이터 유형: 객체 배열

    "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일 Id 때 eventType 필요합니다.

    경보를 게시하는 소스 시스템의 경보에 대한 고유 식별자입니다.

    데이터 유형: 문자열
    event.alarm.href 경보에 대한 URL 참조입니다.

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

    데이터 유형: 문자열
    event.alarm.id 가 지정되지 않은 경우 externalAlarmIdAlarmDeleteEvent 또는 AlarmChangeEvent일 때 eventType 필요합니다.

    경보의 고유 식별자입니다. 경보 소유 시스템에 의해 지정됩니다.

    예: "8675399"

    데이터 유형: 문자열
    event.alarm.perceivedSeverity AlarmCreateEvent일 때 eventType 필요합니다.

    경보와 관련된 가능한 심각도입니다. 값이 ITU-T 권고안 X.733과 일치합니다. 경보가 지워지면 인식된 심각도가 'CLEAR'로 설정되고 더 이상 설정할 수 없습니다.

    유효한 값은 다음과 같습니다.
    • 맑다
    • CRITICAL
    • 전공
    • 사소한
    • 경고

    데이터 유형: 문자열
    event.alarm.probableCause AlarmCreateEvent일 때 eventType 필요합니다.

    경보를 트리거할 가능성이 가장 높은 상황입니다. 경보를 검증하기 위해 사용합니다 alarmType .

    가능한 값은 ITU-T 권장 사항 X.733 또는 3GPP TS 32.111-2 Annex B와 일치합니다.

    예: "임계치 초과"

    데이터 유형: 문자열
    event.alarm.sourceSystemId AlarmCreateEvent일 때 eventType 필요합니다.

    경보에 대한 소스 시스템의 고유 식별자입니다.

    예: "SOURCE_SYSTEM_vManage_00000_000_00"

    데이터 유형: 문자열
    event.alarm.specificProblem 경보를 트리거하는 특정 문제입니다. 알람을 검증하는 tparameter o와 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"
      }
    }
  }
}

    반환된 응답이 없습니다.