セルフサービスポータルを使用したデバイス問題の改善

始めるにあたり、一般的なセルフサービスのユースケースに対するNQL例を確認ください。

従業員にデバイスに関連する基本的な情報やトラブルシューティングオプションを提供するために、Nexthinkデータを活用してデバイス情報を取得し、以下のリモーションを開始します：

• リモートアクションを使用してディスク容量の問題を修正します。

• Workflowsを使用したMicrosoft Teamsのトラブルシューティング。

• バッテリーヘルスが低い場合に備えて、新しいバッテリーを注文します。

前提条件

Nexthinkとセルフサービスポータルの統合を始める前に、以下の要件を整えてください：

• Nexthinkライセンス

• 管理者権限

セルフサービスポータルのインタラクション設計

インタラクションステージ	APIテクノロジー
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 リモートアクションをトリガーします。
ステップ5：修正のフォローアップ	NQL APIを使用して修正状態と詳細を取得し、修正結果をユーザーに通知します。

Nexthinkで

Nexthink web インターフェースでAPI機能を設定します。 Nexthinkは、いくつかの機能が相互依存しているため、リストされている順序に従うことを推奨します。 それでもなお、必要に応じて異なるソリューション間をナビゲートする自由があります。

データ収集リモートアクションの設定

次のリモートアクションをNexthink Libraryからインストールしてください：

• スタートアップインパクトを得る

• Get Battery Status

毎日実行されるようにスケジュールを設定します。 詳細については、 リモートアクションの管理 を参照してください

このステップを完了したら、後のステップで使用するために両方のリモートアクションのNQL IDを保存します。

NQL ID's:

• get_startup_impact_windows

• get_battery_status

修正リモートアクションの設定

Nexthink Libraryからリモートアクションのディスククリーンアップをインストールします。 既にインストールしている場合は、次のようにコピーして設定してください：

• リモートアクショントリガーにAPIを選択します。

• 入力パラメータのデフォルト値を設定し、自分のセルフサービスポータルのニーズに合わせます。 下記のディスククリーンアップリモートアクションの入力パラメータテーブルを参照してください。

ディスククリーンアップリモートアクションの入力パラメータ

入力	推奨値
DiskCleanupCampaignId	キャンペーンを表示したい場合は、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)
MaximumDelayInSeconds	Nexthink Library からのデフォルト値 (30)
CleanupLevel	クリーンアップレベルを選択してください。Light または Deep。 このフィールドは、キャンペーンを使用せず、従業員にクリーンアップレベルを選ばせる場合にのみ機能します。 それ以外の場合、従業員の選択が優先されます。

このステップを完了したら、次のステップで使用するためにリモートアクションのNQL IDを保存します。

NQL ID: disk_cleanup

NQL APIクエリの作成

設計されたシナリオに従い、3つのNQL APIクエリを作成する必要があります：

• ユーザーのusernameに基づいてユーザーのデバイスを取得する—ステージ1：デバイスを特定する。

• 現在のトピックの診断を実行するためにデバイスデータを取得する—ステージ2：デバイスを診断する。

• リモートアクションのステータスと結果を取得する—ステージ4：修正のフォローアップ。

各NQL APIクエリの詳細を参照してください。

ユーザーのユーザー名に基づいてデバイスを取得する

クエリID: #get_device_basic_infos

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

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

前提条件:

• 前のステップでデバイス名を取得しました。

• この例では、3つのデータポイントを収集します：

  • 空きディスクスペースはセットアップされたメトリックです。

  • 高影響のスタートアップアプリケーションを確認するには、Nexthink Libraryから Get Startup Impact というリモートアクションが必要です。 リモートアクションをインストールして設定し、毎日実行するようにスケジュールしてください。

  • バッテリーの健康状態を確認するには、Nexthink Libraryから Get Battery Status というリモートアクションが必要です。 リモートアクションをインストールして設定し、毎日実行するようにスケジュールしてください。

• リモートアクションがそのデバイスでまだスケジュールされていないか、または実行されていない場合、対応する列は空のままです。

ディスククリーンアップリモートアクションを取得する

コンテンツ: リモートアクション Nexthink Library から (NQL ID: disk_cleanup)

前提条件:

• collector.uidは、NQL APIまたはデータエクスポートを介して前のステップで取得されました。

• リモートアクション ディスククリーンアップ をインストールするか、Nexthink Library からコピーして次のように設定します：

  • リモートアクショントリガーにAPIを選択します。

  • 入力パラメータのデフォルト値を設定し、自分のセルフサービスポータルのニーズに合わせます。 下記のディスククリーンアップリモートアクションの入力パラメータテーブルを参照してください。

このステップを完了したら、次のステップで使用するためにすべてのNQL APIクエリのNQL IDを保存します。

NQL ID's:

