5.3.3.2. 使い方¶

インテグレーション機能（Webhook）（※以降、当機能）を利用するためには、他システムからのWebhookによるイベント連携を受け付けるエンドポイントを作成する必要があります。

以降で、受け付けたイベント内容から千手メッセージを発行するエンドポイントを作成する手順を示します。

5.3.3.2.1. はじめに¶

Webコンソールにサービスポリシー（インテグレーション）の有効化したユーザーでログインします。

サイドメニューから"設定変更"＞"共通設定"＞"インテグレーション"を選択すると、インテグレーション機能画面( 図 5.709 )が表示されます。

以降の手順は、この画面から各エンティティの一覧画面に遷移したうえで実施します。

../../_images/user_guide-webhook-usage-top.jpg — 図 5.709 インテグレーション機能画面¶

5.3.3.2.2. アクション定義¶

当機能で呼び出すSenju/DCのWeb APIを定義します。

アクション一覧画面の[Create New]をクリックして、アクション新規作成画面( 図 5.710 )に遷移します。

../../_images/user_guide-webhook-usage-action.jpg — 図 5.710 アクション新規作成画面¶

以下のように値を設定し、千手メッセージを発行するアクション定義を作成します。

項目	指定内容
WebAPI URI	`https://localhost/senju_iwas/v1/live/[千手ドメイン名]/functions/message`
WebAPI Method	`2` (POST)
WebAPI Token	本書 Senju/DCのAPIトークンの発行に記載の手順で発行したAPIトークン文字列

5.3.3.2.3. スクリプト定義¶

他システムから連携されたデータを"アクション"の入力とするための書式変換処理を定義します。

スクリプト一覧画面の[Create New]をクリックして、スクリプト新規作成画面( 図 5.711 )に遷移します。

../../_images/user_guide-webhook-usage-script.jpg — 図 5.711 スクリプト新規作成画面¶

以下のように値を設定し、千手メッセージを発行するスクリプト定義を作成します。

ScriptType 項目: Lua

Script 項目:

メッセージID/状態/内容を指定する場合

return {
  Code = SdcGetJsonPathValue("$.sample.Code"),
  Level = SdcGetJsonPathValue("$.sample.Level"),
  Message = SdcGetJsonPathValue("$.sample.Message")
}

メッセージID/状態/内容/ノードID/発信元プロセス名を指定する場合

return {
  Code = SdcGetJsonPathValue("$.sample.Code"),
  Level = SdcGetJsonPathValue("$.sample.Level"),
  Message = SdcGetJsonPathValue("$.sample.Message"),
  NodeId = SdcGetJsonPathValue("$.sample.NodeId"),
  ProcessName = SdcGetJsonPathValue("$.sample.ProcessName")
}

書式変換処理については、以下の組み込み関数を使用することができます。

SdcGetJsonPathValue
JSONのデータから、指定したJSONPathの値を取得できます。
SdcGetJsonPathToString
JSONのデータから、指定したJSONPathの値を文字列化して取得できます。

以降で各組み込み関数の使用例を示します。なお、記載の例は以下の入力JSONデータ例を前提としています。

使用例に用いる入力JSONデータ:

{
  "Number": 123.45,
  "Boolean": false,
  "String": "test messages",
  "Object": {"key":"value"},
  "Array": ["str", 12.3, null, true]
}

組み込み関数 SdcGetJsonPathValue の使用例は以下のとおりです。

スクリプト例:

return {
    FromNumber = SdcGetJsonPathValue("$.Number"),
    FromBoolean = SdcGetJsonPathValue("$.Boolean"),
    FromString = SdcGetJsonPathValue("$.String"),
    FromObject = SdcGetJsonPathValue("$.Object"),
    FromArray = SdcGetJsonPathValue("$.Array")
}

出力JSONデータ例:

{
  "FromNumber": 123.45,
  "FromBoolean": false,
  "FromString": "test messages"
  "FromObject": { "key": "value" },
  "FromArray": ["str", 12.3, null, true],
}

組み込み関数 SdcGetJsonPathToString の使用例は以下のとおりです。

スクリプト例:

return {
    FromNumber = SdcGetJsonPathToString("$.Number"),
    FromBoolean = SdcGetJsonPathToString("$.Boolean"),
    FromString = SdcGetJsonPathToString("$.String"),
    FromObject = SdcGetJsonPathToString("$.Object"),
    FromArray = SdcGetJsonPathToString("$.Array")
}

出力JSONデータ例

{
  "FromNumber": "123.45",
  "FromBoolean": "false",
  "FromString": "\"test messages\"",
  "FromObject": "{\"key\":\"value\"}",
  "FromArray": "[\"str\",12.3,null,true]"
}

スクリプト新規作成画面で[ScriptTest]をクリックすると、作成中のスクリプト処理をテストできます。

想定されるWebhook受信データ（HTTPSパケットのBody部）であるJSON文字列を「InputJson」フィールドに指定して[Test]ボタンを押すと、スクリプト処理結果つまりアクションの入力となる書式変換後の文字列が「Result」フィールドに表示されます。

../../_images/user_guide-webhook-usage-scripttest.jpg — 図 5.712 スクリプト新規作成画面(ScriptTest)¶

5.3.3.2.4. エンドポイント定義¶

Webhookによるイベント連携を受け付けるHTTPSエンドポイントを作成します。

エンドポイント一覧画面で[Create New]をクリックして、エンドポイント新規作成画面( 図 5.713 )に遷移します。

../../_images/user_guide-webhook-usage-endpoint.jpg — 図 5.713 エンドポイント新規作成画面¶

注釈

「WebhookToken」項目に表示される文字列は、新規作成中のみ全体が確認できます。この文字列は作成したエンドポイントに対してWebhookによりイベントを送信する際に必要となりますので、安全な方法で記録してください。利用方法の詳細は、後述の Webhookによるイベント連携を参照してください。

以下のように値を設定し、Senju/DCに千手メッセージを送信するエンドポイント定義を作成します。

項目	指定内容
ActionID	前述のアクション定義で定義したアクションのActionID
ScriptID	前述のスクリプト定義で定義したスクリプトのScriptID

5.3.3.2.5. Webhookによるイベント連携¶

作成済みのエンドポイントに対してイベント情報を送信します。

エンドポイントに対する通信はHTTPSを用います。トークンの指定方法に応じて、以下の情報を指定してください。

HTTPのリクエストヘッダーに指定する場合

Authorization ヘッダーにBearerトークンとしてWebhook Token文字列指定します。

項目

指定内容

URL

https://[千手ウェブサービスのホスト名またはIPアドレス]/smc/webhook/gw/endpoints/[EndpointStr文字列]

メソッド

POST

Authorizationヘッダー

Bearer [Webhook Token文字列]

Content-Typeヘッダー

application/json

Body

イベント情報（JSON形式）

URLのクエリー文字列に指定する場合

withParam パスの token クエリーとしてWebhook Token文字列指定します。

項目

指定内容

URL

https://[千手ウェブサービスのホスト名またはIPアドレス]/smc/webhook/gw/endpoints/[EndpointStr文字列]/withParam?token=[Webhook Token文字列]

メソッド

POST

Content-Typeヘッダー

application/json

Body

イベント情報（JSON形式）

参考

上記の指定例における以下の各部分には、前述のエンドポイント定義で確認した、対応する項目の値を入力します。

[EndpointStr文字列]
[Webhook Token文字列]

イベント送信に成功した場合、HTTPステータスコード 200 で以下の内容が返却されます。

{
  "message" : "success.",
  "endpointTicketId" : "__TicketId__"
}

注釈

__TicketId__ 部分に該当する値は、送信イベントに対応する受付履歴をチケット一覧画面にて特定する際に利用します。

5.3.3.2.6. チケット参照¶

Webhookによるイベント連携の受付履歴および動作状態や結果を確認できます。

チケット一覧画面で一覧表示されたチケットの[Details]をクリックすると、チケット参照画面( 図 5.714 )に遷移します。

../../_images/user_guide-webhook-usage-endpointticket.jpg — 図 5.714 チケット参照画面¶

目次

前のトピックへ

次のトピックへ