ウェブフックフィールドの設定: メソッド、リソース、およびペイロード

Webhookを設定する主な利点は、Nexthinkのアラートやイベントからのデータを、宛先に応じて様々なサードパーティツールにプッシュできることです。

Webhook設定ページでは、宛先のサードパーティツールでアクションを実行するために重要な3つのフィールドがあります。

  • 方法

  • リソース

  • ペイロード

以下のセクションでは、サードパーティツールでアクションを実行するための属性の設定方法を説明します。

方法の選択

Webhook設定ページから、資格情報を選択した後:

  1. 方法のドロップダウンからPOSTPUTまたはPATCHのいずれかを選択します。 以下の表を参照してください。

  2. オプションで、各メソッドの意味を明確に識別するために適切なサードパーティソフトウェアのドキュメントを確認します。

  • 全てのベンダーやサードパーティツールのプロバイダーが同じようにメソッドを使用しているわけではないと想定してください。

HTTP上でのREST標準が用いられ、統一インターフェース制約の大部分を構成し、Webhookで利用可能なリクエストメソッドを提供します。

HTTPメソッド
CRUD*
説明

POST

作成

POSTは新しいリソースを作成するために最も頻繁に使用されます。

PUT

更新/置換

PUTはその更新機能のために最も頻繁に使用されます。 既知のリソースURIにPUTすると、リクエスト本文に元のリソースの新しく更新された表現が含まれます。

PATCH

更新/修正

PATCHは修正機能のために使用されます。 PATCHリクエストには、リソース全体ではなく、そのリソースへの変更だけを含める必要があります。

*_CRUD_は、作成、読み取り、更新、削除の頭字語です。

Resourceフィールドの入力

リソースに関する特別な考慮事項:

  • リソースは、APIと一緒に使用できるエンドポイントを介してアクセスできるデータセットです。

  • リソースは他のリソースに関連し、それに対して実行できる操作によって制限されます。

  • リソースは、関連するデータや操作可能なオブジェクトに基づいてエンドポイントグループとして提示されます。

  • リソースには簡単な名前が付けられており、ユーザーが適切なエンドポイントを簡単に見つけることができます。 ただし、これにより重要な機能が見落とされることがあります。

Webhook configuration ページから Resource 値を追加するには:

  1. 第三者のREST APIによって指定されるアクションである、Resource 値を貼付けます。

  • URIを追加してはいけません。URIはWebhookのcredentialsで定義されたインスタンスURLに結合されます。

  • Resource 値には、第三者ツールが必要とするパラメーター (key=value) を含めることができます。

  1. 必要に応じて、プレースホルダー {{variable_name}}Resource に追加します。 このページの ペイロードにNexthinkデータモデル変数をプレースホルダーとして使用する セクションを参照してください。

有効なResource値の例

ベンダーAPI URL
Webhookにおけるリソース値

rest/servicedeskapi/request

https://fra1.qualtrics.com/API/v3/users

API/v3/users

https://ven01063.service-now.com/api/now/v1/table/incident

api/now/v1/table/incident

https://api.4me.com/v1/requests?api\_\=

v1/requests?api_<token>=

ペイロードの作成

ペイロードは、HTTPのPOST/PUT/PATCHメソッドで送信されるデータパックです。

ウェブフック設定ページから ペイロード 値を記述するには:

  1. サーバーにAPIを要求する際に送信する重要な情報を ペイロード に含めます。

  • 必要に応じて、使用するウェブフックツールに依存するため、関連する第三者のフィールドと値を確認します。

  1. 必要に応じて、Nexthinkデータモデル変数をプレースホルダーとして使用して、{{variable_name}}ペイロード 内に組み込みます。

  • Webhook NQL条件 の記入後、便利なNexthinkウェブインターフェースで 許可されたプレースホルダー を一覧表示します。

  1. このページに載っている 各プロバイダーからのメソッド、リソース、およびペイロードの例 を参考にしてください。

ペイロード フィールドはJSON形式のみを受け入れます。

ペイロード内でNexthinkデータモデル変数をプレースホルダーとして使用する

Nexthinkからのデータを第三者ツールにプッシュすることで情報を渡すことができるのは、発生したイベントについての情報を渡す能力が最大の利点の一つです。

