使用“资源组管理服务”API

使用资源组管理服务 API 可以从命令行管理受管系统组的生命周期。

关于此任务

完成资源组任务，例如创建、查看、更新和删除受管系统组。对定制组添加和移除各个系统。查看已添加到特定定制资源组的系统列表，以及查看自动添加到内置组（例如，系统资源组）的系统列表。

您可以创建脚本来自动执行一些任务，例如，定义资源组以及将代理程序分配到这些资源组。资源组可以是阈值分布和/或访问控制策略的目标。

在该任务中，可以在 curl 命令中使用访问令牌或基本授权：

访问令牌: 使用 OpenID Connect (OIDC) 协议从Cloud APM 服务器上的 OIDC 服务器获取访问令牌。访问令牌使您能够对 API 进行授权访问，以便在 30 分钟后令牌到期之前运行操作。

基本授权

使用 base64 工具将 Cloud APM 控制台用户标识和密码编码为单个 base64 字符串。输入字符串格式为 userId:password，如 apmadmin:apmpass。输出为字符串，例如：YXBtYWRtaW46YXBtcGFzcw==!

在每个请求的授权头中使用 base64_encoded_string，如 curl 命令示例所示。

请注意，必须将 Cloud APM 控制台用户标识添加到具有适当许可权的角色。

您可在 API Explorer 中以及本主题末尾的“示例”中找到有关下列操作的描述。

返回所有资源组、代理程序，或特定资源组或代理程序。
创建定制资源组或更新现有组的定义
删除指定的定制资源组
将代理程序添加到定制资源组
从定制资源组中移除代理程序

禁用 OIDC 认证（在 Cloud APM 与需要 LTPA 以用于单点登录 (SSO) 的其他 IBM® 产品（例如 Tivoli® Common Reporting）之间启用单点登录之前，需要此认证）并不会影响此 API。RESTful API 继续使用 Cloud APM 内部 OIDC 服务器，即使在 Cloud APM 控制台与其他产品用户界面之间禁用 OIDC 单点登录也是如此。

过程

完成以下步骤以使用“资源组管理服务”API 定义和更改定制资源组。不能修改系统资源组和代理程序。

在安装 Cloud APM 服务器的系统上，打开以下文件并复制 client.secret.apmui 和 client.id.apmui 变量的值：

install_dir/wlp/usr/shared/config/clientSecrets.xml

以下示例显示此文件包含的内容：

<server>
  <variable name="client.secret.apmui" value="{xor}J2oZKWQsHXVxeCJwBGscfQ40d2N+cBUPZmltKRNz" />
  <variable name="client.id.apmui" value="rpapmui" />
</server>

可选：如果计划在 curl 命令中使用访问令牌，请使用 XOR 解码器来解码 client.secret.apmui 变量的值以获取实际密钥值。
例如，在使用 XOR 解码器来解码 J2oZKWQsHXVxeCJwBGscfQ40d2N+cBUPZmltKRNz 时，获得以下值：x5Fv;sB*.'}/[4C"Qk(<!/JP962vL
可选：如果计划在 curl 命令中使用访问令牌，那么请完成此步骤。要获取访问令牌，请使用下列 4 个必需项与 Cloud APM OIDC 服务器的令牌端点联系：username、password、client_id 和 client_secret，如以下命令中所示：
```
curl --tlsv1.2 -v -k -d "grant_type=password&client_id=rpapmui&client_secret=x5Fv;sB*.'}/[4C"Qk(<!/JP962vL&username=apmadmin&password=apmpass&scope=openid" https://example.mycompany.com:8099/oidc/endpoint/OP/token
```
其中：
- username 是 Cloud APM 控制台用户的用户名
- password 是 Cloud APM 控制台用户的密码
- clientid 是来自步骤 1 的 client.id.apmui 变量的值。
- client_secret 是 XOR 解码器在步骤 2 中创建的值。
输出：
```
{"access_token":"jnz4Ad0zpeCpYcUlUf7o4A40tz5trnIW9GutICG8","token_type":"Bearer","expires_in":1800,"scope":"openid","refresh_token":"VsCWUhPHBRpidD2F1PVyZ2LNGMuQPTN837t3OoqZj71FcBfsGE"}
```
可选：如果计划在 curl 命令中使用访问令牌，请抽取 access_token 值。
在上一示例的输出中，可以看到值为 jnz4Ad0zpeCpYcUlUf7o4A40tz5trnIW9GutICG8。

