ライセンス・メトリック使用状況の取得 (v2)

9.2.10 9.2.10 から使用可能。インフラストラクチャー内にインストールされている製品のライセンス・メトリック使用状況に関する情報を要求するには、api/sam/v2/license_usage エレメントに対して GET 操作を使用します。デフォルトでは、認証にトークンが使用されているユーザーのコンピューター・グループについての結果が返され、データがこのグループに集約される期間が対象となります。また、「すべてのメトリック」レポートに追加されたカスタム・フィールドも含まれます。

権限

ユーザーこの API を使用するには、「ライセンス・メトリックの表示」権限が必要です。

リソース URL

https://hostname:port/api/sam/v2/license_usage?token=token

リソース情報

表 1. リソース情報
操作の詳細	「説明」
HTTP メソッド	`GET`
要求ヘッダー	ヘッダー `Accept-Language` (オプション) 値 en-US (英語のみをサポート) 応答の言語をネゴシエーションします。ヘッダーを指定しない場合、コンテンツはサーバーの言語で戻されます。
要求フォーマット	`application/json`
応答ヘッダー	ヘッダー `Content-Type` 値 `application/json` 応答のコンテンツ・タイプを指定します。
	ヘッダー `Content-Language` 値 en-US, … 応答のコンテンツの言語を指定します。ヘッダーを指定しない場合、コンテンツはサーバーの言語で戻されます。
	ヘッダー `startdate` 値 `YYYY-MM-DD` データの取得を開始する日付を指定します。
	ヘッダー `enddate` 値 `YYYY-MM-DD` データの取得を終了する日付を指定します。
	ヘッダー `computerGroupId` 値 Integer データを取得するコンピューター・グループの ID を指定します。
応答ペイロード	`License Usage` element
応答フォーマット	`application/json`
応答コード	`200 – OK` `400 – "Bad Request"` 照会パラメーターにエラーがあるか、照会パラメーターが欠落している場合

スキーマの説明

この REST API によって返されるすべての列のリストをその説明と一緒に取得するには、次の要求を使用します。

GET api/sam/v2/schemas/license_usage.json?token=token

選択可能な列

表 2. 選択可能な列
列	「説明」	デフォルトで表示	タイプ
product_publisher_name	製品の発行者の名前。	✓	ストリング
product_id	ソフトウェア製品の ID。		Integer
product_name	ソフトウェア製品の名前。	✓	ストリング
product_family_guid	ソフトウェア製品の GUID。		ストリング
metric_id	ライセンス・メトリックの ID。戻り値の説明については、以下を参照してください:メトリック ID およびコード名。		ストリング
metric_name	ライセンス・メトリックの名前。`metric_name` パラメーターによって返される値は参照として指定され、「メトリック ID、コード名、および説明」でメトリックの説明として指定された値と若干異なる場合があります。`metric_id` または `metric_code_name` パラメーターを使用してメトリックを取得し、その後「メトリック ID、コード名、および説明」を参照して正確なメトリックの説明を確認することをお勧めします。		ストリング
metric_code_name	ライセンス・メトリックのコード名。戻り値の説明については、以下を参照してください:メトリック ID およびコード名。	✓	ストリング
hwm_quantity	データが取得された期間内に製品が使用したメトリック単位の最大数。特定のライセンス・メトリックについてメトリック数量が測定されていない場合、 hwm_quantity パラメーターによって返される値は -1 になります。値 -1 は、ソートやフィルタリングには使用できません。	✓	Integer
しきい値	コンピューター・グループ内で製品で使用を許諾されているメトリック単位の最大数。この値は手動で設定され、メトリックしきい値の差分を計算するために使用されます。		Integer
threshold_delta	しきい値からメトリック数量を減算することによって計算されます。計算されていないライセンス・メトリックのしきい値を指定すると、 threshold_delta パラメーターによって返される値は 2147483647 になります。値 2147483647 は、ソートやフィルタリングには使用できません。		Integer
imported_part_numbers	BigFix Inventory にインポートした部品番号。product_name 列とそのライセンス・メトリックにリストされている製品を表します。		ストリング
is_reaggregation_needed	製品に対して再計算が必要かどうかを指定します。このパラメーターは、結果のフィルタリングやソートには使用できません。		ブール値
custom_field_number	「すべてのメトリック」レポートに追加されたカスタム・フィールド。すべてのカスタム・フィールドのリストを表示するには、license_usage.json スキーマを表示します。		各種の問題
hwm_peak_time	選択した期間内に製品がメトリック単位の最大数を使用した日付と時刻。hwm_quantity パラメーターの値が -1 の場合、 hwm_peak_time の値は無意味なものとなります。注: hwm_peak_time を取得すると、データの取得にかかる時間が著しく増加する可能性があります。		ストリング
bundle_id	製品が割り当てられている FlexPoint バンドルまたは Cloud Pak の ID。		Integer (整数)
bundle_name	製品が割り当てられている FlexPoint バンドルまたは Cloud Pak の名前。		ストリング
bundle_type	バンドルのタイプ。可能な値: -1 - バンドルではない 0 - FlexPoint バンドル 1 - Cloud Pak		整数のセット
bundle_guid	製品が割り当てられている FlexPoint バンドルまたは Cloud Pak の GUID。		ストリング
bundle_metric_contribution	製品が FlexPoint バンドルまたは Cloud Pak の一部である場合、特定の製品が、その製品が割り当てられている FlexPoint バンドルまたは Cloud Pak の全体的なメトリック数量の一因となっているライセンス・メトリック単位の数が列に表示されます。これは、 hwm_quantity 列の値に、特定の製品に対して指定されている変換オプションを乗算して得た値です。製品が FlexPoint バンドルまたは Cloud Pak の一部でない場合、列は空です。		Integer (整数)
product_bundle_ratio_divider	製品が FlexPoint バンドルまたは Cloud Pak の一部である場合、この列には、製品ライセンス・メトリックをバンドルのライセンス・メトリックに変換するために使用される比率の除数が表示されます。例えば、IBM Security QRadar SOAR ユーザーが IBM Cloud Pak for Security の一部としてインストールされている場合、変換率は 5:1 です。この場合の product_bundle_ratio_divider 列の値は 5 です。		Integer (整数)
product_bundle_ratio_factor	製品が FlexPoint バンドルまたは Cloud Pak の一部である場合、この列には、製品ライセンス・メトリックをバンドルのライセンス・メトリックに変換するために使用される比率の係数が表示されます。例えば、IBM Security QRadar SOAR ユーザーが IBM Cloud Pak for Security の一部としてインストールされている場合、変換率は 5:1 です。この場合の product_bundle_ratio_factor 列の値は 1 です。		Integer (整数)