ペイロード内でNexthinkデータモデル変数をプレースホルダーとして使用するには:

  1. ペイロードで報告されるフィールド内のプレースホルダーとして、Nexthink変数を {{variable_name}} を使用して参照します。

  2. ウェブフック NQL条件を記入後、Nexthinkウェブインターフェースで 許可されたプレースホルダー を一覧表示します。

  • ペイロード内のプレースホルダーは、Nexthink変数を生成する ウェブフックのNQL条件 と整合している必要があります。

  1. また、NQLデータモデル を確認して、プレースホルダーで利用可能なNexthink変数を特定します。

  • NQLデータモデルは、namespace > table > fieldによって組織化されていることを忘れないでください。

  • 例えば、プレースホルダー {{alert.monitor.name}} には、 alerts namespace内の monitorテーブルから name フィールドが含まれています。 Data organization ドキュメントをご覧ください。」

  1. 出力が第三者ツールで生成されたときに読みやすくユーザーフレンドリーであることを確保するために、プレースホルダーに as(format = text) を追加します。 例えば、 {{remote_action.execution.outputs.as(format = text)}}

  2. 特にNQLデータモデルで厳密に定義されていない特別なプレースホルダーを必要に応じて使用することができます。本ページに含まれており、Nexthinkウェブインターフェースの 許可されたプレースホルダー にも参照されています。

以下の画像は、Nexthinkデータモデル変数を参照するプレースホルダーを持つペイロードの例です。 このケースの 許可されたプレースホルダー をシステムがどのようにリストするかに注意してください。

Allowed placeholders from the webhook configuration page.

システムは空白値や無効なプレースホルダーを置き換えることができません。 その場合、{{variable_name}} がそのまま表示されます。

警告データモデル変数のための特別なプレースホルダー

この表には、NQLデータプロパティで厳密に定義されていない警告のための特別なプレースホルダーが含まれています。

NQLデータモデルのプロパティ
特別なプレースホルダー

alert.monitor.thresholds

各配列項目には、alias(メトリック名)と対応するvalueがあります:

{{alert.monitor.thresholds[n].alias}}

{{alert.monitor.thresholds[n].values}}

[n] 値を整数で置き換えます。 モニターで定義されたメトリックしきい値 の数に応じて、[n] 値の数が決まります。

[0] 値は常に使用可能です。

[1] 以上の値はオプションです。

alert.trigger_values

各配列項目には、alias(メトリック名)と対応するvalueがあります:

{{alert.alert.trigger_values[n].alias}}

{{alert.alert.trigger_values[n].value}}

[n] 値を整数で置き換えます: [0] , [1], etc.

alert.trigger_reference_value

{{alert.alert.trigger_reference_value}}

を参照して、reference_value 計算について詳しく学ぶために、タイプセクションの Metric change 項目をご確認ください。

alert.context

{{alert.alert.context}}

{{alert.alert.context.<property name>}}

{{alert.alert.context.<property name>.label}}

{{alert.alert.context.<property name>.data_path}}

{{alert.alert.context.<property name>.data_type}}

以下例示します*:

{{alert.alert.context.binary.name}}

{{alert.alert.context.binary.name.label}}

{{alert.alert.context.binary.name.data_path}}

{{alert.alert.context.binary.name.data_type}}

*モニタNQLクエリと条件で定義されたデータモデルプロパティのみが contextフィールドに含まれます。

したがって、context フィールドには、警告に関連するバイナリ、デバイスまたはユーザーの名前が含まれている場合があります。

alert.alert.issue_view_link

alert.alert.device_view_link

alert.alerts.links

これらのプロパティは現在NQLデータモデルにリストされていません。

alert.alert.issue_view_link は、警告に関連するトラブルシューティングダッシュボードへのリンクを提供します。 追加してください issue_view_linkフィールドをWebhookのNQL条件リスト句に。

alert.alert.device_view_link 提供されるリンクはデバイスビューへのリンクです。 追加してください device_view_linkフィールドをWebhookの NQL条件リスト句に。

警告設定に応じて、alert.alerts.links プレースホルダーは、デバイスビューまたはトラブルシューティングダッシュボードへのリンクを提供します。 この場合、両方のdevice_view_linkissue_view_linkフィールドをWebhookのNQL条件リスト句に追加する必要があります。

リモートアクションデータモデル変数のための特別なプレースホルダー

この表には、NQLデータプロパティで厳密に定義されていないリモートアクションのための特別なプレースホルダーが含まれています。

NQLデータモデルのプロパティ
特別なプレースホルダー

remote_action.execution.outputs

{{remote_action.execution.outputs.<property name>}}

例:

{{remote_action.execution.outputs.MeteredConnection}}

remote_action.execution.inputs

{{remote_action.execution.inputs.<property name>}}

例:

{{remote_action.execution.inputs.InputPath}}

remote_action.execution.account_name

このプロパティは現在NQLデータモデルでリストされていません。