• #get_device_basic_infos

• #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

{
 "queryId": "#get_device_basic_infos",
 "parameters": {
 "username": "[チャットボットによって特定されたユーザー名]"
  }
}

APIレスポンスの例

ステータス200

{
 "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"
 ]
 ]
}

注意:

• ステータスコードが200でない場合、リクエストは失敗したか、レート制限を超過しました。 詳細については、 Nexthink Developer ドキュメントを参照してください。

• 返されたリストが空である場合、そのユーザーは指定された期間 past 7d でデバイスを使用していません。 従業員がデバイスの使用を開始してから、Nexthinkデータプラットフォームでデータが利用可能になるまでには少し遅延があります。

大規模な組織の場合、どのデバイスがどの従業員によって使用されているかを特定するためにCMDBを頼ることをNexthinkは推奨します。 Data Exporterを使用してCMDBデータを補強および修正するためにNexthinkデータを活用してください。 Set upする方法については、エクスポート via SFTP または エクスポート via HTTP for ServiceNow のドキュメントを参照してください。

主要なユーザー情報を抽出するために定期的にNQLクエリに基づいたデータエクスポートを検討してください。

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

{
 "queryId": "#diagnose_device_bad_health",
 "parameters": {
 "device_name": "[チャットボットによって特定されたデバイス名]"
 }
}

APIレスポンスの例

ステータス200

{
 "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チケットを作成してください。

注意:

• ステータスコードが200でない場合、リクエストは失敗したか、レート制限を超えていました。 詳細については、 Nexthink Developer ドキュメントを参照してください。

• 返されたリストが空である場合、ユーザーは指定された時間枠 (past 7d) でどのデバイスにもアクティブではありません。

• 診断フィールドのいずれかがnullまたは空である場合、情報が利用できません。 空の値の可能性のある理由は次の通りです：

  • データプラットフォームフィールドの場合、フィールドはプラットフォームによってサポートされていません。 詳細については、 NQLデータモデル ドキュメントを参照してください。

  • リモートアクションフィールドの場合、システムはまだリモートアクションを正常に実行していません。 リモートアクションのスケジュールとターゲティングNQLクエリ、およびリモートアクションダッシュボードを確認して、実行エラーの可能性を調べてください。

ステップ4：問題を修正する

リモートアクションAPIを使用して、前のステップで構成したディスククリーンアップリモートアクションを実行し、 従業員がセルフサービスウィジェットのボタンをクリックした後に問題を解決します。詳細はリモートアクションの構成を参照してください。

APIリクエスト

POST /api/v1/act/execute

{
 "remoteActionId": "disk_cleanup",
 "devices": ["e0aa796d-e3af-47b5-88d8-228cf5551fb6"]
}

APIレスポンスの例

ステータス200

{
 "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

{
 "queryId": "#get_remote_action_result",
 "parameters": {
 "request_id": "f27efd0c-8cb2-4d00-aae0-261aa06729c7"
  }
}

APIレスポンスの例

ステータス 200

{
 "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ライブラリーに存在し、事前に構成する必要があります。

  • データ収集リモートアクションのトリガータイプスケジュールを選択し、必要な頻度に応じてスケジュールを毎時または毎日に設定します。

  • トリガータイプAPIを選択して、リメディエーションリモートアクションをアクティブにします。 詳細についてはリモートアクションの管理文書を参照してください。

• 診断NQLクエリ。

• 診断クエリ結果を解釈するロジック。

• 各診断のための可能な修正方法。

デバイス名を事前に特定していることを前提に、エンドツーエンドのユースケースと同様のフローを使用して例を実装します。

一般的なクエリ

エンドツーエンドのユースケースで示されているように、すべてのユースケースで役立つ基本的なタスクを実行するために一般的なクエリを構成します。

タスク	NQL クエリー
ユーザーのデバイスの取得	クエリID: #get_device_basic_infos - usernameに基づくマッチング 過去7日間のデバイス | session.events（過去7日間）とともに | 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 user.name == $username句を調整できます。例えば： ユーザーのUPNを知っている場合：| where user.upn == $upn（コレクターレベルでUPNを有効にする必要があります） ユーザーのメールアドレスを知っている場合：| where user.ad.email_address == $email（Azure ADコネクターを有効にし、メールフィールドが同期されている必要があります） デバイス名を知っている場合：| where device.name == $device_name ユーザーがアクティブだった7日間以外の期間についてデバイスを考慮したい場合は、期間を調整してください。 保持期間のデフォルト設定は30日であるため、最大データ保有期間まで期間を調整できます。
リモートアクションのステータスと出力を取得します	クエリID: #get_remote_action_result 過去24時間のリモートアクション実行 | request_id == $request_id | list request_id, device.name, remote_action.name, status, status_details, outputs

---

関連トピック