照会パラメーター

表 3. 照会パラメーター
パラメーター	「説明」	必須	値
columns	取得する列を指定します。このパラメーターを指定しなかった場合、デフォルトの列のみが取得されます。例: 製品名およびしきい値の差分の取得 `URL?columns[]=product_name&columns[]=threshold_delta`		ストリング
computerGroupId	データを取得するコンピューター・グループの ID を指定します。このパラメーターを指定しない場合、認証に使用されるトークンを持つユーザーのコンピューター・グループのデータが取得されます。このパラメーターを指定すると、このコンピューター・グループのサブグループのデータを取得できます。コンピューター・グループの ID を表示するには、BigFix Inventory にログインして、「レポート」 > 「コンピューター・グループ」に移動します。「レポート・ビューの管理」アイコンの上にカーソルを移動して、「ビューの設定」をクリックし、レポートに表示する ID 列を選択します。例: コンピューター・グループ 5 のデータの取得 `URL?computerGroupId=5`		Integer
order	取得したデータのソート方法を指定します。列のソートのデフォルト方向は昇順です。降順ソートを指定する場合は、列名に `desc` を追加します。例: しきい値の差分による並べ替え `URL?order[]=threshold_delta desc`		英数字
限界値	取得する行数を指定します。このパラメーターを省略した場合、すべての行が取得されます。例: 100 件のレコードの取得 `URL?limit=100`		数字
offset	結果の取得でスキップする行数を指定します。これを limit パラメーターと一緒に使用して、結果をページ編集できます。例: レコード 150 の後から始まる 50 件のレコードの取得 `URL?limit=50&offset=150`		数字
startdate	データの取得を開始する日付を指定します。`YYYY-MM-DD` 形式で指定してください。このフィルターを指定しない場合、デフォルト値は、BigFix Inventory に最後にデータが正常にインポートされた日付から、コンピューター・グループにおけるデータの計算対象となる日数 (デフォルトは 90 日) を引いた日付になります。例: 2017 年 7 月 14 日から始まるデータの取得 `URL?startdate=2017-07-14`		日付
enddate	データの取得を終了する日付を指定します。`YYYY-MM-DD` 形式で指定してください。このフィルターを指定しない場合、デフォルト値は、BigFix Inventory へのデータのインポートが最後に正常に行われた日付になります。例: 2017 年 10 月 1 日から 2017 年 10 月31 日までのデータの取得 `URL?startdate=2017-10-01&enddate=2017-10-31`		Date
token	固有のユーザー認証 ID。認証トークンを取得するための REST API を使用して取得することができます。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-number> \| <json-null>` 注: `license_usage` REST API は、ネストされたフィルター条件をサポートしていません。例 1: 製品名に「BigFix」が含まれ、かつしきい値の差分が 0 未満のソフトウェア・インスタンスの取得 `URL?criteria={"and":[["product_name","contains","BigFix"], ["threshold_delta","<","0"] ] }` `threshold` および `custom_field_number` フィールドについては、この値が指定されている場合も、指定されていない場合も、すべてのエントリーを取得することができます。例 2: しきい値が指定されているソフトウェア製品の取得 `URL?criteria={"and":[["threshold","!=",]]}` 例 3: しきい値が指定されていないソフトウェア製品の取得 `URL?criteria={"and":[["threshold","=",]]}` 日付の値を使用する列を作成した場合、特定の日付の代わりにある期間のデータを取得することもできます。これを行うには、`last` または `next` を <operator> として使用し、次の規則で時刻の値を指定します。PxD/PxW/PxM/PxY。ここで、x は 1 から 999 の範囲の数値であり、D、W、M、Y はそれぞれ、日、週、月、年を表す指定子です。例 4: 使用権が次の月の間に終了するソフトウェア製品の取得 `URL?criteria={"and":[["custom_field_1","next","P1M"]]}` 演算子について詳しくは、以下を参照してください。「共通のコネクターおよび演算子」。		ストリング

会話例 - デフォルトの列

要求

GET api/sam/v2/license_usage?token=7adc3efb175e2bc0f4484bdd2efca54a8fa04623
Host: localhost:9081 
Accept: application/json 
Accept-Language: en-US

応答ヘッダー

Status Code: 200 OK
Content-Type: application/json
computerGroupId: 0
enddate: 2017-10-31
startdate: 2017-10-01

応答本文

[{

"product_publisher_name": "IBM",
"product_name": "WebSphere Service Registry and Repository",
"metric_code_name": "PVU_FULL_CAP",
"hwm_quantity": 480
}]

会話例 - すべての列

要求

GET api/sam/v2/license_usage?columns[]=product_id
&columns[]=product_name&columns[]=product_family_guid&columns[]=metric_id
&columns[]=metric_name&columns[]=metric_code_name&columns[]=hwm_quantity
&columns[]=threshold&columns[]=threshold_delta&columns[]=imported_part_numbers
&columns[]=is_reaggregation_needed&token=7adc3efb175e2bc0f4484bdd2efca54a8fa04623
Host: localhost:9081 
Accept: application/json 
Accept-Language: en-US

応答本文

[{

"product_publisher_name": "IBM",
"product_id": 29258,
"product_name": "WebSphere Service Registry and Repository",
"product_family_guid": "3b31a72e-468d-47bb-825a-ea26c8e85199",
"metric_id": 3,
"metric_code_name": "PVU_FULL_CAP",
"metric_name": "PVU Full Capacity",
"hwm_quantity": 480,
"threshold": null,
"threshold_delta": null,
"imported_part_numbers": null,
"is_reaggregation_needed": 0
"bundle_name": null, 
"bundle_type": -1,
"bundle_guid": null,
"bundle_metric_contribution": null
}]

会話例 - 追加の列

要求

GET api/sam/v2/license_usages?columns[]=product_name
&columns[]=metric_name&columns[]=threshold_delta
&token=7adc3efb175e2bc0f4484bdd2efca54a8fa04623
Host: localhost:9081 
Accept: application/json 
Accept-Language: en-US

応答本文

[{
"product_name": "WebSphere Service Registry and Repository",
"metric_name": "PVU Full Capacity",
"threshold_delta": 100
}]

会話例 - カスタム・フィールド

「すべてのメトリック」レポートに追加されたカスタム・フィールドからデータを取得するには、最初に license_usage.json スキーマを表示します。このスキーマには、カスタム・フィールドを含むすべての列がリストされます。データを取得するカスタム・フィールドを識別します。

要求 - 作成されたカスタム・フィールドのリストの確認

GET api/sam/v2/schemas/license_usage.json?token=7adc3efb175e2bc0f4484bdd2efca54a8fa04623

応答 - すべての列のリスト (カスタム・フィールドを含む)

[{
"product_name":
      {
       "type": "string",
       "description": "Name of the software product."
       },
...

"custom_field_1":
       {
       "type": "date",
       "title": "Entitlement End"
       }
}]

カスタム・フィールドの名前を識別した後、REST API 要求でそれを使用することができます。

要求

GET api/sam/v2/license_usages?columns[]=product_name
&columns[]=custom_field_1&token=7adc3efb175e2bc0f4484bdd2efca54a8fa04623
Host: localhost:9081 
Accept: application/json 
Accept-Language: en-US

応答本文

[{
"product_name": "WebSphere Service Registry and Repository",
"custom_field_1": "2017-10-01"
}]

対話の例 - FlexPoint バンドルと Cloud Pak に関する情報の取得

要求

GET api/sam/v2/license_usages?columns[]=product_name
&columns[]=bundle_name&columns[]=bundle_type&columns[]=bundle_metric_contribution
&token=7adc3efb175e2bc0f4484bdd2efca54a8fa04623&criteria={"and":[["bundle_type","in","[0,1]"]]}
Host: localhost:9081 
Accept: application/json 
Accept-Language: en-US

応答本文

[{
"product_name": "IBM WebSphere Application Server Network Deployment",
"bundle_name": "IBM Cloud Pak for Applications"
"bundle_type": "1"
"bundle_metric_contribution": "100"
}]