OpenAPI QueryBuilder の使用

OpenAPI QueryBuilder は、設定とポーリング済みデータをエクスポートし、クエリ URL を作成します。
capm350
HID_OpenAPI_QueryBuilder
OpenAPI QueryBuilder は、設定とポーリング済みデータをエクスポートし、クエリ URL を作成します。
QueryBuilder にアクセスするには、次の URL にアクセスします:
http://
DA_host
:8581/odataquery
フォールト トレラント環境では、
DA_host
としてプロキシ サーバを指定します。
2
OpenAPI クエリの作成
データ ソースからカスタマイズされたデータ セットを抽出するには、QueryBuilder を使用して OpenAPI クエリを生成します。
大きな結果セットを返すクエリは、システムに悪影響を及ぼす可能性があります。 要求に関する結果のみを返すようにクエリを絞り込んでください。
Web ブラウザのアドレス バーが更新され、[Query Expression (クエリ式)]フィールドで選択されたトークンが表示されます。 クエリの編集を続けるには、この URL をコピーして保存します。
以下の手順に従います。
  1. [クエリ式]フィールドをクリックしてクエリを開始します。
  2. データ セットに必要な要素を表す
    for
    オプションを選択します。
  3. select
    select metrics
    、および
    expand
    トークンを追加して出力データを定義します。
  4. トークンをさらに追加して結果を絞り込みます。
    QueryBuilder は OData URL を作成します。
    • QueryBuilder ブラウザ ウィンドウでクエリを実行するには、[
      実行
      ]をクリックします。
    • Web ブラウザ、REST ツール、またはカスタム アプリケーションからクエリを実行するには、OData URL をコピーします。
OpenAPI コントロール
OpenAPI QueryBuilder は、OpenAPI クエリ構文に論理要素を表すトークンを使用します。 [クエリ式]フィールドをクリックすると、トークンが表示されます。 トークンでは、クエリの属性のタイプ、フィルタ、メトリック ファミリ、メトリック、または時間範囲を選択できます。 トークンを選択すると、クエリ URL が更新されます。
トークンを使用して、Query URL を作成およびエクスポートします。
  • for
    このトークンは、クエリのデータ取得に関するアイテムのタイプを決定します。 このトークンは、クエリごとに 1 回のみ表示されます。
    このトークンのほとんどのオプションには、自動フィルタの設定の選択内容が含まれます。 たとえば、トークンで
    interface
    を選択すると、
    within Groups that...
    を選択できます。
    このオプションは、最初の基準として選択されているグループ フィルタで filter トークンを追加します。
    QueryBuilder で新しく追加されたメトリック ファミリが表示されない場合は、Web ブラウザを更新します。
  • select
    このトークンは、データ セットに含めるアイテムのプロパティを決定します。
    結果では適切な順序がサポートされません。
  • expand metrics
    このトークンは、データ セットに含めるパフォーマンス メトリックを決定します。
    結果では適切な順序がサポートされません。
  • フィルタ
    このトークンは、AND および OR の演算子を使用して論理関数に基づくカスタム フィルタを追加します。 このフィルタですべての論理関数に対して大文字小文字を区別するかどうかを選択します。
    OData がフィルタ式を評価する場合、「指定なし」演算子は、ブール式がアイテムのコレクションに対して True または False のどちらであるかを判断するのに使用されます。 以下の例は True を返します。
    • odata/api/devices?$select=ID,Name&$filter=((startswith(Name, 'cisco') eq true))
    • odata/api/cpus?$top=10&$filter=cpumfs/im_Utilization gt 80 where cpumfs/im_Utilization is the collection [60,65,81,68,61]
    大規模なシステムでは、フィルタの適用が効率的でない場合に、一部のクエリがタイムアウトする可能性があります。 OpenAPI は、クエリに表示される順序でフィルタ式を評価します。 データをより制限するフィルタを最初に使用します。 たとえば、北米でインターフェース使用率が 50% を超えるすべてのグループを希望する場合は、北米フィルタを最初に配置します。
  • filter metrics
    このトークンは、選択されたメトリックに基づくカスタム フィルタを追加します。
  • time range
    このトークンは、パフォーマンス メトリックの結果の時間範囲を制限し、データの精度を設定します。
    時間精度が[日]に設定され、[タイム ゾーン]がデフォルト以外の任意の値に設定されている場合、[開始時刻]および[終了時刻]フィールドは無効です。
  • expand
    このトークンは、返されるデータ セットにベース アイテムに関連するデータを追加します。 たとえば、インターフェースのデータを選択した場合は、expand を使用して関連デバイスに関するデータを取得します。
    expand トークンでは、データ セットに追加する列を選択します。 たとえば、デバイスの場合、名前、プライマリ IP アドレス、および場所を選択できます。
    展開された属性がそれぞれ、メトリック列と同じ形式で HTML テーブルに表示されます。 たとえば、特定のデバイスのインターフェース情報を表示する場合は、以下のクエリを使用できます。
    select=device/Name&$expand=device
  • group/aggregate
    このトークンは、返されるデータ セットのグループ化と集計を定義します。 たとえば、CPU 使用率をデバイス レベルに集計して、過去 1 時間の使用率を平均します。
    OpenAPI QueryBuilder で現在サポートされているのは、「
    groupby
    」および「
    aggregate
    」 OData 変換のみです。 開始エンティティがメトリック ファミリの場合は、
    ID
    DeviceItemID
    、および
    Timestamp
    groupby
    変換を適用できます。 config エンティティと集計の開始エンティティがメトリック ファミリ データの場合は、
    ID
    および
    DeviceItemID
    groupby
    変換を適用できます。
    groupby
    変換では、グループ ID を使用してグループ レベルで実行できるようになりました。
    aggregate
    変換では、最大 5 つの式を含めることができるようになりました。
  • sort
    このトークンは、クエリ出力のソートを制御します。
    OpenAPI では、関連するエンティティのプロパティをソートすることはできません。 たとえば、以下のクエリがサポートされています。
    /cpus?$orderby=Name
    以下のクエリはサポートされてい
    ません
    /cpus?$orderby=device/Name
    OpenAPI では、クエリのターゲットになっているエンティティのプロパティのみをソートできます。
    http://
    hostname
    :8581/odata/api/
    TargetEntity
    たとえば、メトリック列のソートは、クエリのターゲットになっているエンティティがメトリック ファミリの場合に最も有効です。
  • limit (top)
    このトークンは、クエリ出力内の行または展開行の最大数を指定します。
    • Maximum number of rows
      結果テーブル内の行の数
    • Maximum number of expanded rows
      展開ウィンドウ内の行の数
      展開トークンが使用されている場合、この数は行数にのみ適用されます。
      デフォルト値または最大行数を変更するには、「OpenAPI のデフォルト値および制限の設定」を参照してください。
    • Skip
      クエリ出力から除外する先頭行の数
  • 形式
    このトークンは、返されるデータ セットの形式を決定します。 OpenAPI は、以下の形式をサポートします。
    • HTML テーブル
      クエリにこのトークンが含まれていない場合は、HTML テーブルがデフォルトの形式です。
      HTML テーブルの形式は、OpenAPI QueryBuilder でのみサポートされています。 ダイレクト OpenAPI クエリは、JSON、XML、Atom、および CSV をサポートします。
    • JSON
      JSON 形式は、結果データ セットからメタデータを削除します。 これを行うと、ネットワーク転送時間、ペイロード サイズ(最大 50 ~ 75%)、およびクライアント処理時間を短縮できます。 JSON 出力にメタデータを手動で追加するには、以下の HTTP ヘッダを使用します。
      Accept: application/json;odata=verbose
      JSON 出力にメタデータを追加することもできます。 これを行うには、次のテキストのように $format クエリ オプションを OData URL に追加します。
      $format=application/json;odata=verbose
    • XML
    • Atom
    • CSV
      形式として CSV を手動で指定するには、OData URL の最後に次のテキストを追加します。
      $format=text/csv
  • custom parameter
    このトークンは、OpenAPI クエリに OData 構文のカスタム パラメータを追加します。
