ライセンス使用状況の取得

コンピューター・システムによって報告されるライセンス使用状況に関する情報を要求するには、api/sam/license_usages エレメントに対して GET 操作を使用します。

この API は、最後の 90 日間におけるピークのライセンス使用状況を取得します。PVU および RVU のフルキャパシティーおよびサブキャパシティー・ライセンス使用状況は、ホスト・コンピューター・システム・レベルでのみ取得されます。コンピューター・システムによって報告されるライセンス使用状況に関する情報を取得するには、次の URL を使用します。 
https://hostname:port/api/sam/license_usages?token=token
重要:
  • この API を使用するには、「すべてのコンピューター」グループに割り当てられていて、「ライセンス・メトリックの表示」権限が付与されている必要があります。
  • 各 API 要求は、token パラメーターを使用して認証する必要があります。認証トークンを取得するための REST API を使用して取得することができます。BigFix Inventory にログインして「ユーザー」アイコン「ユーザー」アイコンにカーソルを移動して、「プロファイル」をクリックすることもできます。次に、「トークンの表示」をクリックします。
  • この API は、最後の正常なインポートが行われるまでの、最後の 90 日間のデータを取得します。
  • デフォルトでは、取得したデータは computer_system_id、software_title_id、および metric_name 列でソートされます。
表 1. 操作の説明
操作の詳細 「説明」
操作 GET /api/sam/license_usages
目的 ライセンス使用状況に関する情報を返します
HTTP メソッド GET
リソース URI https://server_host_name:port_number/api/sam/license_usages
URL リンク関係 n/a
URI 照会パラメーター 適用可能な照会パラメーターのリストについては、以下を参照してください。「照会パラメーター」。
要求ヘッダー
ヘッダー
Accept-Language (オプション)
値
en-US (英語のみをサポート)

応答の言語のネゴシエーションに使用されます。このヘッダーを指定しない場合、コンテンツはサーバーの言語で戻されます。
要求ペイロード n/a
要求 Content-Type
  • application/json
応答ヘッダー
ヘッダー
Content-Type
値
application/json

応答のコンテンツ・タイプを指定します。
ヘッダー
Content-Language
値
en-US, …

応答のコンテンツの言語を指定します。このヘッダーを指定しない場合、コンテンツはサーバーの言語で戻されます。
ヘッダー
Import-Mode
値
none､idle､running､pending

インポートの状況を示します。
ヘッダー
Import-Progress
値
パーセント値 (例: 59)。

インポートの進行状況をパーセントで示します。
ヘッダー
Import-Last-Status
値
successful、 failed

最後のインポート状況を示します。
ヘッダー
Import-Last-Success-Time
値
日付 (例: 2014-06-18T04:00:29Z)。

最後の正常なインポートの時刻を示します。
応答ペイロード License Usages element
応答 Content-Type
  • application/json
正常な HTTP 応答コード
  • 200 – OK
エラーの HTTP 応答コード
  • 500 – "Bad Request" 照会パラメーターにエラーがあるか、照会パラメーターが欠落している場合

メッセージの本文にはエラー・メッセージと詳細が含まれます。

照会パラメーター

照会パラメーターは、検索結果の絞り込みに使用できます。以下の表は、api/sam/license_usages エレメントに対して使用できる照会パラメーターを示しています。
表 2. ライセンス使用状況を取得するための照会パラメーター
パラメーター 「説明」 必須 値
columns[] 取得する列を指定します。このパラメーターを指定しない場合は、一連のデフォルトの列が取得されます。例:
名前とバージョンの列を取得します。
URL?columns[]=name&columns[]=version
 いいえ ストリング
order 返されたデータのソート方法を指定します。列のソートのデフォルト方向は昇順です。降順ソートを指定する場合は、列名に desc を追加します。例:
ピークのライセンス使用状況の降順で並び替えるには、次のように指定します。
URL?order[]=peak_value desc
 いいえ ストリング
限界値 取得する行数を指定します。このパラメーターを省略した場合、すべての行が取得されます。 いいえ 数字
offset 結果の取得でスキップする行数を指定します。これを limit パラメーターと一緒に使用して、結果をページ編集できます。例:
レコード 150 の後から始まる 50 件のレコードを取得するには、次のとおり指定します。
URL?limit=50&offset=150
 いいえ 数字
token 固有のユーザー認証 ID。自分のトークンは、BigFix Inventory の「プロファイル」設定に表示できます。 はい 英数字
criteria 特定の条件と合致するレコードを取得します。このパラメーターでは、以下の構造が 1 行で記述されている必要があります。 
<criteria> ::= <left-brace> <boolean-operator><colon> <left-bracket> 
<criterion> [{ <comma> <criterion> }...] <right-bracket> <right-brace>

<boolean-operator> ::= "and" | "or"
<criterion> ::= <criteria> | <left-bracket> <column> <comma> <operator> <comma> <value> <right-bracket>
<column> ::= <json-string>
<operator> ::= <json-string>
<value> 	::= <json-array> | <json-string> | <json-numver> | <json-null>

演算子について詳しくは、共通のコネクターおよび演算子を参照してください。

例: 発行者名に「BigFix」が含まれるソフトウェアのライセンス使用状況を取得します。
URL?criteria={ "and": [ ["publisher_name", "contains", "BigFix"]]}

HTTP 会話の例

要求
GET api/sam/license_usages
?token=7adc3efb175e2bc0f4484bdd2efca54a8fa04623
Host: localhost:9081 
Accept: application/json 
Accept-Language: en-US
応答ヘッダー
HTTP/1.1 200 OK
Content-Type: application/json
Content-Language: en-US
上記の応答ヘッダーの後には、Import-Mode で表わされるデータ・インポートの現在の状況に応じてそれぞれ異なる項目が続きます。返される値について理解するために、以下の定義を確認してください。
  • none - データ・インポートが一度も開始されていない
  • idle - データ・インポートは現在実行されていない
  • running - データ・インポートは進行中
  • pending - ユーザー・インターフェースで実行されるアクションが、データ・インポートを開始して変更を有効にすることを必要とする
データ・インポートが一度も開始されていない場合:
Import-Mode: none
データ・インポートが進行中の場合:
Import-Mode: running
Import-Progress: 41
データ・インポートが実行されていない場合:
Import-Mode: idle/pending
Import-Last-Status: successful
Import-Last-Success-Time: Mon, 23 Jun 2014 12:18:29 GMT
応答の本文 (JSON)
特定の項目がデフォルトで非表示になっている場合、一般 URL を使用してもその項目は取得されません。このようなデータを取得するには、照会パラメーターを使用して、非表示の列の名前を指定する必要があります。例えば、以下に示すように、columns[] パラメーターを使用して、software_title_dimension.name 列を取得できます。 
URL?columns[]=software_title_dimension.name
{
"software_title_id": 36181,
"metric_name": "RVU_FULL_CAP",
"computer_system_id": 4,
"peak_value": 1,
"peak_date": "2014-04-14",
"peak_time": "2014-04-14T13:05:10Z",
"reporting_period_start_date": "2014-04-01",
"reporting_period_end_date": "2014-04-30",
"software_title_dimension":   //hidden by default 
   {
   "name": "BigFix Protection",
   "guid": "d78048cf-842b-44e8-8036-e7e2bf8afb31",
   "publisher_name": "BigFix",
   "publisher_guid": "8a759f0c-b91a-4d7d-8c4a-a9d85e06c13d" 
   }
}