检索许可证度量利用率 (v2)

https://server_url:server_port/api/sam/v2/license_usage

表 1. 资源信息

操作详细信息	描述
HTTP 方法	GET
请求头	Accept-Language（可选） 使用: 用于协商响应的语言。 如果不指定该头，将以服务器语言返回内容。 值: en-US (仅支持英语) Token 使用: 用于认证 REST API 请求。 当您将 api_token_in_url_enabled 参数的值设置为 false时，头是必需的。 否则，可以在请求头或 URL中指定令牌。 更多信息，请参阅： 验证 REST API 请求。 值: 在 License Metric Tool 中生成的字母数字字符串
请求格式	application/json
响应头	Content-Type 使用: 指定响应的内容类型。 值： application/json Content-Language 使用: 指定响应内容的语言。 如果不指定该头，将以服务器语言返回内容。 值 :en-US ， ... startdate 使用: 指定从检索数据开始的日期。 值： YYYY-MM-DD enddate 使用: 指定检索数据的截止日期。 值： YYYY-MM-DD computerGroupId 使用: 指定要检索其数据的计算机组的标识。 值: 整数
响应有效内容	License Usage 元素
响应格式	application/json
响应码	200 – OK 如果查询参数包含错误或缺少 400 – “Bad Request”

要检索此 REST API 返回的所有列及其描述的列表，请使用以下请求。

GET https://server_url:server_port/api/sam/v2/schemas/license_usage.json

表 2. 可用栏目

列	描述	缺省情况下显示	类型
bundle_guid	产品分配到的 FlexPoint 捆绑软件或 Cloud Pak 的 GUID。		字符串
bundle_id	将产品分配到的 FlexPoint 捆绑软件或 Cloud Pak 的标识。		整数
bundle_metric_contribution	当产品是 FlexPoint 捆绑软件或 Cloud Pak的一部分时，该列显示特定产品对该产品所分配到的 FlexPoint 捆绑软件或 Cloud Pak 的总体度量数量所贡献的许可证度量单位数。 它是 hwm_quantity 列中的值乘以为特定产品指定的转换选项。 当产品不是 FlexPoint 捆绑软件或 Cloud Pak的一部分时，该列为空。		整数
bundle_name	将产品分配到的 FlexPoint 捆绑软件或 Cloud Pak 的名称。		字符串
bundle_type	捆绑软件的类型。 可能的值： - -1 - 不是捆绑销售 0- FlexPoint 捆绑软件 1- Cloud Pak		整数集
custom_field_编号	已添加到 "所有度量" 报告的定制字段。 要查看所有定制字段的列表，请查看 license_usage.json 模式。		各种
entitled	指示是否已将某个产品、Cloud Pak 或 FlexPoint 捆绑软件定义为您的软件权利（通过上载部件号或手动方式）。		布尔值
hwm_peak_time	在所选时间段内，产品使用最大度量单位数的日期和时间。 如果 hwm_quantity 参数的值为 -1 ，则 hwm_peak_time 的值毫无意义。 注: 检索 hwm_peak_time 可能会明显增加检索数据的时间。		字符串
hwm_quantity	产品在检索数据的时间段内使用的最大度量单位数。 当特定许可指标未测量公制数量时， hwm_quantity 参数返回的值为 -1。 -1 不能用于排序或过滤。	✓	整数
ibm_provided	指定产品可使用许可证度量的信息是来自 IBM 提供的软件目录还是手动添加的。 可能的值： 0 -来自 IBM 提供的软件目录的信息 1 -用户手动添加的信息		布尔值
imported_part_numbers	导入到 License Metric Tool的部件号。 它表示 product_name 列中列出的产品及其许可证度量。		字符串
is_hybrid	指示产品是只能部署在传统 VM 上，还是可以同时部署在传统 VM 和 Kubernetes 集群上。 如果这两个部署选项都可行，那么可能需要从 License Metric Tool 和 License Service组合累积许可证使用情况。 可能的值： 0 -只能在传统 VM 上安装软件 1 -可以在传统 VM 和 Kubernetes 集群上安装软件		布尔值
is_reaggregation_needed	指定产品是否需要重新计算。 该参数不能用于对结果进行过滤或排序。		布尔值
metric_code_name	许可证度量的代码名称。 有关返回值的解释，请参阅： 度量 ID 和代码名称。	✓	字符串
metric_id	许可证度量的标识。 有关返回值的解释，请参阅： 度量 ID 和代码名称。		字符串
metric_name	许可证度量的名称。 metric_name 参数返回的值作为参考提供，可能与 表 1中作为度量描述提供的值略有不同。 最好使用 metric_id 或 metric_code_name 参数来检索度量值，然后通过引用 表 1来检查准确的度量值描述。		字符串
product_bundle_ratio_divider	当产品是 FlexPoint 捆绑软件或 Cloud Pak的一部分时，该列将显示用于将产品许可证度量与捆绑软件的许可证度量进行转换的比率的除法器。 例如，当 IBM Security QRadar SOAR Users 作为 IBM Cloud Pak for Security 的一部分安装时，转换比率为 5:1。 在此情况下， product_bundle_ratio_divider 列的值将为 5。		整数
product_bundle_ratio_factor	当产品是 FlexPoint 捆绑软件或 Cloud Pak的一部分时，该列显示用于将产品许可证度量与捆绑软件的许可证度量进行转换的比率的因子。 例如，当 IBM Security QRadar SOAR Users 作为 IBM Cloud Pak for Security 的一部分安装时，转换比率为 5:1。 在此情况下， product_bundle_ratio_factor 列的值将为 1。		整数
product_family_guid	软件产品的 GUID。		字符串
product_id	软件产品的标识。		整数
product_name	软件产品的名称。	✓	字符串
ratio	表示如何将捆绑产品的许可证公制单位转换为 Cloud Pak 的公制单位。 数值显示格式如下： <integer>:<integer>. 例如，2:1。 如果产品是免费的，价值为 free。		字符串
threshold	产品有权在计算机组中使用的最大度量单位数。 该值手动设置，用于计算度量阈值变化量。		整数
threshold_delta	计算方法是从阈值中减去度量值数量。 为未计算的许可证度量指定阈值时， threshold_delta 参数返回的值为 2147483647。 值 2147483647 不能用于排序或过滤。		整数

