检索软件库存 (v2)

在线编辑

9.2.8 可查阅 9.2.8。 您可以在 api/sam/v2/software_instances 元素上使用 GET 操作来请求有关基础设施中安装的软件的信息。 API 将返回现有组件的详细信息以及有关已除去组件的历史数据。

许可权

用户 您必须拥有 "查看端点 "和 "查看硬件库存 "权限才能使用此 API。

资源 URL

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

资源信息

表 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 ， ...
响应有效内容 Software Instances 元素
响应格式 application/json
响应码

200 – OK

500 – “Bad Request”，如果查询参数包含错误或缺失

模式描述

要检索此 REST API 返回的所有列及其描述的列表，请使用以下请求。
GET https://server_url:server_port/api/sam/v2/schemas/software_instance.json

可用列

表 2. 可用栏目
列 描述 缺省情况下显示 类型
9.2.13 bundle_id 捆绑软件实例的 FlexPoint 产品或 CloudPak 的标识。 可能值包括：
  • -1-无法将软件实例分配给任何 FlexPoint 产品或 Cloud Pak ，因为该组件未分配给任何产品
  • 0-软件实例未捆绑到任何 FlexPoint 产品或 Cloud Pak
  • 其他值-将软件实例分配到的 FlexPoint 产品或 Cloud Pak 的标识
 字符串
9.2.26 bundle_guid
向其分配软件实例的 FlexPoint 产品或 Cloud Pak 的 GUID。 可能值包括：
  • 空列-软件实例未捆绑到任何 FlexPoint 产品或 Cloud Pak
  • 其他值-将软件实例分配到的 FlexPoint 产品或 Cloud Pak 的 GUID
 字符串
9.2.13 bundle_name 向其分配软件实例的 FlexPoint 产品或 CloudPak 的名称。 可能值包括：
  • 空列-无法将软件实例分配给任何 FlexPoint 产品或 Cloud Pak ，因为该组件未分配给任何产品
  • None -软件实例未捆绑到任何 FlexPoint 产品或 Cloud Pak
  • 其他值-将软件实例分配到的 FlexPoint 产品或 Cloud Pak 的名称
 字符串
9.2.21 bundle_type 将软件实例分配到的捆绑软件的类型。 可能值包括：
  • --1- 软件实例未分配给任何捆绑包，或由于组件未分配给任何产品而无法分配
  • 0- FlexPoint 捆绑软件
  • 1- Cloud Pak 捆绑软件
 数值
9.2.11 component_detailed_version 基于导致其检测的最高 SWID 标记的组件版本。 字符串
component_name 组件名称。 ✓ 字符串
component_publisher_name 组件发布程序。 字符串
component_release 组件发行版号。 ✓ 字符串
computer_bigfix_id 中定义的计算机标识符。 BigFix®.对于断开连接的计算机，该值未定义。 数值
computer_dns_name 计算机的 DNS。 字符串
computer_group_id 计算机所属的 License Metric Tool 计算机组的标识。 值 0 代表“所有计算机”组。 数值
computer_id 计算机的标识，如 License Metric Tool中所定义。 数值
computer_ip_address 计算机的 IP 地址。 ✓ 字符串
computer_name 计算机的名称。 ✓ 字符串
computer_os 计算机的操作系统。 字符串
computer_os_type 计算机的操作系统类型。 字符串
9.2.25 disconnected_endpoint_id 在断开连接的扫描程序文件夹中的 config/endpoint_id.txt 文件中定义的断开连接的计算机的标识。 对于未向断开连接的数据源报告的计算机，该值为空。 字符串
discoverable_family_guid 组件系列 GUID。 例如，如果组件是 IBM DB2 Enterprise Server Edition，那么组件系列是 IBM DB2。 字符串
discoverable_guid 组件 GUID。 字符串
discovery_end 上次报告组件的日期和时间。 此时间是以 GMT 时区指定。 ✓ 字符串
discovery_path 组件的安装路径。 ✓ 字符串
discovery_start 首次报告组件的日期和时间。 此时间是以 GMT 时区指定。 ✓ 字符串
exclusion_or_suppress_comment 在排除或禁止期间提供的注释。 字符串
instance_id 组件实例的标识。

9.2.42从应用程序更新 9.2.42 开始，该列默认显示。

 数值
