学ぶ (英語版)
ドキュメント (英語版)
サポート (英語のみ)
コミュニティ (英語版)

Introducing the NXQL API (classic)

NXQL APIは、Web API V2とも呼ばれることがあり、EngineへのURLへのPOSTまたはGET HTTPリクエストを発行することによって呼び出すHTTPSサービスです：

https://<Nexthink_Instance_FQDN>/2/query

このサービスは、メモリ上のEngine databaseへのNXQLクエリに応答し、選択した出力形式でのレコードのリストを返します。

リクエストは次のパラメーターを期待します：

クエリ

実行するNXQLクエリ。

プラットフォーム

クエリの対象プラットフォームを指定します。 クエリが複数のプラットフォームを対象とする必要がある場合、必要なプラットフォーム数分の引数を指定します。 サポートされているプラットフォームは、Windows、macOS、およびmobileです。

形式

期待される出力形式。 利用可能な形式は、CSV、HTML、XMLおよびJSONです。

hr

（オプション）出力が人間に読みやすい形式であるべきかどうかを示すブール値。 trueの場合、応答の数値はより読みやすくするために最も適した単位に適応されます。 選択された単位も値と共に表示されます。 JSON出力形式では使用されません。

例えば、次のNXQLクエリを実行するには：&#x20

(select (device_uid name) (from device))

Nexthinkインスタンスにクエリを送信するには、そのFully Qualified Domain Name (FQDN)を指定する必要があります。 以下の形式でNXQL APIリクエストを使用します：&#x20

https://<instance>-engine-X.<region>.nexthink.cloud/2/query?platform=windows&platform=mac_os&query=(select%20(device_uid%20name)%20(from device))&format=csv

ターゲットEngineインスタンスは、CSV形式でWindowsおよびmacOSすべてのデバイスのユニーク識別子と名前のリストを返します。

テンプレートパラメーター

クエリにプレースホルダー**%1**、%2などを置き換えるために、追加パラメーターp1、p2などを追加できます。 頻繁に使用するクエリをパラメータ化するために、カスタムフィールドの名前、カテゴリ名、またはリテラル値の代わりにプレースホルダーを使用します。

例えば、次のNXQLクエリは、すべてのデバイスの名前と、パラメーターとして渡すカテゴリの関連キーワードを返します&#x20