{{remote_action.execution.account_name}}

このプレースホルダーは、リモートアクションを実行したユーザー/従業員を提供します。

複数のプロバイダーやツールからのメソッド、リソースおよびペイロードの例

ウェブフックユースケースのセットアップ ドキュメントを参照してください。複数の第三者ツールのための完全なウェブフック設定があります。

ITSMツール

ServiceNowのためのインシデントの作成

メソッド: POST

リソース: api/now/v1/table/incident

ペイロード:

{
 "assignment_group":"アプリケーションチーム",
 "business_service":"MS Teams",
 "caller_id":"Nexthink Alert",
 "description":"Alertsチームから作成されたアラート。",
 "impact":"5",
 "short_description":"テスト目的のアラート David G {{alert.monitor.name}}",
 "sys_created_by":"Nexthink Integration test David G.",
 "urgency":4
}

このガイドライン に従って、インシデントを作成するために、ServiceNowにアラートやイベントを送信するためのウェブフックを設定します。

AmplifyからServiceNowのインシデントチケットを更新する

メソッド: PATCH

リソース: api/now/v1/table/incident/{{remote_action.execution.external_reference}}

ペイロード (メッセージ):

{"work_notes": "リモートアクション {{remote_action.execution.outputs.as(format = text)}} は、Amplifyユーザー {{remote_action.execution.account_name}} によって {{remote_action.execution.request_time}} にこのチケットでトリガーされました。"}

リモートアクションの出力を読みやすい形式で表示するために、"work_notes"as(format = text) 関数を含めます。

このガイドライン に従って、AmplifyからServiceNowの実行ログを更新するためのウェブフックを設定します。

ServiceNowのための問題の作成

メソッド: POST

リソース: api/now/v1/table/problem

ペイロード:

{
 "impact":"1",
 "urgency":"2",
 "category":"ハードウェア",
 "short_description":"アラート: {{alert.monitor.name}} がNexthinkにより発生",
 "description":"アラート {{alert.monitor.name}} は{{alert.monitor.time}}にNexthinkにより自動的に発生しました。アラートをトリガーしたNQLクエリは次です: https://tinyurl.com/29k9xy8d",
 "assignment_group":"アプリケーションチーム",
 "business_service":"MS Teams",
}

BMCのインシデント作成

方法: POST

リソース: api/arsys/v1/entry/HPD:IncidentInterface_Create?fields=values(Incident Number , Request ID, First_Name)

ペイロード:

{
 "values": {
 "First_Name": "Allen",
 "Last_Name": "Allbrook",
 "Description": "REST API: Nexthinkのアラート {{alert.monitor.name}} がトリガーされました",
 "Impact": "1-広範/深刻",
 "Urgency": "1-クリティカル",
 "Status": "割り当て済み",
 "Reported Source": "直接入力",
 "Service_Type": "ユーザーサービスの復元" 
 }
}

4meでのインシデント作成

方法: POST

リソース: v1/requests

ペイロード:

{
"category":"インシデント",
"subject":"このアラート {{alert.monitor.name}} によって引き起こされた結果です",
"impact":"低",
"service_instance_id":"147488",
"ci":"21819154",
"ci_id":"21819154",
"note":"アラートは{{alert.alert.trigger_time}}に次の値でトリガーされました: {{alert.alerts.trigger_values[0].alias}}: {{alert.alerts.trigger_values[0].value}}, {{alert.alerts.trigger_values[1].alias}}: {{alert.alerts.trigger_values[1].value}}"
}

Jira Service Deskでのサービスリクエスト作成

方法: POST

リソース: rest/servicedeskapi/request

ペイロード:

{
 "serviceDeskId": "1",
 "requestTypeId": "5",
 "requestFieldValues": {
 "summary": "REST経由でJSDヘルプを依頼",
 "description": "Mac用の新しい*マウス*が必要です"
  }
}

アラート ツール

Pager Dutyでのインシデント作成

方法: POST

リソース: incidents

ペイロード:

{
 "incident": {
 "type": "incident",
 "title": "apiインシデントによるNexthinkアラート {{alert.monitor.name}}",
 "service": {
 "id": "PXZF637",
 "summary": null,
 "type": "service_reference",
 "self": null,
 "html_url": null
    },
 "priority": {
 "id": "高",
 "summary": null,
 "type": "priority_reference",
 "self": null,
 "html_url": null
    },
 "urgency": "高",
 "body": {
 "type": "incident_body",
 "details": "string"
    },
 "incident_key": "incident_{{alert.alert.trigger_time}}",
 "escalation_policy": {
 "id": "P14MFQ2",
 "summary": null,
 "type": "escalation_policy_reference",
 "self": null,
 "html_url": null
    },
 "conference_bridge": {
 "conference_number": "string",
 "conference_url": "string"
    }
  }
}

