이벤트 알림 관리 개방형 API

  • 릴리스 버전: Xanadu
  • 업데이트 날짜 2024년 08월 01일
  • 읽기10분

    • 이벤트 알림 관리 Open API는 이벤트 [em_event] 테이블에서 이벤트를 작성, 업데이트 및 삭제하기 위한 엔드포인트를 제공합니다.

    Event Notification Management Open API(sn_ind_tmf688)는 TM Forum Open API 스펙의 구현입니다ServiceNow. 이 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 구현과 다릅니다. Kafka, 데이터베이스 모니터 또는 기타 애플리케이션과 같이 이 API를 사용할 각 외부 시스템은 먼저 플랫폼에 등록 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(구성 항목)에 매핑됩니다.

    데이터 유형: 문자열
    이벤트.경보.경보 객체 이벤트를 생성할 때 필요합니다.
    경보 객체의 상세 정보입니다.

    데이터 유형: 객체

    "alarmedObject":
{
  "href": "String",
  "id": "String"
}
    event.alarm.alarmedObject.href 이벤트를 생성할 때 필요합니다.
    경보 객체의 상세 정보를 가져오는 URL 참조입니다.

    데이터 유형: 문자열
    event.alarm.alarmedObject.id AlarmCreateEvent인 경우 eventType 필요합니다.
    경보 개체의 고유 식별자입니다. 이 값은 시스템의 CI에 매핑됩니다.

    데이터 유형: 문자열
    이벤트.경보.경보유형 AlarmCreateEvent인 경우 eventType 필요합니다.

    경보의 유형입니다. 경보를 분류하는 데 사용됩니다.

    예: "QualityOfServiceAlarm"

    데이터 유형: 문자열
    event.alarm.crossedThresholdInfomation 초과된 임계치에 대한 상세 정보입니다.

    데이터 유형: 객체

    "crossedThresholdInformation":
{
  "thresholdId": "String"
}
    event.alarm.crossedThresholdInfomation.thresholdId
    경보를 발생시킨 임계치의 고유 식별자입니다.

    데이터 유형: 문자열
    event.alarm.externalAlarmId AlarmCreateEvent인 경우 eventType 필요합니다. 매개 변수가 지정되지 않은 경우 AlarmDeleteEvent 또는 AlarmChangeEvent일 Id 때 eventType 필요합니다.

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

    데이터 유형: 문자열
    이벤트.알람.href 경보에 대한 URL 참조입니다.

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

    데이터 유형: 문자열
    event.alarm.id 지정되지 않은 경우 eventTypeAlarmDeleteEvent 또는 AlarmChangeEvent 인 경우 externalAlarmId 필요합니다.

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

    예: "8675399"

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

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

    가능한 값:
    • 맑다
    • 비판적인
    • 전공
    • 사소한
    • 경고

    데이터 유형: 문자열
    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 필수 처리할 이벤트의 유형입니다.
    유효한 값은 다음과 같습니다.
    • 알람 변경 알림
    • 알람 생성 알림
    • 알람삭제 알림

    데이터 유형: 문자열

    헤더

    다음 요청 및 응답 헤더는 이 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"
      }
    }
  }
}

    응답이 반환되지 않았습니다.