Webhook仕様
Webhookとは、イベントが発生した際に外部サービスへHTTP通信で通知する仕組みです。
AppSuiteでは自動処理によってデータの追加・変更時にWebhookを実行できます。
リクエスト
リクエストのコンテンツタイプ
application/json
リクエストボディ
追加・変更されたデータやアプリケーションの情報を送信します。
| キー |
値 |
説明 |
| app_id |
[アプリケーションID] |
アプリケーションのIDです。 |
| data_id |
[データID] |
追加・変更されたデータのデータIDです。 |
| data |
[データ] |
追加・変更されたデータ1件の内容です。
データ参照APIのレスポンスのrecordキー以下と同様の形式。
（詳しくは、 AppSuite API仕様＞データ参照API をご覧ください。）
※データ情報JSONは、データ参照APIのレスポンスと異なりアクセス権設定の影響を受けません。
- データを追加・変更したユーザーが参照権を持たない部品の値も送信されます。
- データを追加・変更したユーザーが参照権を持たないアプリケーションに対する参照部品の値も送信されます。
- \permissionsキーは送信されません。
- deny_writeキーは送信されません。
※[アプリケーション設定＞オプション機能＞API設定]で「部品識別子でデータの取得、設定を行う」設定をしている場合でも、データは部品名で送信されます。
|
| type |
[added | updated] |
自動処理を呼び出した操作です。
データの追加の場合はadded、データの変更の場合はupdated。
|
| app_name |
[アプリケーション名] |
アプリケーションの名前です。 |
| action_name |
[データの追加・変更時の処理のタイトル] |
自動処理設定で設定されたタイトルです。 |
| access_token |
[アクセストークン] |
自動処理設定で設定されたアクセストークンの値です。
未設定の場合は空の値が送られます。
|
| url |
[詳細画面のURL] |
dataキー以下のデータを既定の詳細画面で表示するURLです。
|
| external_url |
[詳細画面のURL（社外からアクセス用）]
|
dataキー以下のデータを既定の詳細画面で表示するURLです。
※URLは、 [管理者設定＞URL設定] のアクセスURL(外部)を使用して作成されます。
※アクセスURL(外部)が未設定の場合、空の値が送られます。
|
送信内容(リクエストボディ)の例
{
"app_id": "59",
"data_id": "141",
"data": {
"revision": {
"val": "5"
},
"データID": {
"val": "141"
},
"登録日時": {
"val": "2023-12-18T16:44:48"
},
"登録者": {
"val": {
"users": {
"item": [
{
"id": "15",
"Name": "前田隆",
...
}
]
}
}
},
"更新日時": {
"val": "2023-12-19T13:42:48"
},
"更新者": {
"val": {
"users": {
"item": [
{
"id": "34",
"Name": "佐々木光",
...
}
]
}
}
},
"備品名": {
"val": "キーボード"
},
"出庫数": {
"val": "2"
},
"在庫数" {
"val": "12",
"type": "number"
}
},
"type": "updated",
"app_name": "備品アプリ",
"action_name": "備品情報変更",
"access_token": "so84TkMOI470j127MA1Gp6PhIhNv+0SgS5508f8/SHo",
"url": "https://192.168.1.1/cgi-bin/dneo/appsuite.exe?cmd=cdbbrowse&app_id=59#view_id=4&id=141",
"external_url": "https://local.yourdomain/cgi-bin/dneo/appsuite.exe?cmd=cdbbrowse&app_id=59#view_id=4&id=141"
}
エラーについて
Webhookでエラーが発生した場合、[アプリケーション設定＞運用管理＞エラーログ]にエラー情報が保存されます。
通知先での処理失敗など独自のエラーメッセージを残したい場合は、後述のレスポンスを返してください。
エラーが保存される例
- URL、通知先のサーバー、ネットワークに問題があり、リクエストの送信に失敗した場合
- レスポンスが30秒以上返ってこない場合
- レスポンスのHTTPステータスコードが「200」以外の場合
-
レスポンスのHTTPステータスコードが「200」で、以下のようなJSON形式のレスポンスが返された場合
| キー |
値 |
説明 |
| result |
ng |
固定値
|
| error_message |
[エラーメッセージ] |
この文字列がエラーログに保存されます。 |
レスポンス内容の例
{
"result": "ng",
"error_message": "更新データのステータスが不正なため処理を中断しました。"
}
注意事項
Webhookの通知先プログラムからAppSuiteのAPIを使用して同じアプリケーションのデータを追加・変更すると、再び自動処理によってWebhookが実行されることで処理が無限に循環してしまう場合があります。
無限ループはサーバーの負荷となり、desknet's NEOの運用に問題を引き起こす可能性があります。
このような問題の防止策、発生してしまった際の対処方法をご案内します。
事前の防止策
-
通知先プログラムでデータ追加APIまたは変更APIを使用する際は、パラメーターauto_action=offを指定する。
APIを使用してデータ追加・変更時に自動処理が実行されなくなる指定です。
（詳しくは、 AppSuite API仕様＞データ追加API をご覧ください。）
-
自動処理設定でWebhookが実行される条件を調整する。
設定されている他の自動処理の実行が必要などパラメーターauto_action=offを指定できない場合は、自動処理設定の「処理を行うタイミング」「処理対象の絞り込み」を設定することで無限ループになってしまわないように調整してください。
問題のアプリケーションを特定するための調査方法
どのアプリケーションの自動処理設定が無限ループを引き起こしてしまっているかわからない場合、[管理者設定＞ログ＞アクセスログ検索]の機能を利用して、APIで繰り返しデータ追加・変更が行われているアプリケーションを探します。
※アクセスログの機能を利用するには、desknet's NEOのスケジューラーが起動している必要があります。
-
[管理者設定＞ログ＞アクセスログ設定]で「作成・追加/変更/削除の実行ログ」を「保存する」に設定します。
※設定変更後10分程度待ちます。（アクセスログは10分間隔で収集されるため）
-
[管理者設定＞ログ＞アクセスログ検索]でアクセスログを検索します。
AppSuite以外のログが含まれないように「処理」や「機能」を絞り込みます。
-
検索結果が表示されたら、[ダウンロード]ボタンからCSVファイルをダウンロードし内容を確認します。
- 「機能詳細」列の値が「insert_data」または「update_data」
- 「テーブル名他」列の値が「t000000000」（"t"の後に9桁の数字）
の両方を満たす行が、APIを使用してAppSuiteのデータを追加/変更したことを示すログになります。
同じテーブル名に対して大量の追加/変更ログが繰り返し残されている場合、無限ループの疑いがあります。
-
「テーブル名他」列の値（"t"の後に9桁の数字）から対象のアプリケーションIDを求めます。
テーブル名から先頭の"t"を取り除き、数字部分の下位3桁を取り除いた残りがアプリケーションIDになります。
（例：「t000571000」の場合「571」）
-
以下のURLを直接ブラウザに入力し、対象のアプリケーション管理画面にアクセスします。
※システム管理者、またはAppSuiteの機能管理者でログインして作業してください。
・desknet's NEOのURL：https://local.yourdomain/cgi-bin/dneo/dneo.cgi
・アプリケーションID：571
の場合のURL例
https://local.yourdomain/cgi-bin/dneo/appsuite.cgi?cmd=cdbmsetappmanage&app_id=571
メニューより[自動処理＞データの追加・変更時の処理]を開き、処理タイプが「Webhook」の設定があるようなら無限ループの原因になっている可能性があります。
設定内容を確認してください。
Copyright (C) NEOJAPAN Inc. All Rights Reserved.