メッセージングツール

MS Teamsチャネルへのメッセージ投稿

方法: POST

リソース: /workflows/XXXXXXXXXXXXXXXXXXX/triggers/manual/paths/invoke?api-version=?????&sp=/triggers/manual/run&sv=1.0&sig=XXXXXXXXXXXXXXX

ペイロード:

{
    "type": "message",
    "attachments": [
        {
            "contentType": "application/vnd.microsoft.card.adaptive",
            "content": {
                "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
                "type": "AdaptiveCard",
                "version": "1.0",
"msteams": {  
        "width": "Full"  
    },  
                "body": [
                    {
                        "type": "TextBlock",
                        "text": "Nexthink アラート",
                        "id": "Title",
                        "spacing": "Medium",
                        "horizontalAlignment": "Center",
                        "size": "ExtraLarge",
                        "weight": "Bolder",
                        "color": "Accent"
                    },
                    
                    {
            "type": "Container",
            "items": [
                {
                    "type": "TextBlock",
                    "text": "{{alert.alert.context.application.name}},{{alert.monitor.name}}",
                    "wrap": true,
                     "color": "Default",
                    "size": "Medium"
                }
            ],
            "style": "強調"
        },
{
                        "type": "FactSet",
                        "facts": [
                            {
                                "title": "担当者",
                                "value": "インフラストラクチャチーム"
                            }, {
                               "title": "トリガーされた日時: ",
                               "value": "{{alert.alert.trigger_time}}"
                           },  {
                               "title": "アプリケーション名",
                               "value": "{{alert.alert.context.application.name}}"
                           },

           ]
        },


                     {
            "type": "TextBlock",
            "text": "違反条件:",
            "wrap": true
        },
        {
            "type": "Table",
            "columns": [
                {
                    "width": 1
                },
                {
                    "width": 1
                },
                {
                    "width": 1
                },
                {
                    "width": 1
                }
            ],
            "rows": [
                {
                    "type": "TableRow",
                    "cells": [
                        {
                            "type": "TableCell",
                            "items": [
                                {
                                    "type": "TextBlock",
                                    "text": "メトリック名",
                                    "wrap": true
                                }
                            ]
                        },
                        {
                            "type": "TableCell",
                            "items": [
                                {
                                    "type": "TextBlock",
                                    "text": "しきい値",
                                    "wrap": true
                                }
                            ]
                        },
                        {
                            "type": "TableCell",
                            "items": [
                                {
                                    "type": "TextBlock",
                                    "text": "メトリック値",
                                    "wrap": true
                                }
                            ]
                        },
                        {
                            "type": "TableCell",
                            "items": [
                                {
                                    "type": "TextBlock",
                                    "text": "ベースライン値",
                                    "wrap": true
                                }
                            ]
                        }
                    ]
                },
                {
                    "type": "TableRow",
                    "cells": [
                        {
                            "type": "TableCell",
                            "items": [
                                {
                                    "type": "TextBlock",
                                    "text": "{{alert.alert.trigger_values[0].alias}}",
                                    "wrap": true
                                }
                            ]
                        },
                        {
                            "type": "TableCell",
                            "items": [
                                {
                                    "type": "TextBlock",
                                    "text": "{{alert.monitor.thresholds[0].value}}",
                                    "wrap": true
                                }
                            ]
                        },
                        {
                            "type": "TableCell",
                            "items": [
                                {
                                    "type": "TextBlock",
                                    "text": "{{alert.alert.trigger_values[0].value}}",
                                    "wrap": true
                                }
                            ]
                        },
                        {
                            "type": "TableCell",
                            "items": [
                                {
                                    "type": "TextBlock",
                                    "text": "{{alert.alert.trigger_reference_value}}",
                                    "wrap": true
                                }
                            ]
                        }
                    ]
                },
                {
                    "type": "TableRow",
                    "cells": [
                        {
                            "type": "TableCell",
                            "items": [
                                {
                                    "type": "TextBlock",
                                    "text": "{{alert.alert.trigger_values[1].alias}}",
                                    "wrap": true
                                }
                            ]
                        },
                        {
                            "type": "TableCell",
                            "items": [
                                {
                                    "type": "TextBlock",
                                    "text": "{{alert.monitor.thresholds[1].value}}",
                                    "wrap": true
                                }
                            ]
                        },
                        {
                            "type": "TableCell",
                            "items": [
                                {
                                    "type": "TextBlock",
                                    "text": "{{alert.alert.trigger_values[1].value}}",
                                    "wrap": true
                                }
                            ]
                        },
                        {
                            "type": "TableCell",
                            "items": [
                                {
                                    "type": "TextBlock",
                                    "text": "",
                                    "wrap": true
                                }
                            ]
                        }
                    ]
                },
                {
                    "type": "TableRow",
                    "cells": [
                        {
                            "type": "TableCell",
                            "items": [
                                {
                                    "type": "TextBlock",
                                    "text": "",
                                    "wrap": true
                                }
                            ]
                        },
                        {
                            "type": "TableCell",
                            "items": [
                                {
                                    "type": "TextBlock",
                                    "text": "",
                                    "wrap": true
                                }
                            ]
                        },
                        {
                            "type": "TableCell",
                            "items": [
                                {
                                    "type": "TextBlock",
                                    "text": "",
                                    "wrap": true
                                }
                            ]
                        },
                        {
                            "type": "TableCell",
                            "items": [
                                {
                                    "type": "TextBlock",
                                    "text": "",
                                    "wrap": true
                                }
                            ]
                        }
                    ]
                }
            ], "showGridLines": false
        },
        {
            "type": "ActionSet",
            "actions": [
                {
                    "type": "Action.OpenUrl",
                    "title": "Nexthinkで表示",
                    "URL": "{{alert.alert.issue_view_link}}"
                }
            ]
        }
                ] 
            }
        }
    ]
}

