Webhookフィールドの設定: メソッド、リソース、ペイロード

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

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

• メソッド

• リソース

• ペイロード

以下のセクションでは、サードパーティツール上でのアクション実行のための属性設定について説明します。

メソッドの選択

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

1. メソッド ドロップダウンから POST、PUT、または PATCH のいずれかを選択してください。 以下の表を参照してください。

2. オプションとして、各メソッドの意味を明確に把握するために、関連するサードパーティソフトウェアのドキュメントを確認してください。

   • すべての販売者とサードパーティツールプロバイダーがすべてのメソッドを同様に使用するとは限りません。

REST標準はHTTP上で使用され、ウェブフック用リクエストメソッドを提供し、標準インターフェース制約の主要部分を構成します。

HTTPメソッド	CRUD*	説明
POST	作成	POSTは、新しいリソースを作成するために最も頻繁に利用されます。
PUT	更新/置換	PUTはその更新機能のために最も頻繁に使用されます。 既知のリソースURIにPUTし、リクエストボディに元のリソースの更新された表現を含めることができます。
PATCH	更新/修正	PATCHは修正機能のために使用されます。 PATCHリクエストには、リソースの変更すべき部分だけを含めればよく、完全なリソースを必ずしも含める必要はありません。

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

リソースフィールドの入力

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

• リソースはエンドポイントを通じてアクセス可能なデータセットで、APIと共に使用されます。

• リソースは他のリソースと関連し、実行可能な操作に制限があります。

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

• リソースには簡単な名前が付けられ、ユーザーが正しいエンドポイントを見つけやすくなっています。 しかし、これにより重要な機能を見逃す可能性があります。

ウェブフック設定 ページから Resource 値を追加するには:

1. 指定されたサードパーティREST APIのアクションである リソース 値を貼り付けます。

   • URIは追加しないでください。それはウェブフック資格情報に定義された インスタンスURL に連結されます。

   • リソース 値には、サードパーティツールが要求するパラメータ (key=value) を含めることができます。

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

有効なリソース値の例

ベンダーAPI URL	Webhook内のリソース値
https://webhook.atlassian.net/rest/servicedeskapi/request	rest/servicedeskapi/request
https://api.4me.com/v1/requests	v1/requests
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_=

ペイロードの作成

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

Webhook設定 ページから ペイロード 値を記述するには:

1. APIをリクエストする際にサーバーに送信する重要な情報をペイロードに含めてください。

   • オプションとして、ペイロードは、Webhookで使用しているツールに依存する関連サードパーティフィールドと値を確認してください。

2. 必要に応じて、ペイロード内のプレースホルダーとしてのNexthinkデータモデル変数 {{variable_name}} を使用してください。

   • Webhook NQL条件 の入力後、システムはNexthink Webインターフェースで 許可されたプレースホルダー を表示します。

3. このページに掲載されている 複数のプロバイダーからのメソッド、リソース、ペイロードの例 を参考にしてください。

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

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

Nexthinkからサードパーティツールにデータをプッシュする大きな利点の一つは、発生したイベントに関する情報を渡すことができるという点です。

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

1. ペイロードに報告される任意のフィールド内で {{variable_name}} プレースホルダーを使用してNexthink変数を参照してください。

2. Webhook NQL条件 の入力後、Nexthink Webインターフェースで 許可されたプレースホルダー が表示されます。

   • ペイロードのプレースホルダーは、Nexthink変数を埋め込む Webhook NQL条件 と整合する必要があります。

3. さらに、プレースホルダーとして利用可能なNexthink変数を確認するには、NQLデータモデルを検討してください。

   • なお、NQLデータモデルは、namespace > table > field で組織されています。

   • 例えば、プレースホルダー {{alert.monitor.name}} は、alerts namespace 内の monitor テーブルの name フィールドを含むものです。 詳細については、データの組織ドキュメントを参照してください。

4. サードパーティツールで生成される出力を読みやすくユーザーフレンドリーにするために、プレースホルダーに 'as(format = text)' を追加してください。 例えば、 {{remote_action.execution.outputs.as(format = text)}} 。

