サポート (英語のみ)

キャンペーンを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を取得するには:

  1. キャンペーンの編集権限を持つユーザーとしてFinderにログインします。

  2. 左側のメニューの キャンペーン セクションで、目的のキャンペーンを見つけます。

  3. キャンペーン名を右クリックします。

  4. エクスポート > クリップボードにキャンペーン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回だけ受信します。

関連タスク

関連項目

Last updated

Was this helpful?