サポート (英語のみ)

NXQL APIの紹介 (クラシック)

NXQL APIは、Web API V2とも呼ばれることがあるHTTPSサービスで、URLを介してエンジンにPOSTまたはGETのHTTPリクエストを発行することで呼び出します:

https://<Nexthink_Instance_FQDN>/2/query

このサービスは、メモリ内のエンジンデータベースに対するNXQLクエリに対して、選択した出力形式でレコードのリストを返します。

リクエストは、以下のパラメーターを必要とします:

クエリー

実行するNXQLクエリー。

プラットフォーム

クエリーのターゲットプラットフォームを指定します。 クエリーが複数のプラットフォームをターゲットにしている場合は、必要なプラットフォームそれぞれに対して引数を渡します。 サポートされているプラットフォームはwindows、mac_os、mobileです。

フォーマット

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

hr

(任意)出力を人間が読みやすい形式にするかどうかを示すブール値。 trueの場合、レスポンス内の数値は、読みやすくするために最適な単位に変換されます。 選択された単位も値と共に表示されます。 JSON出力形式の場合には使用されません。

例えば、次のNXQLクエリーを実行するには:

(select (device_uid name) (from device))

Nexthinkインスタンスにクエリーを送信するには、その完全修飾ドメイン名（FQDN）を指定する必要があります。 NXQL APIリクエストを次の形式で使用します:

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

ターゲットエンジンインスタンスは、CSV形式で全てのWindowsおよびmacOSデバイスの一意の識別子と名前のリストを返します。

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

追加パラメーター p1, p2 などをクエリーに追加して、NXQLクエリー内のプレースホルダー %1, %2 などを置き換えることができます。 カスタムフィールドの名前、カテゴリの名前、またはパラメーター化されたクエリーによく使われるリテラル値の代わりにプレースホルダーを使用します。

例えば、次のNXQLクエリーは、デバイスの名前とパラメーターとして渡すカテゴリに関連付けられたキーワードを返します。

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

次のNXQL APIリクエストを使用して、全てのデバイスの名前とその Location キーワードを取得します:

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認証で検証されます。 特定のユーザーにとって、表示および情報のレベルは、そのユーザープロファイルで定義されているものと同じです。

アカウントの修正

アカウントに行った変更は、エンジンインスタンスに直ちに反映されないことに注意してください。 全てのエンジンインスタンスの同期には最大5分かかる場合があります。 これにより、一時的にアカウントの許可に関する不一致が生じることがあります。 例えば、アカウントのプロファイルを変更してFinderアクセスを削除し、NXQL APIへのアクセスを防ぐと、アカウントが無効になる前の数分間、エンジンインスタンスへのNXQL APIを介したクエリーが可能な場合があります。

OAuth

Nexthinkを構成して、アクセス委任のオープン標準であるOAuthを使用してNXQL APIへのアクセスを許可することができます。 Nexthink サポートに問い合わせて、詳細情報を入手してください。

HTTPステータスコード

NXQL APIは以下を返します:

  • 200 OK\nリクエストは成功しました。

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

  • 401 Not Authorized\n資格情報が提供されていないか、無効です。

  • 403 forbidden\nNXQL APIがライセンスされていません。

NXQL APIの使用例

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

NXQLエディターは、NXQL API用のウェブベースのユーザーインターフェースです。 この便利なエディターを使って、後で統合プロジェクトで使用する予定のクエリーをテストすることができます。 NXQLエディターは、統合ツールキットを備えたすべてのエンジンに搭載されており、お気に入りのウェブブラウザから次のURLを入力してアクセスできます:

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形式で全デバイスの名前を取得するには、次のコマンドを入力します:

PowerShellを使ったNXQL APIの使用

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

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

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

フルコマンドラインオプションを取得するには、次を入力します:

Power BI Desktopを使用したNXQL APIの使用

Microsoft Power BIは、インタラクティブな可視化ツールのスイートで、組織全体に分析の洞察を提供します。 NXQL APIのおかげで、NexthinkデータでPower BIをフィードし、魅力的なチャートでエンドユーザーのデジタルエクスペリエンスを可視化します。

まず、Power BI Desktopを実行するデバイスがエンジンサーバー証明書を信頼していることを確認してください。

  • デフォルトのエンジン証明書を公的に信頼された認証局が署名したサーバー証明書に置き換えた場合、通常Windowsが証明書を信頼するため、他に何も必要ありません。

  • そうでない場合は、エンジンサーバー証明書を署名したCAのルート証明書を、CollectorまたはFinderを実行しているデバイスの説明に従って、WindowsデバイスのTrusted Root Certification Authoritiesストアにインストールします。

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

  1. Power BI Desktopを開きます。

  2. 上部メニューから データ取得 を選択します。

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

    2. From web ダイアログで、NXQL APIクエリーをXML出力形式として URL に入力します。

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

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

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

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

  4. ナビゲーターで、エンジンレスポンスからXMLデータを取得するために本体を選択します。

  5. ロードをクリックします。

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

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

  2. NXQL APIを呼び出すデータソースを開き、Advanced Editor を選択します。

  3. エディターで、let キーワードの下にある Source 変数を探します:\ 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

Was this helpful?