キャンペーンをAPI経由でトリガーする（クラシック）

概要

Nexthink EngageのAPIを使用すると、プログラム的にキャンペーンをトリガーでき、セルフサービスポータルやチケッティングシステムなど、サードパーティ製品と統合が可能です。

前提条件

APIを通じてキャンペーンをトリガーするには、以下の前提条件があります。

キャンペーンは手動でターゲットユーザーに向けられています。
キャンペーンが公開されています。
キャンペーンは、プロファイルにFinderへアクセスでき、かつ「APIによるキャンペーントリガーへのアクセス」のオプションがチェックされているユーザーに代わってトリガーされます。

Engage APIの呼び出し

Portalは、URLの下にREST APIとしてEngage APIを公開しています。

https://[portal.company.com]/api/campaign/v1/trigger

URLでは、ポータルの外部DNS名を[portal.company.com]に置き換えてください。

To trigger a manually targeted campaign, submit a POST request to the URL of the API (note that GET requests are not supported, returning a 404 error) with a JSON payload containing two parameters:

名前

説明

CampaignUid

キャンペーンの識別子

UserSids

ユーザー識別子のリスト

EngageのAPIへのリクエストのJSONペイロードの例:

{
 "CampaignUid": "3a6ae8fe-3e00-40f8-a061-5d8b3ba6d8e9",
 "UserSids" : ["S-1-5-21-2281471460-584676728-3927365163-9716"]
}

Engage APIへの呼び出しは、Portalに接続しているすべてのEngineに配信され、非同期で実行されるため、リクエストが検証された後、すぐに呼び出しが返されます。したがって、Portalからの成功応答は、選択されたユーザーがキャンペーン通知を受け取ったことを保証しません。失敗した応答については、以下のエラー条件のリストを参照してください。

キャンペーンのUIDとユーザーのSIDの取得

キャンペーンのUIDを取得するには:

キャンペーンの編集権限を持つユーザーとしてFinderにログインします。
左側のメニューの キャンペーン セクションで、目的のキャンペーンを見つけます。
キャンペーン名を右クリックします。
エクスポート > クリップボードにキャンペーンUIDを選択します。

ユーザーのSIDを見つける方法は次の通りです。

FinderでユーザーオブジェクトのSIDフィールドを表示します。
NXQLを使用してユーザーオブジェクトのsidフィールドを取得する、例えば: (select sid (from user))
GetSID APIの呼び出し。

HTTPヘッダー

JSONコンテンツを指定し、基本認証を用いるための以下のHTTPヘッダーを付けて、EngageのAPIにPOSTリクエストを送信します。

Content-type: application/json

Authorization: Basic [base-64(user:password)]

Replace [base-64(user:password)] with the credentials (in base-64 encoding) of a Nexthink user who has the right to access the API for triggering campaigns.

エラー条件

リクエストに対して問題が発生した場合、Portalは以下のいずれかの回答を送信することがあります。

エラータイプ

HTTPコード

原因

アクセス拒否

未認証 401

認証エラー

禁止 403

指定されたキャンペーンを実行するための権限が不足しているユーザー

検証エラー

不正なリクエスト 400

Invalid JSON
Invalid encoding
Invalid Content-type
Invalid or missing UID of campaign
Invalid or missing SIDs of users
Unknown or not published campaign
The campaign does not target users manually
Too many user SIDs specified (limited to 12 000 users)

不明なエラー

内部サーバーエラー 500

未定義の内部エラー

静止期間

Engage APIを通じてキャンペーンをトリガーすることは、Finderから手動でトリガーするのと同等です。したがって、API呼び出しでキャンペーンをトリガーした後の後続のAPI呼び出しは、ユーザーの以前の回答に関係なく、過去にキャンペーンの回答を拒否していたとしても、同じユーザーにキャンペーンを再送信することができます。

しかし、ユーザーを誤ったまたは繰り返しのトリガーから煩わせないように、Engage APIを介してトリガーされたキャンペーンでは、他の手動でトリガーされたキャンペーンと同じ静止期間が適用されます: 2時間。この間にすでにキャンペーンを受け取ったユーザーは、同じキャンペーンを再び受け取ることはありません。

Engage APIへの呼び出しがオフライン中のユーザーに複数回キャンペーンをトリガーした場合、ユーザーはキャンペーンを1回だけ受信します。