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

  • リリースバージョン: Australia
  • 更新日 2026年03月12日
  • 所要時間：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. 要求本文のパラメーター
    名前 説明
    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 など
    • OR:variable1=value1,value2,value3 など
    • 階層変数:variable1.variable2.variable3=value1 など

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

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

    詳細については、「 TMF688 Event Management API ユーザーガイド」を参照してください。

    データタイプ：文字列
    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 ユーザーガイド」を参照してください。

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

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

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

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

    データタイプ：文字列

    ヘッダー

    次の要求ヘッダーと応答ヘッダーは、この 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 内部サーバーエラー要求の処理中に予期しないエラーが発生しました。応答には、エラーに関する追加情報が含まれています。

    応答本文のパラメーター

    名前 説明
    contentQuery 作成されたトピックレコードのcontent_queryフィールドの値。

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

    データタイプ：文字列
    ヘッダークエリ 作成されたトピックレコードのheader_queryフィールドの値。このフィールドは、トピックに送信するイベントメッセージを決定するためにトピックピッカーフレームワークによって使用されます。

    データタイプ：文字列
    ID 作成されたトピックレコードのSys_id。

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

    データタイプ：文字列
    名前空間 作成されたトピックレコードの [名前空間] フィールドの値。

    データタイプ：文字列

    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"
}