API を使用してリモートアクションを実行する

Nexthink パブリック API を使用してリモートアクションをトリガーおよびクエリすることで、ServiceNow などの外部アプリケーションとの統合を柔軟に作成できます。 API を使用すると、IT チームは作業を実行するために複数のアプリケーションにアクセスする必要がなくなり、複雑さを軽減できます。

API 認証情報の設定

Nexthink API との統合を設定するには、まずインスタンスで API 認証情報のセットを作成する必要があります。外部アプリケーションまたはサービスは、この認証情報を使用して API にアクセスし、リモートアクションにリクエストを送信します。 詳細については、API Credentials ドキュメントを参照してください。

API リクエスト用のリモートアクションの設定

1. Manage Remote Actions ドキュメントの説明に従って、新しいリモートアクションを作成するか、既存のリモートアクションを編集します。
2. General タブで、API チェックボックスをオンにします。

   

   API チェックボックス
3. Save remote action ボタンをクリックします。

これで、リモートアクションを API 呼び出しで使用できます。

リモートアクション ID のコピー

API 経由でリモートアクションをトリガーするには、その ID を知っている必要があります。

1. メインメニューから Remote Actions を選択します。
2. ナビゲーションパネルの下部にある Manage remote actions ボタンをクリックします。
3. ID が必要なリモートアクションを見つけ、行の右側にあるアクションメニューをクリックして Copy NQL ID を選択します。
4. 後で使用できるようにリモートアクション ID を保存します。

API からクエリしてリモートアクション ID を取得します。 以下のセクションを参照してください。

API 呼び出しの例

認証トークンの取得

client secret と client ID を使用して API からトークンを取得します。

トークンを取得する呼び出しの例を以下に示します。

curl --location --request POST 'https://<customer>.api.<region>.nexthink.cloud/api/v1/token'\ --header 'Authorization: Basic [Base64 encoded clientId:clientSecret]'

• - インスタンス名。
• - リージョン名：

  • us：アメリカ合衆国
  • eu：欧州連合
  • pac：アジア太平洋地域
  • meta：中東、トルコ、アフリカ

呼び出しが成功すると、応答は以下のようになり、access_token フィールドにトークンが含まれます。

{
    "token_type": "Bearer",
    "expires_in": 900,
    "access_token": "example",
    "scope": "service:integration"
}

トークンの有効期間は 15-minute であり、有効期限が切れた後は新しいトークンをリクエストする必要があります。

すべてのリモートアクションのリストを取得

生成されたトークンを使用して、Nexthink インスタンス内のリモートアクションのリストを取得します。

GET

https://<customer>.api.<region>.nexthink.cloud/api/v1/act/remote-action/

API は、設定情報を含むすべてのリモートアクションを JSON 形式で返します。 以下は JSON 応答の例です：

    {
        "id": "#ExampleRA",
        "uuid": "5g5158g0-cd00-46be-9bfb-a9283ba800b",
        "name": "Example Remote Action",
        "purpose": [
            "DATA_COLLECTION"
        ],
        "targeting": {
            "apiEnabled": false,
            "manualEnabled": true,
            "manualAllowMultipleDevices": true
        },
        "scriptInfo": {
            "runAs": "LOCAL_SYSTEM",
            "timeoutSeconds": 120,
            "hasScriptWindows": true,
            "hasScriptMacOs": false,
            "inputs": [
                {
                    "id": "name",
                    "name": "Name",
                    "usedByWindows": true,
                    "usedByMacOs": false,
                    "options": [
                        "X"
                    ],
                    "allowCustomValue": true
                },
                {
                    "id": "StatusChange",
                    "name": "Status Change",
                    "usedByWindows": true,
                    "usedByMacOs": false,
                    "options": [
                        "On"
                    ],
                    "allowCustomValue": true
                },
                {
                    "id": "SetStartTypeTo",
                    "name": "Set Start Type To",
                    "usedByWindows": true,
                    "usedByMacOs": false,
                    "options": [
                        "X"
                    ],
                    "allowCustomValue": true
                }
            ],
            "outputs": [
                {
                    "id": "UpdatedServiceStatus",
                    "name": "Updated Service Status",
                    "type": "list_of_strings",
                    "usedByWindows": true,
                    "usedByMacOs": false
                }
            ]
        }
    },

URL にクエリパラメータを渡して、返されるリストをフィルタリングします。

Windows スクリプトを含むリモートアクション

以下の例では、Windows スクリプトのみを含むリモートアクションを返します。

GET

https://<customer>.api.<continent>.nexthink.cloud/api/v1/act/remote-action/?hasScriptWindows=true&hasScriptMacOs=false

特定のリモートアクションを取得

生成されたトークンを使用して、特定のリモートアクションの設定を取得します。

これは、上記のすべてのリモートアクションを取得する呼び出しと似ていますが、この呼び出しではリモートアクションの URL エンコードされた ID を渡します。 たとえば、ID が #ExampleRA の場合は、URL エンコードして、nql-id パラメータの値として nql-id=%23ExampleRA を送信する必要があります。

GET

https://<customer>.api.<continent>.nexthink.cloud/api/v1/act/remote-action/details?nql-id=%23ExampleRA

リモートアクションのトリガー

生成されたトークンとリモートアクションの ID を使用して、リモートアクションを実行します。

POST

https://<customer>.api.<continent>.nexthink.cloud/api/v1/act/execute

本文では、以下のパラメータを JSON 形式で指定する必要があります：

remoteActionId (String): 実行するリモートアクションの ID。

params (Object | Key Pair): スクリプトに送信するパラメータ。 パラメータがない場合は、オブジェクトを空のままにします。 devices (Array): リモートアクションを実行するデバイスの Nexthink Collector ID。

Collector ID を取得するには、devices オブジェクトを使用して、NQL 調査で device.collector.id フィールドを検索します。

例：

{
 "remoteActionId": "#ExampleRA",
 "params": {"StartType": "Automatic", "StatusChange": "On", "SetStartTypeTo": "Manual"},
 "devices": [
 "2b2frs41-bbb3-4e50-ba45-7ba09c3a7f16","8ebe8051-4g1b-4617-8148-df7a56c307b3","31bc219c-fb9g-47ba-8fc1-18cdf66b5e5a"
    ]
}

呼び出しが正常に送信されると、応答で次のフィールドを取得します：

requested: 実行を生成した、作成済みリクエストの Nexthink ID。 この ID を使用して、NQL でリモートアクションの実行をクエリします。

expiresInMinutes: 対象デバイスがオンラインになって処理を実行しない場合に、実行の有効期限が切れるまでの分数。

例：

{
    "requestId": "7fbd96a7-b717-43a7-8973-9c6adbca3a56",
    "expiresInMinutes": 10080
}