表 3. 查询参数

参数	描述	必填	值
computerGroupId	指定要检索其数据的计算机组的标识。 如果未指定此参数，那么将检索其令牌用于认证的用户的计算机组的数据。 如果指定该参数，那么可以检索此计算机组的子组的数据。 要查看计算机组的 ID，请登录 License Metric Tool 并转到报告 > 计算机组。 然后，将鼠标悬停在 配置上，单击 配置视图，然后选择标识列以将其显示在报告上。 示例: 检索计算机组 5 的数据 URL?computerGroupId=5		整数
columns[]	指定要检索的列。 如果未指定此参数，那么将仅检索缺省列。 示例: 检索产品名称和阈值增量 URL?columns[]=product_name&columns[]=threshold_delta		字符串
order	指定如何对检索到的数据进行排序。 对列进行排序的缺省方向是升序。 如果要指定降序排序，请将 desc 附加到列名称。 示例: 按阈值增量排序 URL?order[]=threshold_delta desc		字母数字
limit	指定要检索的行数。 如果省略此参数，将检索所有的行。 示例: 检索 100 条记录 URL?limit=100		数值
offset	指定要为获取检索结果而跳过的行数。 可以将其与 limit 参数一起使用来对结果进行分页。 示例: 从记录 150 之后开始检索 50 条记录 URL?limit=50&offset=150		数值
startdate	指定要从中检索数据的日期。 以 YYYY-MM-DD 格式指定该值。 如果未指定过滤器，那么其缺省值为上次成功将数据导入到 License Metric Tool 的日期减去在计算机组中计算数据的天数 (缺省情况下为 90 天)。 例如检索从 2017 年 7 月 14 日开始的数据 URL?startdate=2017-07-14		日期
enddate	指定要检索数据的截止日期。 以 YYYY-MM-DD 格式指定该值。 如果未指定过滤器，那么其缺省值为上次成功将数据导入到 License Metric Tool的日期。 示例检索 2017 年 10 月 1 日至 2017 年 10 月 31 日的数据 URL?startdate=2017-10-01&enddate=2017-10-31		日期
criteria	检索与特定条件匹配的记录。 该参数应具有以下结构 (写在一行中): <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 https://server_url:server_port/api/sam/v2/license_usage

请求头

Accept: application/json 
Accept-Language: en-US
Token: <token>

响应头

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

响应主体

[{
 
"product_name": "WebSphere Service Registry and Repository",
"metric_code_name": "PVU_FULL_CAP",
"hwm_quantity": 480
}]

请求

GET https://server_url:server_port/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&columns[]=bundle_name&columns[]=bundle_type
&columns[]=bundle_guid&columns[]=bundle_metric_contribution
&columns[]=ibm_provided&columns[]=ratio

请求头

Accept: application/json 
Accept-Language: en-US
Token: <token>

响应主体

[{
"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,
"ibm_provided": 1,
"ratio": "free"
}]

请求

GET https://server_url:server_port/api/sam/v2/license_usage
?columns[]=product_name&columns[]=metric_name&columns[]=threshold_delta

请求头

Accept: application/json 
Accept-Language: en-US
Token: <token>

响应主体

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

要从已添加到 "所有度量" 报告的定制字段中检索数据，请从查看 license_usage.json 模式开始。 模式列出所有列，包括定制字段。 标识要从中检索数据的定制字段。

请求-已创建定制字段的检查列表

GET https://server_url:server_port/api/sam/v2/schemas/license_usage.json

请求头

Accept: application/json 
Accept-Language: en-US
Token: <token>

响应-所有列的列表，包括定制字段

[{
"product_name":
      {
       "type": "string",
       "description": "Name of the software product."
       },
...
 
"custom_field_1":
       {
       "type": "date",
       "title": "Entitlement End"
       }
}]

请求

GET https://server_url:server_port/api/sam/v2/license_usage
?columns[]=product_name&columns[]=bundle_name&columns[]=bundle_type&columns[]=bundle_metric_contribution
&ratio&criteria={"and":[["bundle_type","in","[0,1]"]]}

请求头

Accept: application/json 
Accept-Language: en-US
Token: <token>

响应主体

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