이벤트 관리 주제 개방형 API

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

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

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

    이 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/{api_version}/topic

    기본 URL: /api/sn_api_notif_mgmt/topic

    주:
    사용 가능한 버전은 REST API 탐색기에 지정됩니다. 스크립트 기반 REST API의 경우 스크립트 기반 REST 서비스 양식에 추가 버전 정보가 있습니다.

    지원되는 요청 매개변수

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

    데이터 유형: 문자열
    표 2. 쿼리 매개변수
    이름 설명
    안 함
    표 3. 요청 본문 매개변수
    이름 설명
    contentQuery 이벤트의 페이로드에 적용할 필터입니다. 이 쿼리는 이벤트 심각도 또는 티켓 유형과 같은 정보를 찾는 데 사용되는 심층 이벤트 필터입니다. 이 매개 변수를 중첩 쿼리로 전달할 수 있습니다.
    예를 들어, 다음 문제 티켓 이벤트 페이로드의 경우 이 쿼리는 페이로드의 "event" 객체에 있는 속성에 적용됩니다.
    {
  "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"
}