このガイドラインに従って、MS Teamsに着信要求を受信するように設定します。

Slackの特定のチャネルへのメッセージ投稿

方法: POST

リソース: services/T01S01V0HB3/B02GY9BKZ7G/DIDFWXuCAeFfqkgNntQqJV7e

ペイロード:

{
 "channel":"C01R6KV8CA3",
 "text":"デジタル体験に影響を与えるアラート{{alert.monitor.name}}があります",
 "attachments":[
        {
 "text":"誰が確認すべきか?",
 "fallback":"コンピューターには、チョコレートの永年供給ができることを伝えてもらわなければなりません。",
 "color":"#3AA3E3",
 "attachment_type":"default",
 "callback_id":"select_simple_1234",
 "actions":[
             {"name":"winners_list",
 "text":"アラートを誰が処理するべきですか?",
 "type":"select",
 "data_source":"users"
              }
            ]
        }
    ]
}

このガイドラインに従って、Slackに着信要求を受信するように設定します。

Zoomへのメッセージ投稿

方法: POST

リソース: chat/webhooks/incomingwebhook/dSUcla-dQaGYgqGuBk3BsQ.

上記のURLリソースは例示的なものです。具体的な終点URLはZoomに直接設定します。

ペイロード: Zoomに送信するメッセージを追加してください。 以下の例をご覧ください。

[
{
"text":"入力メッセージ",
"img":["file1","file2"]
}
] 

このガイドラインに従って、Zoomに着信要求を受信するように設定します。

生産性ツール

Jiraの特定のプロジェクトでのバグ作成

方法: POST

リソース: services/T01S01V0HB3/B02GY9BKZ7G/DIDFWXuCAeFfqkgNntQqJV7e

ペイロード:

{
 "fields": {
 "project":
       {
 "key": "WHKBUG"
       },
 "summary": "ユーザーは悪い音声品質の通話を経験しています",
 "description": "Nexthink アラート {{alert.monitor.name}} がトリガーされました",
 "issuetype": {
 "name": "バグ"
        },
 "priority":{
 "name": "{{alert.alert.priority}}"
        },      
 "timetracking":
        {
 "originalEstimate": "1d 2h",
 "remainingEstimate": "3h 25m"
        }
    }
}

データ プラットフォーム

Splunkのイベントコレクターへのイベント送信

方法: POST

リソース: services/collector?index=_main

ペイロード:

{
 "event": "メトリック",
 "source": "メトリクス",
 "sourcetype":"perflog",
 "fields": {
 "event_name":"システム クラッシュ",
 "event_label":"{{device_performance.system_crash.label}}",
 "event_error_code":"{{device_performance.system_crash.error_code}}",
 "event_time":"{{device_performance.system_crash.time}}",
 "region": "us-west-1",
 "datacenter": "dc2",
 "rack": "63",
 "os": "Ubuntu16.10",
 "arch": "x64",
 "team": "LON",
 "service": "6",
 "service_version": "0",
 "service_environment": "test",
 "path": "/dev/sda1",
 "fstype": "ext3"
  }
}

Last updated

Was this helpful?