9.2.14 is_charged 有关组件到产品分配是否收费的信息。 布尔值
is_confirmed 确认是否将组件分配给产品的信息。 布尔值
9.2.21 is_entitled 是否将特定产品声明为软件权利的信息。 布尔值
is_excluded 是否从定价计算中排除产品的信息。 布尔值
is_present 有关组件是否仍安装在环境中的信息。 布尔值
is_suppressed 是否在安装了该组件的计算机上禁止该组件的信息。 ✓ 布尔值
metric_code_name 产品所使用的许可证度量的唯一代码名称。 有关每个指标的含义信息 metric_code_name，请参阅： 指标ID与代码名称。 字符串
metric_id 产品所使用的许可证度量的标识。 有关每个指标的含义信息 metric_id，请参阅： 指标ID与代码名称。 字符串
product_family_guid 产品系列 GUID。 例如，如果产品发行版为 IBM DB2 Enterprise Server Edition 10.5，那么产品为 IBM DB2 Enterprise Server Edition。
注: 从应用程序更新 9.2.26开始，不推荐使用该列并将其替换为 product_guid 列。
 字符串
9.2.26 product_guid 产品 GUID。 例如，如果产品发行版为 IBM DB2 Enterprise Server Edition 10.5，那么产品为 IBM DB2 Enterprise Server Edition。 字符串
product_name 将组件分配到的产品的名称。 ✓ 字符串
product_publisher_name 产品发布者。 字符串
product_release 产品发行版号。 ✓ 字符串
product_release_guid 产品发行版 GUID。 字符串
product_release_name 将组件分配到的产品发行版的名称。 字符串
9.2.40 ratio 表示如何将捆绑产品的许可证公制单位转换为 Cloud Pak 的公制单位。 数值显示格式如下： <integer>:<integer>. 例如，2:1。 如果产品是免费的，价值为 free。 字符串

适用的关联

您还可以从以下关联中检索数据:
重要信息: 所有关联都提供有关基础结构中当前存在的项的数据。 对于已除去的计算机和已卸载的软件，这些关联将返回 null。

查询参数

表 3. 查询参数
参数 描述 必填 值
columns[] 指定要检索的列。 如果未指定此参数，那么将仅检索缺省列。
示例: 检索产品名称和发行版
URL?columns[]=product_name&columns[]=product_release
 字符串
order 指定如何对返回的数据排序。 对列进行排序的缺省方向是升序。 如果要指定降序排序，请将 desc 附加到列名称。
示例: 按计算机标识降序排序
URL?order[]=computer_id desc
 字母数字
limit 指定要检索的行数。 如果省略此参数，将检索所有的行。
示例: 检索 100 条记录
URL?limit=100
 数值
offset 指定要为获取检索结果而跳过的行数。 您可以将其与用于对结果编写页码的限制参数一起使用。
示例: 从记录 150 之后开始检索 50 条记录
URL?limit=50&offset=150
 数值
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>

有关运算符的更多信息，请参阅： 常用连接符和运算符。

示例检索产品名称包含"BigFix"或发现开始时间在特定日期范围内的软件实例
URL?criteria={ "or": [ ["product_name", "contains", "BigFix"], 
{ "and": [ ["discovery_start", ">", "2018-10-01T00:00:00+00:00Z"], 
["discovery_start", "<", "2018-10-02T00:00:00+00:00Z"] ] } ] }

对于使用日期和时间值的列，您还可以检索时间段 (而不是特定日期) 的数据。 要执行此操作，请使用 last 或 next 作为 <operator>，然后按以下约定指定时间值：PxD/PxW/PxM/PxY，其中，x 是 1-999 之间的数字，D、W、M 和 Y 是指示符，分别表示日、周、月和年。

示例: 检索参与许可证利用率峰值的软件实例。 峰值的日期和时间为: 2018-10-10T00:00:00+00:00Z。 查询将搜索满足以下条件的实例: 产品名称包含 "DB2" ，并且使用在峰值范围内开始的给定度量和发现。

