始めるにあたり、一般的なセルフサービスのユースケースに対するNQL例を確認ください。
従業員にデバイスに関連する基本的な情報やトラブルシューティングオプションを提供するために、Nexthinkデータを活用してデバイス情報を取得し、以下のリモーションを開始します：
リモートアクションを使用してディスク容量の問題を修正します。
Workflowsを使用したMicrosoft Teamsのトラブルシューティング。
バッテリーヘルスが低い場合に備えて、新しいバッテリーを注文します。
前提条件
Nexthinkとセルフサービスポータルの統合を始める前に、以下の要件を整えてください：
セルフサービスポータルのインタラクション設計
Step 1: Authenticate communication
Configure API credentials and collect a token via the API.
Step 2: Identify the device
NQL API を使用して、セルフサービスポータルウィジェットが username に基づいてデバイスを識別できるようにします。 または、大規模な組織の場合、Nexthinkはこの情報をキャッシュするためにData Exporterの使用を強く推奨します。
Step 3: Diagnose the device
Use NQL API (or Data Exporter) to retrieve device performance data and outputs of the Get Startup Impact and Get Battery Status remote actions.
Step 4: Remediate the issue
Remote Actions API を使用して、ユーザーのデバイスで Disk Cleanup リモートアクションをトリガーします。
NQL API を使用して修正状態と詳細を取得し、修正結果をユーザーに通知します。
Nexthinkで
Nexthink web インターフェースでAPI機能を設定します。 Nexthinkは、いくつかの機能が相互依存しているため、リストされている順序に従うことを推奨します。 それでもなお、必要に応じて異なるソリューション間をナビゲートする自由があります。
データ収集リモートアクションの設定
次のリモートアクションをNexthink Libraryからインストールしてください：
毎日実行されるようにスケジュールを設定します。 詳細については、 リモートアクションの管理 を参照してください
このステップを完了したら、後のステップで使用するために両方のリモートアクションのNQL IDを保存します。
NQL ID's:
get_startup_impact_windows
修正リモートアクションの設定
Nexthink Libraryからリモートアクションのディスククリーンアップ をインストールします。 既にインストールしている場合は、次のようにコピーして設定してください：
ディスククリーンアップリモートアクションの入力パラメータ
キャンペーンを表示したい場合は、Nexthink Library キャンペーン disk_cleanup_invoke を使用してください。
キャンペーン確認ポップアップを表示したくない場合は、値00000000-0000-0000-0000-000000000000を入力してください。
CleanupCompletedCampaignId
キャンペーンを表示したい場合は、Nexthink Library キャンペーン disk_cleanup_completed を使用してください。
キャンペーン通知ポップアップを表示したくない場合は、値00000000-0000-0000-0000-000000000000を入力してください。
RemoveFilesNotModifiedInDays
Nexthink Library からのデフォルト値 (7)
Nexthink Library からのデフォルト値 (30)
クリーンアップレベルを選択してください。Light または Deep。
このフィールドは、キャンペーンを使用せず、従業員にクリーンアップレベルを選ばせる場合にのみ機能します。 それ以外の場合、従業員の選択が優先されます。
このステップを完了したら、次のステップで使用するためにリモートアクションのNQL IDを保存します。
NQL ID: disk_cleanup
NQL APIクエリの作成
設計されたシナリオに従い、3つのNQL APIクエリを作成する必要があります：
ユーザーのusernameに基づいてユーザーのデバイスを取得する—ステージ1：デバイスを特定する。
現在のトピックの診断を実行するためにデバイスデータを取得する—ステージ2：デバイスを診断する。
リモートアクションのステータスと結果を取得する—ステージ4：修正のフォローアップ。
各NQL APIクエリの詳細を参照してください。
クエリID : #get_device_basic_infos
Copy devices during past 7d
| with session.events past 7d
| where user.name == $username
| list collector.uid, device.name, operating_system.platform, operating_system.name,
hardware.type, hardware.manufacturer, last_seen
| sort last_seen desc collector.uidフィールドは、リモートアクションをトリガーするための後続のやり取りでシステムが使用するキーです。
usernameに基づいて一致します。 代替のアプローチについては、 Pre-built セクションを参照してください。
クエリID : #diagnose_device_bad_health
Copy devices
| where device.name == $device_name
| include device_performance.events during past 24h
| compute free_space = system_drive_free_space.avg() / 1000000000
| list collector.uid, device.name, free_space,
remote_action.get_startup_impact_windows.execution.outputs.HighImpactCount,
remote_action.get_battery_status.execution.outputs.BatteryHealth 前提条件:
空きディスクスペースはセットアップされたメトリックです。
高影響のスタートアップアプリケーションを確認するには、Nexthink Libraryから Get Startup Impact というリモートアクションが必要です。 リモートアクションをインストールして設定し、毎日実行するようにスケジュールしてください。
バッテリーの健康状態を確認するには、Nexthink Libraryから Get Battery Status というリモートアクションが必要です。 リモートアクションをインストールして設定し、毎日実行するようにスケジュールしてください。
リモートアクションがそのデバイスでまだスケジュールされていないか、または実行されていない場合、対応する列は空のままです。
コンテンツ: リモートアクション Nexthink Library から (NQL ID: disk_cleanup)
前提条件 :
collector.uidは、NQL APIまたはデータエクスポートを介して前のステップで取得されました。
リモートアクション ディスククリーンアップ をインストールするか、Nexthink Library からコピーして次のように設定します：
このステップを完了したら、次のステップで使用するためにすべてのNQL APIクエリのNQL IDを保存します。
NQL ID's:
#diagnose_device_bad_health
#get_remote_action_result
APIクレデンシャルの作成
Nexthink web インターフェースでAPIクレデンシャルを作成し、Nexthinkとセルフサービスポータル間の安全な通信を確立します。 Permissions セクションで、Remote Actions API と NQL API を選択します。 詳細については、 APIクレデンシャル ドキュメントを参照してください。
セルフサービスポータルで
Nexthink内のすべての必要なAPI機能を設定した後、API呼び出しの実装に進みます。
ステップ1：通信を認証する
次のAPI呼び出しを実行する前に、有効な認証トークンを取得する必要があります。 生成した APIクレデンシャル を使用して有効なOAuthトークンを取得する方法については、 Nexthink Developer ドキュメントを参照してください。
ステップ2：デバイスを特定する
デバイスを特定するには、 ユーザー名に基づいてユーザーのデバイスを取得する で作成した NQL API クエリ #get_device_basic_infos を使用します。
APIリクエスト POST /api/v1/nql/execute
Copy {
"queryId": "#get_device_basic_infos",
"parameters": {
"username": "[チャットボットによって特定されたユーザー名]"
}
} APIレスポンスの例 ステータス200
Copy {
"queryId": "#get_device_basic_infos",
"executedQuery": "...",
"rows": 2,
"executionDateTime": { ... },
"headers": [
"device.collector.uid",
"device.name",
"device.operating_system.platform",
"device.operating_system.name",
"device.hardware.type",
"device.hardware.manufacturer",
"device.last_seen"
],
"data": [
[
"e0aa796d-e3af-47b5-88d8-228cf5551fb6",
"XN1231242-2142",
"Windows",
"Windows 11 Pro 22H2 (64 bits)",
"laptop",
"Lenovo",
"2023-07-17 17:53:49"
],
[
"9866a43b-caab-4948-86d2-5567b3ac1d24",
"XCX124231-1231",
"macOS",
"macOS Ventura 13.4.1 (ARM 64 bits)",
"laptop",
"Apple",
"2023-07-17 17:53:03"
]
]
} 注意:
返されたリストが空である場合、そのユーザーは指定された期間 past 7d でデバイスを使用していません。 従業員がデバイスの使用を開始してから、Nexthinkデータプラットフォームでデータが利用可能になるまでには少し遅延があります。
大規模な組織の場合、どのデバイスがどの従業員によって使用されているかを特定するためにCMDBを頼ることをNexthinkは推奨します。 Data Exporterを使用してCMDBデータを補強および修正するためにNexthinkデータを活用してください。 Set upする方法については、エクスポート via SFTP または エクスポート via HTTP for ServiceNow のドキュメントを参照してください。
NQLクエリに基づいて、ユーザーの重要な情報を抽出するための定期的なデータエクスポートを実行することを検討してください。
Copy session.events past 30d
| summarize last_event = time.max() by collector.uid, device.name, operating_system.platform, operating_system.name,
hardware.type, hardware.manufacturer, last_seen ステップ3：特定のデバイスを診断する
ユーザーがデバイスを選択した後にデバイス情報を取得するには、 現在のトピックの診断を実行するためにデバイスデータを取得する で以前に作成した NQL API クエリ #diagnose_device_bad_health を使用します。
APIリクエスト POST /api/v1/nql/execute
Copy {
"queryId": "#diagnose_device_bad_health",
"parameters": {
"device_name": "[チャットボットによって特定されたデバイス名]"
}
} APIレスポンスの例 ステータス200
Copy {
"queryId": "#diagnose_device_bad_health",
"executedQuery": "...",
"rows": 1,
"executionDateTime": { ... },
"headers": [
"device.collector.uid",
"device.name",
"free_space_GB",
"remote_action.get_startup_impact_windows.execution.outputs.HighImpactApplications",
"remote_action.get_startup_impact_windows.execution.outputs.HighImpactCount",
"remote_action.get_battery_status.execution.outputs.BatteryHealth"
],
"data": [
[
"e0aa796d-e3af-47b5-88d8-228cf5551fb6",
"XN1231242-2142",
2.2316807136971,
"",
null,
0.9
]
]
} collector.uidフィールドは、リモートアクションをトリガーするための後続のやり取りでシステムが使用するキーです。
チャットボットは、会話における三つの列を意思決定の分岐として使用します：
もし free_space_GB <= 6
ならば 問題を解決するために ディスクのクリーンアップ のリモートアクションをトリガーします。
もし remote_action.get_startup_impact_windows.execution.outputs.HighImpactCount > 0
ならば 被疑アプリケーションを無効にするために スタートアップメニューからアプリケーションを無効化する のリモートアクションをトリガーします。remote_action.get_startup_impact_windows.execution.outputs.HighImpactApplications の値を使用して、高影響のアプリケーションを無効にします。
もし remote_action.get_battery_status.execution.outputs.BatteryHealth <= 0.85
ならば バッテリーの交換が必要になります：フォローアップのためにチャットボットからITSMチケットを作成してください。
注意:
返されたリストが空である場合、ユーザーは指定された時間枠 (past 7d) でどのデバイスにもアクティブではありません。
診断フィールドのいずれかがnullまたは空である場合、情報が利用できません。 空の値の可能性のある理由は次の通りです：
データプラットフォームフィールドの場合、フィールドはプラットフォームによってサポートされていません。 詳細については、 NQLデータモデル ドキュメントを参照してください。
リモートアクションフィールドの場合、システムはまだリモートアクションを正常に実行していません。 リモートアクションのスケジュールとターゲティングNQLクエリ、およびリモートアクションダッシュボードを確認して、実行エラーの可能性を調べてください。
ステップ4：問題を修正する
設定済みのディスククリーンアップ リモートアクションを実行し、従業員がセルフサービスウィジェットでボタンをクリックした後に問題を解決するために Remote Action API を使用します—修正リモートアクションの設定 を参照してください。
APIリクエスト POST /api/v1/act/execute
Copy {
"remoteActionId": "disk_cleanup",
"devices": ["e0aa796d-e3af-47b5-88d8-228cf5551fb6"]
} APIレスポンスの例 ステータス200
Copy {
"requestId":"f27efd0c-8cb2-4d00-aae0-261aa06729c7",
"expiresInMinutes":10080
} 成功したAPI呼び出しは、エンドポイントの準備が整い次第、リモートアクションが実行されるようにスケジュールされていることを示します。
返されるリクエストIDを使って、実行状況を追跡できます。
この呼び出しは非同期で行われます。これは、API呼び出しが成功したとしても、リモートアクションが開始された、または完了したことを示すものではありません。
注記：
ステータスコードが200以外の場合は、リクエストが失敗したかレート制限に達したことを示します。 詳細については、Nexthink 開発者ポータル ドキュメントを参照してください。
手順5：修正状況をフォローアップ
リモートアクションのステータスと結果を取得するために、事前に作成した #get_remote_action_result NQL API クエリを使用します。
Nexthink は、APIでリモートアクションをトリガーした後、少なくとも1分経過してからリモートアクションの結果を取得するための呼び出しを行うことを推奨します。
リアルタイムのフィードバックを受ける場合、セルフサービスポータルの開発がそれをサポートしている場合は、リモートアクションが完了した際に通知を受けるためのwebhookの使用を検討してください。
前のステップからの入力
ステップ4：問題を解決 の際に、リモートアクションAPI 呼び出しを通じて request_id を取得しました。
APIリクエスト POST /api/v1/nql/execute
Copy {
"queryId": "#get_remote_action_result",
"parameters": {
"request_id": "f27efd0c-8cb2-4d00-aae0-261aa06729c7"
}
} APIレスポンスの例 ステータス 200
Copy {
"queryId": "#get_remote_action_result",
"executedQuery": "...",
"rows": 1,
"executionDateTime": { ... },
"headers": [
"remote_action.execution.request_id",
"device.name",
"remote_action.name",
"remote_action.execution.status",
"remote_action.execution.status_details",
"remote_action.execution.outputs"
],
"data": [
[
"XN1231242-2142",
"f27efd0c-8cb2-4d00-aae0-261aa06729c7",
"ディスククリーンアップ",
"success",
"ディスククリーンアップが成功しました。 \r\nPowerShell はコード 0で終了しました\n",
"{\"CleanupSpace\":1324470272.0}""
]
]
} remote_action.execution.status は現在の実行ステータスを示します。 主なステータスには以下が含まれます：
success リモートアクションが正常に実行された場合。
in_progress システムがまだ実行を完了していない場合。 リモートアクションの様々な状態については、リモートアクション ドキュメントを参照してください。
remote_action.execution.status_details にはトラブルシューティングに役立つリモートアクションの実行詳細が含まれています。 設計上、これは従業員に直接公開されることはありません。
remote_action.execution.outputs は、リモートアクションの出力値を含むJSONマップです。 ディスククリーンアップ リモートアクションには、返される値がバイト単位で解放されたスペースの量を示します。
注記：
ステータスコードが200以外の場合は、リクエストが失敗したかレート制限に達したことを示します。 詳細については、Nexthink 開発者ポータル ドキュメントを参照してください。
システムが空のリストを返した場合、リモートアクションの実行がまだ作成されていません。 これは、APIをトリガーしてからすぐにAPIを呼び出した場合、または実行が24時間以上前である場合に発生します。クエリで指定された期間です。
プリビルトコンテンツ
セルフサービスポータルの統合に役立つように、典型的なチャットボット会話で使用できるトピックの例を見つけてください。 各トピックには以下が含まれます：
前提条件としてのデータ収集リモートアクション。 このセクションで参照されているすべてのリモートアクションは、Nexthink Libraryにあり、事前に設定する必要があります。
データ収集リモートアクション用のスケジュール というトリガータイプを選択し、スケジュールを必要な頻度に応じて毎時間または毎日に設定します。
修正リモートアクション用のAPIがアクティブになっているトリガータイプを選択します。 詳細については、リモートアクションの管理 ドキュメントを参照してください。
事前にデバイス名を特定したことを前提として、エンドツーエンドユースケース と同様のFlowで例を実装します。
一般的なクエリ
エンドツーエンドユースケース に示されているように、すべてのユースケース全体で役立つ基本的なタスクを実行するために一般的なクエリを設定します。
クエリID: #get_device_basic_infos - usernameに基づくマッチング
Copy devices during past 7d
| with session.events past 7d
| where user.name == $username
| list collector.uid, device.name,
operating_system.platform, operating_system.name,
hardware.type, hardware.manufacturer, last_seen
| sort last_seen desc 他のアプローチで使用するために `where` 句 | where user.name == $usernameを調整することができます。たとえば:
ユーザーのUPNを知っている場合: | where user.upn == $upn (CollectorレベルでUPNをアクティブ化する必要があります)
ユーザーのメールアドレスを知っている場合: | where user.ad.email_address == $email (Azure ADコネクタがアクティブになっていて、メールフィールドが同期されている必要があります)
デバイス名を知っている場合: | where device.name == $device_name
ユーザーが他の期間中にアクティブだったデバイスを考慮したい場合は、タイムフレームを調整します。
Nexthinkテナントの最大データ保持期間はデフォルトで30日で、両方の過去7日間の句を目的の期間に置き換えてください。
クエリID: #get_remote_action_result
Copy remote_action.executions past 24h
| where request_id == $request_id
| list request_id, device.name, remote_action.name,
status, status_details, outputs 関連トピック
