イベント管理トピックオープン API

  • リリースバージョン: Zurich
  • 更新日 2025年07月31日
  • 所要時間：8分

    • イベント管理トピックオープン 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/{api_version}/topic

    デフォルト URL: /api/sn_api_notif_mgmt/topic

    注:
    利用可能なバージョンは、 REST API エクスプローラーで指定されます。スクリプト済み REST API の場合、[ スクリプト済み REST サービス] フォームに追加のバージョン情報があります。

    サポートされている要求パラメーター

    表 : 1. パスパラメーター
    名前 説明
    api_version オプションアクセスするエンドポイントのバージョン。たとえば、v1 や v2 などです。最新以外のエンドポイントバージョンを使用する場合にのみ、この値を指定してください。

    データタイプ：文字列
    表 : 2. クエリパラメーター
    名前 説明
    なし
    表 : 3. 要求本文パラメーター
    名前 説明
    コンテンツのクエリ イベントのペイロードに適用するフィルター。このクエリは、イベントの重大度やチケットタイプなどの情報を検索するために使用されるより詳細なイベントフィルターです。このパラメーターは、ネストされたクエリーとして渡すことができます。
    たとえば、次のトラブルチケットイベントペイロードの場合、このクエリはペイロードの 「event」 オブジェクトにある属性に適用されます。
    {
  "eventId":"dc2003c2c3bb3550054e20bdc0013136",
  "@type":"Troubleticket",
  "eventType":"TroubleTicketCreateEvent",
  "event":{
    "troubleTicket":{
      "short_description":"Test payload",
      "severity":3,
      "ticketType":"incident"
    }
  }
}
    このパラメーターは、次の条件をサポートします。
    • AND: 例: variable1=value1&variable2=value2&variable3=value3
    • OR:variable1=value1,value2,value3 など
    • 階層変数:variable1.variable2.variable3=value1 など

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

    このフィールドは、関連するトピックレコードの content_query フィールドにマッピングされます。

    詳細については、『 TMF688 Event Management API User Guide』を参照してください。

    データタイプ：文字列
    externalId トピックの一意の外部識別子 (GUID など)。このフィールドは、関連するトピックレコードの topic_id フィールドにマッピングされます。

    データタイプ：文字列
    ヘッダークエリ イベントヘッダーのプロパティに適用するフィルター。このクエリーは、関連するトピックをリッスンするイベントのタイプを定義します。このパラメーターは、ネストされたクエリーとして渡すことができます。
    このパラメーターは、次の条件をサポートします。
    • AND: 例: variable1=value1&variable2=value2&variable3=value3
    • OR:variable1=value1,value2,value3 など
    • 階層変数:variable1.variable2.variable3=value1 など

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

    このフィールドは、関連するトピックレコードの header_query フィールドにマッピングされます。

    詳細については、『 TMF688 Event Management API User Guide』を参照してください。

    データタイプ：文字列
    名前 トピックの名前。

    このフィールドは、関連するトピックレコードの topic_name フィールドにマッピングされます。

    データタイプ：文字列
    名前空間 トピックの名前空間。関連付けられた名前空間がない場合は空です。

    このフィールドは、関連するトピックレコードの名前空間フィールドにマッピングされます。

    データタイプ：文字列

    ヘッダー

    次のリクエストや応答ヘッダーは、この HTTP アクションにのみ適用されるか、またはこのアクションに別個の方法で適用されます。REST API で使用される一般的なヘッダーのリストについては、「 サポートされている REST API ヘッダー」を参照してください。

    表 : 4. 要求ヘッダー
    ヘッダー 説明
    承認 応答本文のデータフォーマット。application/json のみをサポートします。
    Content-Type 要求本文のデータ形式。application/json のみをサポートします。
    表 : 5. 応答ヘッダー
    ヘッダー 説明
    なし

    ステータスコード

    この HTTP アクションには、次のステータスコードが適用されます。REST API で使用される可能性のあるステータスコードのリストについては、「 REST API HTTP 応答コード」を参照してください。

    表 : 6. ステータスコード
    ステータスコード 説明
    201 成功。要求が正常に処理されました。
    400 渡されたトピック外部 ID は既に存在します。一意のトピック外部 ID を渡してください:渡された外部 ID がトピックテーブルに既に存在することを示します。

    トピック名、ヘッダークエリ、コンテンツクエリ、名前空間の一意の組み合わせを渡してください :トピック名、名前空間、ヘッダークエリ、およびコンテンツクエリの組み合わせが既に存在することを示します。
    500 内部サーバーエラー。要求の処理中に予期しないエラーが発生しました。応答に、エラーに関する追加情報が含まれます。

    応答本文のパラメーター

    名前 説明
    コンテンツのクエリ 作成されたトピックレコード内のcontent_queryフィールドの値。

    データタイプ：文字列
    externalId 作成されたトピックレコード内のtopic_idフィールドの値。

    データタイプ：文字列
    ヘッダークエリ 作成されたトピックレコード内の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"
}