リモートアクションをAPI経由でトリガーする（クラシック）

この記事で説明されている機能の一部はFinder（クラシック）に関連しています。

Nexthink FinderはWindows専用のデスクトップアプリケーションで、その機能は現在Nexthinkのwebインターフェース内で利用可能です。 Nexthinkは現在ブラウザから直接使用でき、ほとんどの機能が追加のデスクトップアプリケーションを必要としません。

Nexthink ActのAPIにより、リモートアクションをプログラム上でトリガーすることが可能になり、セルフサービスポータルやチケットシステムなどのサードパーティ製品との統合が可能です。

リモートアクションのAPIは、NexthinkのwebインターフェースによりREST APIとして公開されています。本記事ではAct API v2を文書化しています。

前提条件

Act APIを通じてリモートアクションをトリガーするには、次の前提条件が適用されます。

リモートアクションは手動でトリガーできます。
リモートアクションは、ユーザープロフィールにFinderアクセスを含み、リモートアクションのAPIを許可するオプションが選択されたユーザーの代わりにトリガーされます。

Act APIの呼び出し

Nexthinkのwebインターフェースは、Act APIを次のURLでREST APIとして公開しています。

https://[portal.company.com]/api/remoteaction/v2/run

URLでは、Nexthinkのwebインターフェースの外部DNS名に[portal.company.com]を置き換えてください。

Remote Actionをトリガーするには、APIのURLにパラメータを含むJSONペイロードを送信するPOSTリクエストを送信します（GETリクエストはサポートされず、404エラーが返されます）。

名前

説明

requestUid

(オプション) ログ用のリクエスト識別子です。

remoteActionUid

リモートアクションの識別子です。

deviceUids

ターゲットとなるデバイス識別子のリストです。

engineDatabaseUids

(オプション) ターゲットとなるEngine識別子のリストです。

timeoutSeconds

(オプション) リクエストのタイムアウトを秒で指定します。 Nexthinkのwebインターフェースで設定されたデフォルトのタイムアウトを上書きします（60 秒）。

params

(オプション) パラメータの入力と値のリストです。不明なパラメータ名は無視されます。

この呼び出しはNexthinkのwebインターフェースに接続されているすべてのEngineに配信されるか、指定されたEngineのみに配信され、ターゲットとなるEngineからの応答をNexthinkのwebインターフェースが受信するか、指定されたタイムアウトが経過するまでに返されます。 Nexthinkのwebインターフェースからの成功の応答は、選択されたデバイスでのRemote Actionの実行を保証するものではありません（下記のEngine応答のコード一覧を参照）。

Remote Action、デバイス、EngineのUIDをFinder（クラシック）から取得する

リモートアクションのUIDを取得する方法：

リモートアクションを編集する権限を持つユーザーとしてFinderにログインします。
左側メニューのリモートアクションセクションで、目的のリモートアクションを見つけます。
リモートアクション名を右クリックします。
エクスポート > リモートアクションのUIDをクリップボードにコピーを選択します。
リクエストエディタでCtrl+Vを押して、UIDをJSONペイロードに貼り付けます。

デバイスのUIDを見つけるには、以下のいずれかの方法を使用します。

Finder: デバイスオブジェクトのUIDフィールドを表示します。
NXQL: デバイスオブジェクトのdevice_uidフィールドを取得します。例：

(select device_uid (from device))

特定のEngineを対象にする場合は、List Engines APIを使用して各EngineのデータベースのUIDを取得します。

HTTPヘッダー

リモートアクションのAPIにPOSTリクエストを送信する際には、JSONコンテンツと基本的な認証を指定するために次のHTTPヘッダーを使用します。

Content-type: application/json

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

[base-64(user:password)]をAPIにアクセスする権限を持つNexthinkユーザーの資格情報（base-64エンコード）に置き換えてください。

応答

成功した応答

成功すると、Act API v2への呼び出しは、HTTPコード200でターゲットとなる各Engineからの応答リストを返します。

名前

説明

databaseUid

ターゲットとなるEngineの識別子

code

ok
timeout
engine_error
not_connected
unknown排除databaseUid
許可なしユーザーはそのEngineに権限なし

message

Engineからの追加メッセージの可能性

エラーレスポンス

失敗した場合、Act API v2への呼び出しは、エラーの種類に応じたHTTPコードでエラーレスポンスを返します。

名前

説明

code

エラーコード、以下のいずれか：

HTTPコード

INVALID_REQUEST_JSON

400

INVALID_REQUEST_CONTENT

400

INTERNAL_ERROR

500

CONTENT_TYPE

400

ENCODING

400

NO_REMOTE_ACTION_UID

400

NO_DEVICES

400

TOO_MANY_DEVICES

400

INVALID_ACTION_UID

400

INVALID_DEVICE_UID

400

NO_PERMISSION

403

UNKNOWN_OR_DISABLED_REMOTE_ACTION

400

NO_MANUAL_EXECUTION

400

NO_ENGINES_TO_TARGET

403

error

エラーコードの説明。

関連タスク

すべてのEngineをターゲットにする

すべてのEngineをターゲットにするリクエストの例とそのJSON形式の応答。

// リクエスト
{
 "requestUid": "123",
 "remoteActionUid": "07844969-1889-4de3-9026-020af94be855",
 "deviceUids": ["da2add909a144e8235453f88dc45172f","4423e4c059b2c72ee9382e135888bef7",
 "13ea2b236e6833ffe6045a7715968cba","3537e2f2eb0d5f2152da59e7cbcb505b"]
}


// 応答
// ステータス 200
// 本文:
[
    {
 "databaseUid": "86acc8511251ec444d3a75bac33a23c7",
 "code": "ok",
 "message": ""
    },
    {
 "databaseUid": "a4690014774dcc32b919c27d616166f7",
 "code": "ok",
 "message": ""
    },
    {
 "databaseUid": "ce80dddfdb7a5c2346c4ac184b7d6a54",
 "code": "engine_error",
 "message": "Error in request to engine [172.16.5.177:999]: no license"
    }
]

1つのEngineをターゲットにする

1つのEngineをターゲットにするリクエストの例とそのJSON形式の応答。

// リクエスト
{
 
 "requestUid": "123",
 "remoteActionUid": "07844969-1889-4de3-9026-020af94be855",
 "deviceUids": ["da2add909a144e8235453f88dc45172f","4423e4c059b2c72ee9382e135888bef7",
 "13ea2b236e6833ffe6045a7715968cba","3537e2f2eb0d5f2152da59e7cbcb505b"],
 "engineDatabaseUids" : ["a4690014774dcc32b919c27d616166f7"]
}
 
// 応答
// ステータス 200
// 本文:
[
    {
 "databaseUid": "a4690014774dcc32b919c27d616166f7",
 "code": "ok",
 "message": ""
    }
]

エラーレスポンス

手動実行が無効化されたためエラーを返すリクエストの例。

// リクエスト
{
 "requestUid": "123",
 "remoteActionUid": "e6bb97be-0957-49e0-9922-1a684d093858",
 "deviceUids": ["da2add909a144e8235453f88dc45172f","4423e4c059b2c72ee9382e135888bef7",
 "13ea2b236e6833ffe6045a7715968cba","3537e2f2eb0d5f2152da59e7cbcb505b"]
}
 
 
// 応答
// ステータス 400
// 本文:
{
 "code": "NO_MANUAL_EXECUTION",
 "error": "リモートアクションは手動実行用に設定されていません"
}