(select (name #%1) (from device))

次のNXQL APIリクエストを使用して、すべてのデバイスの名前とその_ロケーション_キーワードを取得します：&#x20

https://<instance>-engine-X.<region>.nexthink.cloud/2/query?query=(select%20(name%20%23%251)%20(from%20device))&p1=Location&format=csv

認証

ユーザーアカウント

データプライバシーを**なし（フルアクセス）**に設定し、Finderアクセスオプションを有効にしたすべてのアカウントはNXQL APIを利用できます。 そうでなければ、NXQL APIはアカウントの資格情報を拒否します。 加えて、カテゴリを編集する権利を持つユーザーのみがNXQLクエリを介した更新を行うことができます。

ユーザーの資格情報は基本HTTP認証で確認されます。 特定のユーザーに対して、可視性および情報レベルはそのプロフィールで定義されているものと同一です。

アカウントの変更

アカウントに対して行う変更がすぐにはEngineインスタンスに伝播されないことに注意してください。 すべてのEngineインスタンスの同期には最大5分かかることがあります。 それにより、アカウントの権限に関して一時的な不整合が生じる可能性があります。 例えば、Finderアクセスを削除してNXQL APIへのアクセスを防ぐためにアカウントのプロファイルを変更した場合、同期が行われて資格情報が無効になるまで数分間、そのアカウントはNXQL API経由でEngineインスタンスへのクエリを実行できる可能性があります。

OAuth

Nexthinkを設定して、アクセス委任のオープンスタンダードであるOAuthを使用してNXQL APIへのアクセスを提供できます。 Nexthink サポートに問い合わせて、詳細情報を入手してください。

HTTPステータスコード

NXQL APIは次のものを返します：

  • 200 OK リクエストが成功しました。

  • 400 Bad Request リクエストが無効です。

  • 401 Not Authorized 資格情報が提供されていない、または無効です。

  • 403 forbidden NXQL APIがライセンスされていない場合。

NXQL APIの使用例

NXQLエディタでNXQL APIをテストする

NXQLエディタは、NXQL APIのwebベースのユーザーインターフェースです。 この便利なエディタを使えば、後で統合プロジェクトで使用するクエリをテストできます。 NXQLエディタは、統合ツールキットを含むすべてのEngineに存在し、次のURLを入力することで、お好きなwebブラウザからアクセスできます。

https://<instance>-engine-X.<region>.nexthink.cloud/2/editor/nxql_editor.html

NXQLエディタでクエリを書くには：

  1. ユーザー資格情報を提供します。 上部の2つのテキスト入力ボックスにユーザー名とパスワードを入力します。 提供された資格情報に関連付けられたユーザーのアクセス権がクエリに適用されます。

  2. クエリが対象とするプラットフォームを上部右隅の適切なプラットフォームアイコンをチェックして選択します。

  3. NXQLクエリを中央の大きなテキスト領域に入力します。

    • クエリにテンプレートパラメーターのプレースホルダーが含まれている場合、クエリの下部にある2つのテキストボックスでパラメーターの値を指定します。 エディタクエリには最大2つのテンプレートパラメーターを含めることができます。

  4. （オプション）フォーマット済みをチェックして、人間に読みやすい出力を取得します（上記のNXQL APIリクエストのhrパラメーターを参照）。

  5. 送信をクリックします。

クエリを送信すると、エンジンが処理中にエディタに読み込み中...というメッセージが表示されます。 送信速度、クエリの複雑さ、およびエンジンの負荷に応じて数秒後、応答が同じページの送信ボタンの下に表示されます。

  • x件を表示セレクターで表示される行の最大数を選択します。

  • 右下のボタンを使用して結果ページをナビゲートします。

  • 列のタイトルを繰り返しクリックして、昇順または降順で結果を並べ替えます。

  • 左下の他の形式オプションをクリックして、結果をCSV、HTML、XMLまたはJSON形式で取得します。

wgetを使用してNXQL APIを使用する

NXQL APIは、古典的なUNIXツールwgetを使用して簡単に呼び出すことができます。 たとえば、すべてのデバイスの名前をCSV形式で取得するには、次のコマンドを書きます：

> wget --quiet \
  --no-check-certificate \
  --user=nxdocsapi --password=This-Is_Just-An_Example \
  --output-document devices.csv \
  'https://<instance>-engine-X.<region>.nexthink.cloud/2/query?
   query=(select%20(id%20name)(from%20device))%20&
   format=csv&
   platform=windows&platform=mac_os'

PowerShellを使用してNXQL APIを使用する

NXQL APIは、Windows PowerShellを使用して呼び出すことができます。 ただし、標準のInvoke-WebRequest CmdLetは自己署名証明書をサポートしていないため、ダウンロード可能なファイルCode-For-Invoke-Nxql.ps1で定義されたCmdLetを使用する必要があります。 このスクリプトを保存した後、PowerShell環境にロードします。 PowerShellの実行ポリシーが無制限に設定されていることを確認してください。

スクリプトを読み込むには、PowerShellコンソールで次のように入力します：

. ./Code-For-Invoke-Nxql.ps1

任意のプラットフォームのすべてのデバイスの名前リストをCSV形式で取得するには、次のコマンドを実行します：

Invoke-Nxql -ServerName 192.168.2.3
  -UserName nxdocsapi -UserPassword This-Is_Just-An_Example
  -Platform windows,mac_os
  -Query "(select (name) (from device))" > devices.csv

全コマンドラインオプションを取得するには、次のように入力します：

Invoke-Nxql -?

Power BI Desktopを使用してNXQL APIを使用する

Microsoft Power BIは、組織全体に分析的な洞察を提供するインタラクティブなビジュアライゼーションツールのスイートです。 NXQL APIのおかげで、NexthinkデータをPower BIにフィードし、エンドユーザーのデジタル体験を視覚的に魅力的なグラフに表示することができます。

まず、Power BI Desktopを実行するWindowsデバイスがEngineのサーバー証明書を信頼することを確認します：

  • Engineのデフォルト証明書を、公開信頼のCAが署名したサーバー証明書に置き換えた場合、通常Windowsは証明書を信頼するため、他に何もする必要はありません。

  • それ以外の場合、Engine証明書を署名したCAのルート証明書を、CollectorまたはFinderを実行するデバイスについて説明されているように、WindowsデバイスのTrusted Root Certification Authoritiesストアにインストールします。

Power BI DesktopからNXQL APIを呼び出すには：

  1. Power BI Desktopを開きます。

  2. トップメニューからデータの取得を選択します。

    1. データソースとしてWebを選択します。

    2. Webからダイアログで、NXQL APIクエリをURLとして入力し、出力形式としてXMLを要求します。

      • NXQLエディタでのクエリの編集中に、ページ下部の他の形式セクションからリンクをコピーすることで、このURLを簡単に取得できます。

    3. OKをクリックします。

      • 接続がTLSエラーのために確立できない場合は、Engineのサーバー証明書を信頼するために正しいルート証明書をインポートしたことを確認してください。

  3. NXQL API資格情報を求められたら入力します。

  4. ナビゲーターから、Engineの応答からのXMLデータを取得するために本体を選択します。

  5. 読み込みをクリックします。

データソースが追加されました。 ただし、Power BIはこれらのパラメータ化されたクエリを使用する際に認証資格情報を再度送信することができません。 その解決策は、クエリを基底パスと相対パスに分割することです：

  1. Power BI Desktopで、トップメニューからクエリの編集を選択します。

  2. NXQL APIを呼び出すデータソースを開き、高度なエディタを選択します。

  3. エディタでletキーワードの下にあるソース変数を探します： Source=XML.Table(Web.Contents("https://<Nexthink_Instance_FQDN>/2/query? query=(select%20(id%20name)(from%20device))%20&format=xml" ...

  4. クエリのURLを基底パスと相対パスに分割します：Source=XML.Table(Web.Contents("https://<Nexthink_Instance_FQDN>/2/", [ RelativePath="query?query=(select%20(id%20name)(from%20device))%20&format=xml" ]...

その後の各クエリに対して、Power BI Desktopは最初にデータソースを作成するときに入力した資格情報を使用します。

Last updated

© Nexthink

プライバシーポリシー (英語版)責任ある情報開示ポリシー (英語版)