이벤트 관리 주제 개방형 API

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

    • Event Management Topic Open API는 메시지 브로커를 통해 주제를 전송하고 인스턴스에 저장할 ServiceNow 수 있는 엔드포인트를 제공합니다.

    이 API를 사용하면 메시지 브로커 ServiceNow 를 통해 생성된 주제를 주제 [topic] 테이블에 저장할 수 있습니다.

    이 API는 sn-api-notif-mgmt 네임스페이스에서 실행되며 sn_api_notif_mgmt.event_mgmt_integration 역할이 필요합니다.

    이벤트 관리 주제 오픈 - POST /sn_api_notif_mgmt/topic

    주제 [sn_api_notif_mgmt_topic] 테이블에 새 기록을 만들고 전달된 주제 정보를 해당 기록에 저장합니다.

    이 엔드포인트를 사용하여 메시지 버스 미들웨어에서 생성된 주제를 인스턴스의 주제와 동기화합니다 ServiceNow .

    이 엔드포인트를 사용하여 주제를 생성하면 관련 주제 기록의 user_created 필드가 false 로 설정되고 유형 필드가 송신으로 설정됩니다.

    URL 형식

    버전이 지정된 URL: /api/sn_api_notif_mgmt/v1/topic

    기본 URL: /api/sn_api_notif_mgmt/topic

    지원되는 요청 매개변수

    표 1. 경로 매개변수
    이름 설명
    api_version 옵션입니다. 액세스할 엔드포인트의 버전입니다. 예를 들면 v1 또는 v2입니다. 최신 버전이 아닌 엔드포인트 버전을 사용하려면 이 값만 지정합니다.

    데이터 유형: 문자열
    표 2. 쿼리 매개변수
    이름 설명
    없음
    표 3. 요청 본문 매개변수
    이름 설명
    contentQuery 이벤트의 페이로드에 적용할 필터입니다. 이 쿼리는 이벤트 심각도 또는 티켓 유형과 같은 정보를 찾는 데 사용되는 보다 심층적인 이벤트 필터입니다. 이 매개 변수를 중첩 쿼리로 전달할 수 있습니다.
    예를 들어 다음 문제 티켓 이벤트 페이로드의 경우 이 쿼리는 페이로드의 "이벤트" 객체에 있는 속성에 적용됩니다.
    {
  "eventId":"dc2003c2c3bb3550054e20bdc0013136",
  "@type":"Troubleticket",
  "eventType":"TroubleTicketCreateEvent",
  "event":{
    "troubleTicket":{
      "short_description":"Test payload",
      "severity":3,
      "ticketType":"incident"
    }
  }
}
    이 매개변수는 다음 조건을 지원합니다.
    • AND: 예: variable1=value1&variable2=value2&variable3=value3
    • 또는: 예: variable1=value1,value2,value3
    • 계층적 변수: 예: variable1.variable2.variable3=value1

    예: "contentQuery": "troubleTicket.ticketType=incident&troubleTicket.severity=1",

    이 필드는 연결된 주제 기록의 content_query 필드에 매핑됩니다.

    자세한 내용은 TMF688 이벤트 관리 API 사용 설명서를 참조하십시오.

    데이터 유형: 문자열
    externalId 주제에 대한 고유 외부 식별자(예: GUID)입니다. 이 필드는 연결된 주제 기록의 topic_id 필드에 매핑됩니다.

    데이터 유형: 문자열
    headerQuery 이벤트 헤더 속성에 적용할 필터입니다. 이 쿼리는 관련된 주제에 대해 수신할 이벤트의 유형을 정의합니다. 이 매개 변수를 중첩 쿼리로 전달할 수 있습니다.
    이 매개변수는 다음 조건을 지원합니다.
    • AND: 예: variable1=value1&variable2=value2&variable3=value3
    • 또는: 예: variable1=value1,value2,value3
    • 계층적 변수: 예: variable1.variable2.variable3=value1

    예: "headerQuery": "eventType=TroubleTicketStatusChangeEvent,TroubleTicketAttributeChangeEvent"

    이 필드는 연결된 주제 기록의 header_query 필드에 매핑됩니다.

    자세한 내용은 TMF688 이벤트 관리 API 사용 설명서를 참조하십시오.

    데이터 유형: 문자열
    이름 주제의 이름입니다.

    이 필드는 연결된 주제 기록의 topic_name 필드에 매핑됩니다.

    데이터 유형: 문자열
    네임스페이스 주제의 네임스페이스입니다. 연결된 네임스페이스가 없으면 비어 있습니다.

    이 필드는 관련 주제 기록의 네임스페이스 필드에 매핑됩니다.

    데이터 유형: 문자열

    헤더

    다음 요청 및 응답 헤더는 이 HTTP 작업에만 적용되거나 이 작업에 고유한 방식으로 적용됩니다. REST API에서 사용되는 일반 헤더 목록은 지원되는 REST API 헤더를 참조하세요.

    표 4. 요청 헤더
    헤더 설명
    수용 응답 본문의 데이터 형식입니다. application/json만 지원합니다.
    컨텐츠-형식 요청 본문의 데이터 형식입니다. application/json만 지원합니다.
    표 5. 응답 헤더
    헤더 설명
    없음

    상태 코드

    다음 상태 코드는 이 HTTP 작업에 적용됩니다. REST API에서 사용할 수 있는 상태 코드 목록은 REST API HTTP 응답 코드를 참조하세요.

    표 6. 상태 코드
    상태 코드 설명
    201 성공입니다. 요청이 성공적으로 처리되었습니다.
    400 전달된 주제 외부 ID가 이미 있습니다. 고유한 주제 외부 ID를 전달하십시오: 전달된 외부 ID가 주제 테이블에 이미 있음을 나타냅니다.

    항목 이름, 헤더 쿼리, 컨텐츠 쿼리 및 네임스페이스의 고유한 조합을 전달하십시오 . 항목 이름, 네임스페이스, 헤더 쿼리 및 컨텐츠 쿼리의 조합이 이미 있음을 나타냅니다.
    500 내부 서버 오류입니다. 요청을 처리하는 동안 예기치 않은 오류가 발생했습니다. 응답에는 오류에 대한 추가 정보가 포함되어 있습니다.

    응답 본문 매개변수

    이름 설명
    contentQuery 생성된 주제 기록의 content_query 필드 값입니다.

    데이터 유형: 문자열
    externalId 생성된 주제 기록의 topic_id 필드 값입니다.

    데이터 유형: 문자열
    headerQuery 생성된 주제 기록의 header_query 필드 값입니다. 이 필드는 주제 선택기 프레임워크에서 주제로 보내야 하는 이벤트 메시지를 결정하는 데 사용됩니다.

    데이터 유형: 문자열
    id 생성된 주제 기록의 Sys_id입니다.

    데이터 유형: 문자열
    이름 주제의 이름입니다.

    데이터 유형: 문자열
    네임스페이스 생성된 주제 기록의 네임스페이스 필드 값입니다.

    데이터 유형: 문자열

    cURL 요청

    다음 코드 예제에서는 이 끝점을 호출하는 방법을 보여 줍니다.

    curl "http://instance.servicenow.com/api/sn_api_notif_mgmt/topic" \
--request POST \
--header "Accept:application/json" \
--user 'username':'password'
--data
{
  "name": "HighPriorityTroubleTicket",
  "headerQuery": "eventType=TroubleTicketStatusChangeEvent,TroubleTicketAttributeChangeEvent",
  "contentQuery": "troubleTicket.ticketType=incident&troubleTicket.severity=1",
  "externalId": "ext001",
  "namespace": "telecomEvents"
}

    응답:

    
{
  "externalId": "ext001",
  "name": "HighPriorityTroubleTicket",
  "headerQuery": "eventType=TroubleTicketStatusChangeEvent,TroubleTicketAttributeChangeEvent",
  "contentQuery": "troubleTicket.ticketType=incident&troubleTicket.severity=1",
  "namespace": "telecomEvents",
  "id": "7ee9850443c3f550461f99612bb8f223"
}