5. 必要に応じて、NQLデータモデルで厳密には定義されていない特別なプレースホルダーを使用してください。これらはこのページで説明されており、Nexthink Webインターフェースの 許可されたプレースホルダー にも参照されています。

• アラートデータモデル変数用特別プレースホルダー

• リモートアクションデータモデル変数用特別プレースホルダー

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

システムは、空の値や無効な値と置き換えることはできません。 この場合、{{variable_name}}がそのまま表現されます。

アラートデータモデル変数用特別プレースホルダー

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

NQLデータモデルのプロパティ	特別プレースホルダー
alert.monitor.thresholds	各配列アイテムには エイリアス (メトリクス名) と対応する 値 があります: {{alert.monitor.thresholds[n].alias}} {{alert.monitor.thresholds[n].values}} [n] の値を整数に置き換えます。 モニターで定義されたメトリックしきい値の数に依存します: • [0] の値は常に利用可能です。 • [1] 以上の値はオプションです。
alert.trigger_values	各配列アイテムには エイリアス (メトリクス名) と対応する 値 があります: {{alert.alert.trigger_values[n].alias}} {{alert.alert.trigger_values[n].value}} [n] の値を整数に置き換えます: [0] 、[1] など。
alert.trigger_reference_value	{{alert.alert.trigger_reference_value}} 組み込みモニターのカスタマイズドキュメンテーションのタイプセクションのメトリックの変更アイテムを参照して、参照値計算に関する詳細を学びましょう。
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}} *contextフィールドは、 モニターNQLクエリと条件で定義されたデータモデルプロパティのみを含みます。 したがって、contextフィールドは、アラートに関連するバイナリ、デバイス、またはユーザーの名前を含む可能性があります。
alert.alert.issue_view_link alert.alert.device_view_link alert.alerts.links これらのプロパティは現在、NQLデータモデルにはリストされていません。	alert.alert.issue_view_linkは、アラートに関連するトラブルシューティングダッシュボードへのリンクを提供します。 ウェブフックのNQL条件で issue_view_link フィールドを リスト 条件に追加する必要があります。 alert.alert.device_view_linkは、デバイスビューへのリンクを提供します。 ウェブフックの NQL 条件 で device_view_link フィールドを リスト 条件に追加する必要があります。 アラート設定に応じて、プレースホルダー alert.alerts.links は、アラートに関連するDevice view またはトラブルシューティングダッシュボードへのリンクを提供します。 この場合、ウェブフック NQL条件 の リスト 条件に device_view_link および issue_view_link を追加する必要があります。

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

この表には、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}} このプレースホルダーは、リモートアクションを実行したユーザー/従業員を提供します。

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

複数のサードパーティツールのフルウェブフック設定については、Webhookのユースケースセットアップドキュメントを参照してください。

ITSM ツール

ServiceNowに対するインシデントの作成

メソッド: POST

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

ペイロード:

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

こちらのガイドラインを参照して、アラートやイベントを検出し、それをServiceNowに送信してインシデントを作成するWebhooksを設定してください。

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

メソッド: PATCH

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

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

{"work_notes": "Amplifyユーザー{{remote_action.execution.account_name}}が{{remote_action.execution.request_time}}にこのチケットのリモートアクション{{remote_action.execution.outputs.as(format = text)}}をトリガーした。"}

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

こちらのガイドラインを参照して、AmplifyからServiceNow実行アクションログを更新するWebhooksを設定してください。

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":"incident",
"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": "high",
 "summary": null,
 "type": "priority_reference",
 "self": null,
 "html_url": null
    },
 "urgency": "高い",
 "body": {
 "type": "incident_body",
 "details": "文字列"
    },
 "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": "文字列",
 "conference_url": "文字列"
    }
  }
}

メッセージングツール

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": "emphasis"
        },
{
                        "type": "FactSet",
                        "facts": [
                            {
                                "title": "Assigned to",
                                "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 リソースは、Zoom 内で直接設定されたエンドポイント URL にのみ依存しているため、参考用です。

ペイロード: 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":"パフォーマンスログ",
 "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": "テスト",
 "path": "/dev/sda1",
 "fstype": "ext3"
  }
}