按标签查询专属主机列表 - ListDedicatedHostsByTags

功能介绍

使用标签过滤专属主机列表，并返回专属主机使用的所有标签。

标签管理服务（TMS）使用该接口过滤专属主机列表。

调试

您可以在API Explorer中调试该接口。

授权信息

账号具备所有API的调用权限，如果使用账号下的IAM用户调用当前API，该IAM用户需具备调用API所需的权限，具体权限要求请参见权限和授权项。

URI

POST /v1.0/{project_id}/dedicated-host-tags/resource_instances/action

参数说明请参见表1。

表1 参数说明
参数	参数类型	是否必选	描述
project_id	String	是	项目ID。

请求消息

表2 请求参数
参数	参数类型	是否必选	描述
tags	Array of objects	否	查询包含所有指定标签的专属主机。更多信息，请参见表3。最多包含10个key，每个key下面的value最多10个。结构体不能缺失。 key不能为空或者空字符串。 key不能重复。同一个key中value不能重复。
not_tags	Array of objects	否	查询不包含所有指定标签的专属主机。更多信息，请参见表3。最多包含10个key，每个key下面的value最多10个。结构体不能缺失。 key不能为空或者空字符串。 Key不能重复。同一个key中value不能重复。
limit	Integer	否	查询返回的专属主机数量限制，最多为1000，不能为负数。如果action的值为count，此参数无效。如果action的值为filter，limit默认为1000。
offset	Integer	否	索引位置，从offset指定的下一条数据开始查询。必须为数字，不能为负数。查询第一页数据时，不需要传入此参数。查询后续页码数据时，将查询前一页数据时响应体中的值带入此参数。如果action的值为count，此参数无效。如果action的值为filter，offset默认为0。
action	String	是	操作标识，包括filter和count两种。 filter：表示按标签过滤专属主机，返回符合条件的专属主机列表。此时，为分页查询。 count：表示按标签搜索专属主机，返回符合条件的专属主机个数。
tags_any	Array of objects	否	包含任意标签。更多信息，请参见表3。最多包含10个key，每个key下面的value最多10个，每个key对应的value可以为空数组但结构体不能缺失。 key不能重复，同一个key中value不能重复。结果返回包含标签的资源列表，key之间是“或”的关系，key-value结构中value是“或”的关系。无过滤条件时返回全量数据。
not_tags_any	Array of objects	否	不包含任意标签。更多信息，请参见表3。最多包含10个key，每个key下面的value最多10个，每个key对应的value可以为空数组但结构体不能缺失。 key不能重复，同一个key中value不能重复。结果返回不包含标签的资源列表，key之间是“或”的关系，key-value结构中value是或的关系。无过滤条件时返回全量数据。
matches	Array of objects	否	搜索字段，用于按条件搜索专属主机。当前仅支持按resource_name进行搜索。更多信息，请参见表4。

表3 tag字段数据结构说明
参数	参数类型	是否必选	描述
key	String	是	键。最大长度127个unicode字符。 key不能为空。
values	Array of strings	否	值列表。最多10个value。 value不允许重复。每个值最大长度255个unicode字符。如果value缺失则表示any_value。 value之间为“或”的关系。

表4 match字段数据结构说明
参数	参数类型	是否必选	描述
key	String	是	键，表示要匹配的字段。 key不能重复，value为匹配的值。此字段为固定字典值。不允许为空字符串。说明：当前key的参数值仅支持resource_name，此时value的参数值为专属主机名称。
value	String	是	值。每个值最大长度为255个unicode字符。不可以为空。

响应消息

表5 响应参数
参数	参数类型	描述
resources	Array of objects	返回的专属主机列表，详情参见表6。
total_count	Integer	总记录数。

表6 resource字段数据结构说明
参数	参数类型	描述
resource_id	String	专属主机ID。
resource_detail	String	专属主机详情。该字段用于后续扩展，默认为空。
tags	Array of objects	标签列表。详见表表7。
resource_name	String	资源名称。

表7 tag字段数据结构说明
参数	参数类型	描述
key	String	键。最大长度36个unicode字符。 key不能为空。不能包含以下ASCII非打印字符：“=”,“*”,“<”,“>”,“\”,“\|”,“/”,“,”。
value	String	值。每个值最大长度43个unicode字符。可以为空字符串。不能包含以下ASCII非打印字符： “=”,“*”,“<”,“>”,“\”,“\|”,“/”,“,”。

请求示例

按标签查询专属主机列表，按标签过滤专属主机，从第一条数据开始查询，搜索名称为resource1的专属主机，标签键为key1值为value1。

POST https://{Endpoint}/v1.0/9c53a566cb3443ab910cf0daebca90c4/dedicated-host-tags/resource_instances/action 
{ 
    "offset": "0",
    "limit": "100",
    "action": "filter",
    "matches": [
        {
            "key": "resource_name",
            "value": "resource1"
        }
    ],
    "tags": [
        {
            "key": "key1",
            "values": ["value1"]
        }
    ]
}

响应示例

action为filter时的响应体：

{
    "resources": [
        {
            "resource_detail": null,
            "resource_id": "cdfs_cefs_wesas_12_dsad",
            "resource_name": "resource1",
            "tags": [
                {
                    "key": "key1",
                    "value": "value1"
                }
            ]
        }
    ],
    "total_count": 1
}

action为count时的响应体：