使用访问令牌或基本授权输入对资源组管理服务 API 的请求。

访问令牌示例

curl --tlsv1.2 -v -k --request GET --url 
'http://myAPMServer.mycompany-domain.com:8090/1.0/topology/mgmt_artifacts' 
--header 'authorization: Bearer  jnz4Ad0zpeCpYcUlUf7o4A40tz5trnIW9GutICG8'
--header 'content-type: application/json'

基本授权示例：

curl --tlsv1.2 -v -k --request GET --url 
'http://myAPMServer.mycompany-domain.com:8090/1.0/topology/mgmt_artifacts'  
--header 'authorization: Basic YXBtYWRtaW46YXBtcGFzcw==!' 
--header 'content-type: application/json'

有关 API 操作的更多详细信息，请参阅 API Explorer 中的 API 文档。有关访问 API Explorer 的指示信息，请参阅探查 API。

注：实例中所示的部分 URL 内容以及某些标头仅为 Cloud APM 所必需。例如：https://api.ibm.com/perfmgmt/run、x-ibm-service-location、X-IBM-Client-Id 和 X-IBM-Client-Secret。请参阅步骤 5 以获取请求示例。
必须在所有的 POST、PUT 和 DELETE 请求中包括 referer 标头。Referer 标头的值如下所示：
```
-H 'Referer: http://apm_server:8090'
```
其中，apm_server 是 Cloud APM 服务器的 IP 地址或标准主机名称。

结果

您在 API 中对定制资源组所做的更改会立即生效，并显示在“资源组管理器”中（请参阅资源组管理器）。

示例

此命令返回所有代理程序的名称、唯一标识、状态、主机名、版本和代理程序类型：

GET /1.0/topology/mgmt_artifacts?_filter=entityTypes=Agent&_field=keyIndexName&_field=online&_field=hostname&_field=version&_field=productCode&_field=description

此命令将返回所有 Linux OS 代理程序的列表：

GET /1.0/topology/mgmt_artifacts?_filter=entityTypes=Agent&_filter=description="Linux OS"&_field=keyIndexName

此命令返回系统和定制组的列表：

GET /1.0/topology/mgmt_artifacts?_filter=entityTypes:AgentGroup,AgentSystemGroup&_field=keyIndexName&_field=displayLabel

此命令返回代理程序的列表，它们将分配给具有唯一标识 {id} 的组：

GET /1.0/topology/mgmt_artifacts/{id}/references/to/contains

以下示例使用 curl 命令创建定制组。

POST /1.0/topology/mgmt_artifacts

注： POST 请求的主体必须包含定义该组的 JSON 对象，如 -d 参数所示。

curl -X POST \
  http://apm_server:8090/1.0/topology/mgmt_artifacts \
  -H 'Referer: http://apm_server:8090' \
  -H 'authorization: Bearer Your_Access_Token' \
  -H 'content-type: application/json' \
  -d '{
  "keyIndexName": "customGroup",
  "description": "Custom group description",
  "displayLabel": "customGroupLabel",
  "entityTypes": [
    "AgentGroup"
  ],
  "arbitraryStringProperty": "Your custom property value"
}'

此命令将具有唯一标识 {otherid} 的代理程序添加到具有唯一标识 {id} 的定制组：

POST /1.0/topology/mgmt_artifacts/{id}/references/to/contains/{otherid}

此命令从具有唯一标识 {id} 的定制组中移除具有唯一标识 {otherid} 的代理程序：

DELETE /1.0/topology/mgmt_artifacts/{id}/references/to/contains/{otherid}