处理器价值单元、 资源价值单元管理的已激活处理器内核和虚拟处理器内核
URL?criteria={ "and": [ ["discovery_start", "<=", "2018-10-10T00:00:00+00:00Z"], 
["discovery_end", ">", "2018-10-10T00:00:00+00:00Z"], ["product_name", "contains", "DB2"], ["metric_id", "=", "5"] ] }
对于其他度量值
URL?criteria={ "and": [ ["discovery_start", "<", "2018-10-11T00:00:00+00:00Z"], 
["discovery_end", ">=", "2018-10-10T00:00:00+00:00Z"], ["product_name", "contains", "DB2"], ["metric_id", "=", "9"] ] }
示例: 检索在过去 7 天内首次报告的软件实例
URL?criteria={"and":[["discovery_start","last","P7D"]]}
 字符串

示例对话-缺省列

请求
GET https://server_url:server_port/api/sam/v2/software_instances
请求头
Accept: application/json 
Accept-Language: en-US
Token: <token>
响应主体
[{
"computer_name":"<name>",
"computer_ip_address":["<ip_address>"],
"component_name":"IBM Endpoint Manager Platform Agent",
"component_release":"9.0",
"is_present":1,
"discovery_start":"2016-04-28T15:37:26Z",
"discovery_end":"2016-11-17T15:11:10Z",
"discovery_path":"/opt/BESClient/bin/properties/version",
"product_name":"IBM Endpoint Manager for Power Management",
"product_release":"9.0"
}]

示例 conversation-all 列

请求
GET https://server_url:server_port/api/sam/v2/software_instances?columns[]=discovery_path
&columns[]=instance_id&columns[]=computer_id&columns[]=computer_bigfix_id
&columns[]=computer_dns_name&columns[]=computer_group_id&columns[]=computer_name
&columns[]=computer_ip_address&columns[]=computer_os&columns[]=computer_os_type
&columns[]=component_name&columns[]=component_release&columns[]=disconnected_endpoint_id
&columns[]=discoverable_guid&columns[]=component_publisher_name&columns[]=is_present
&columns[]=discovery_start&columns[]=discovery_end&columns[]=product_name
&columns[]=product_publisher_name&columns[]=product_release_name&columns[]=product_release
&columns[]=metric_id&columns=columns=metric_code_name&columns[]=is_confirmed
&columns[]=is_excluded&columns[]=is_suppressed&columns[]=exclusion_or_suppress_comment
&columns[]=ratio
请求头
Accept: application/json 
Accept-Language: en-US
Token: <token>
响应主体
[{
"instance_id":1,
"computer_id":3,
"computer_bigfix_id":null,
"computer_dns_name":"<name>",
"computer_group_id":0,
"computer_name":"<name>",
"computer_ip_address":"<ip_address>",
"computer_os":"AIX 5.3",
"computer_os_type":"AIX",
"component_name":"IBM Endpoint Manager Platform Agent",
"component_release":"9.0",
"disconnected_endpoint_id":5,
"discoverable_guid":"0768FB15-383C-4124-A7E2-0D76DDA06874",
"component publisher name":"IBM",
"is_present":0,
"discovery_start":"2016-04-28T15:37:26Z",
"discovery_end":"2016-11-17T15:11:10Z",
"discovery_path":"/opt/BESClient/bin/properties/version",
"product_name":"IBM Endpoint Manager for Power Management",
"product_publisher_name":"IBM",
"product_release_name":"IBM Endpoint Manager for Power Management",
"product_release":"9.0",
"metric_id":"6",
"metric_code_name":"INTERNAL_RVU_MAPC",
"is_confirmed":0,
"is_excluded":0,
"is_suppressed":0,
"exclusion_or_suppress_comment":null
"ratio":"free"
}]

示例对话-附加列

请求
GET https://server_url:server_port/api/sam/v2/software_instances?columns[]=discovery_path
&columns[]=component_name&columns[]=product_name&columns[]=is_confirmed
请求头
Accept: application/json 
Accept-Language: en-US
Token: <token>
响应主体
[{
"component_name":"IBM Endpoint Manager Platform Agent",
"product_name":"IBM Endpoint Manager for Power Management",
"is_confirmed":0
}]

示例对话-关联

请求
GET https://server_url:server_port/api/sam/v2/software_instances
?columns[]=computer_id&columns[]=computer_health.catalog_version
请求头
Accept: application/json 
Accept-Language: en-US
Token: <token>
响应主体
[{
"computer_id":1,
"catalog_version":1304630
}]