QueryBuilder のメトリック ファミリ名を検索する
OpenAPI のメトリック ファミリ名は、内部メトリック ファミリ名の省略バージョンです。 OpenAPI のメトリック ファミリ名では、プレフィックス「Normalized」およびサフィックス「Info」が削除されます。 大文字が小文字になり、サフィックス「mf」が文字列に追加されます。 たとえば、Interface のメトリック ファミリの内部名は「NormalizedPortInfo」です。 OpenAPI のメトリック ファミリ名は「portmf」です。
内部メトリック ファミリ名を表示するには、
NetOps Portal
で名前を検索します。
以下の手順に従います。
  1. [管理]
    を選択し、Data Aggregator のデータ ソースをクリックします。
  2. [監視設定]
    を展開し、
    [メトリック ファミリ]
    をクリックします。
  3. 列見出しの 1 つにマウス ポインタを置き、下向き矢印をクリックします。
  4. [列]メニューを展開し、[
    内部名
    ]を選択します。
    内部名
    ]列がページに表示されます。
  5. メトリック ファミリを検索し、内部名を記録します。
OpenAPI パフォーマンスのベスト プラクティス
OpenAPI では、データベースからのデータの迅速かつ柔軟な抽出が実行できます。 大きな結果を生成するクエリでは、パフォーマンスを向上させるために以下のベスト プラクティスを使用します。
  • クエリに複数のフィルタを適用すると、同じオブジェクトに対するすべてのフィルタ ルールが隣接することを確認します。 これらのフィルタを分割すると、クエリの効率性が減少します。
  • 文字列によってフィルタリングしないようにします。 たとえば、グループをフィルタするには、グループ名のフィルタリングの代わりにグループ ID を検索します。
  • グループの式を結合します。 グループの式と別の式の間に、OR 演算子を使用することはできません。 たとえば、以下の式はエラーを返します。
    odata/api/interfaces?&$select=ID,Description&$filter=(groups/Name eq 'Manageable Devices') or (substringof('Gigabit',Description) eq true)
  • 大規模なデータ セットに対する集計関数は時間がかかります。
  • OpenAPI は、一括データ エクスポート ツールではありません。 OpenAPI を使用して、必要なデータのみを抽出します。
  • top 値および skip 値を使用して、非常に大規模なデータ セットにページングを適用します。
  • データ セットに関連する最大精度を使用します。 たとえば、合計で集計されたデータが必要な場合は、時間単位または日単位の値がレート データと同じ情報を提供します。