更新时间:2024-03-01 GMT+08:00

按标签查询镜像

功能介绍

该接口用于按标签或其他条件对镜像进行过滤或者计数使用。

约束与限制

为兼容遗留数据,使用tags、not_tags、tags_any、not_tags_any参数时,不对查询条件中标签的key、value进行字符集校验。

URI

POST /v2/{project_id}/images/resource_instances/action

参数说明请参见表1
表1 参数说明

参数

是否必选

参数类型

描述

project_id

String

项目ID

请求消息

  • 请求参数

    参数

    是否必选

    参数类型

    描述

    action

    String

    操作标识(区分大小写),支持filter、count。filter就是分页查询;count是只需按照条件将总条数返回即可。

    tags

    Array of objects

    包含标签,最多包含10个key,每个key对应的values最多包含10个值,且key和values都不能重复。不能为空列表。

    详情请参见表2

    tags_any

    Array of objects

    包含任意标签,最多包含10个key,每个key对应的values最多包含10个值,且key和values都不能重复。不允许为空列表,但可以不传递参数。

    详情请参见表3

    not_tags

    Array of objects

    不包含标签,最多包含10个key,每个key对应的values最多包含10个值,且key和values都不能重复。不能为空列表。

    详情请参见表4

    not_tags_any

    Array of objects

    不包含任意标签,最多包含10个key,每个key对应的values最多包含10个值,且key和values都不能重复。不能为空列表。

    详情请参见表5

    without_any_tag

    Boolean

    不包含任意一个标签,该字段为true时查询所有不带标签的资源,此时忽略tag、not_tags、tags_any、not_tags_any字段。

    limit

    String

    最大查询记录数(action为count时,此参数无效)。如果action为filter,则limit默认为10,最多为1000,不能为负数,最小值为1。

    offset

    String

    索引位置, 从offset指定的下一条数据开始查询。 查询第一页数据时,不需要传入此参数(action为count时,此参数无效),如果action为filter,offset默认为0,不能为负数。

    matches

    Array of objects

    搜索字段,key为要匹配的字段,如resource_name、resource_id等。value为匹配的值。多个matches的key不允许重复。不允许为空列表,但可以不传递参数。

    详情请参见表6

    表2 tags字段数据结构说明

    参数

    是否必选

    参数类型

    描述

    key

    String

    标签的键。最大长度127个unicode字符,key不能为空。

    values

    Array of strings

    标签的值列表。每个值最大长度255个unicode字符,如果values为空列表,则标签的值可以是任意值。值列表中的值之间为或的关系。

    表3 tags_any字段数据结构说明

    参数

    是否必选

    参数类型

    描述

    key

    String

    标签的键。最大长度127个unicode字符,key不能为空。

    values

    Array of strings

    标签的值列表。每个值最大长度255个unicode字符,如果values为空列表,则标签的值可以是任意值。值列表中的值之间为或的关系。

    表4 not_tags字段数据结构说明

    参数

    是否必选

    参数类型

    描述

    key

    String

    标签的键。最大长度127个unicode字符,key不能为空。

    values

    Array of strings

    标签的值列表。每个值最大长度255个unicode字符,如果values为空列表,则标签的值可以是任意值。值列表中的值之间为或的关系。

    表5 not_tags_any字段数据结构说明

    参数

    是否必选

    参数类型

    描述

    key

    String

    标签的键。最大长度127个unicode字符,key不能为空。

    values

    Array of strings

    标签的值列表。每个值最大长度255个unicode字符,如果values为空列表,则标签的值可以是任意值。值列表中的值之间为或的关系。

    表6 matches字段数据结构说明

    参数

    是否必选

    参数类型

    描述

    key

    String

    搜索的字段名称。合法值为resource_name、resource_id。

    当字段名称为resource_name时,如果value为空字符串,做精确查询,否则按镜像名称全模糊查询。当字段名称为resource_id时,按镜像ID精确查询。

    value

    String

    搜索的字段名称的对应值,不允许为空。每个值最大长度255个unicode字符。

请求示例

  • 按照标签和总条数返回查询条件,查询镜像。
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    POST https://{Endpoint}/v2/fd73a4a14a4a4dfb9771a8475e5198ea/images/resource_instances/action
    {
       "action": "count",
       "matches": [{
          "key": "resource_name",
          "value": "test100"
       }],
       "tags": [
       {
          "key": "key3",
          "values": ["valueXX"]
       }],
       "tags_any": [
       {
          "key": "key0",
          "values": ["valueXX"]
       }],
          "not_tags": [
       {
          "key": "key9",
          "values": ["value9"]
       }],
       "not_tags_any": [{
          "key": "key7",
          "values": ["value7"]
       }]
    }
    
  • 按照标签和分页查询条件,查询镜像。
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    POST https://{Endpoint}/v2/fd73a4a14a4a4dfb9771a8475e5198ea/images/resource_instances/action
    {
       "action": "filter",
       "limit": "1",
       "offset": "0",
       "matches": [{
          "key": "resource_name",
          "value": "test100"
       }],
       "tags": [
       {
          "key": "key3",
          "values": ["valueXX"]
       }],
       "tags_any": [
       {
          "key": "key0",
          "values": ["valueXX"]
       }],
       "not_tags": [
       {
          "key": "key9",
          "values": ["value9"]
       }],
       "not_tags_any": [{
          "key": "key7",
          "values": ["value7"]
       }]
    }
    

响应消息

  • 响应参数

    参数

    参数类型

    描述

    resources

    Array of resource objects

    镜像信息列表

    total_count

    Integer

    总记录数

    表7 resource字段数据结构说明

    参数

    参数类型

    描述

    resource_id

    String

    镜像ID

    resource_detail

    ResourceDetail object

    镜像详情

    tags

    Array of Tags objects

    镜像的标签列表

    resource_name

    String

    镜像名称

    表8 ResourceDetail object

    名称

    类型

    必选

    描述

    status

    string

    镜像状态

    表9 resource_tag字段数据结构说明

    参数

    参数类型

    描述

    key

    String

    标签的键

    value

    String

    标签的值

  • 响应样例
    • action为count时的响应示例
      STATUS CODE 200
      1
      2
      3
      {
         "total_count": 36
      }
      
    • action为filter时的响应示例
      STATUS CODE 200
       1
       2
       3
       4
       5
       6
       7
       8
       9
      10
      11
      12
      13
      14
      15
      16
      17
      18
      19
      20
      21
      22
      23
      24
      25
      26
      27
      28
      29
      30
      31
      32
      33
      34
      35
      36
      37
      38
      39
      40
      41
      42
      43
      44
      45
      46
      47
      48
      {
         "total_count": 36,
         "resources": [{
            "resource_name": "test10002",
            "resource_detail": {"status": "active"},
            "tags": [{
               "value": "value4",
               "key": "key4"
            },
            {
               "value": "valueXX",
               "key": "key3"
            },
            {
               "value": "value2",
               "key": "key2"
            },
            {
               "value": "value5",
               "key": "key5"
            },
            {
               "value": "value8",
               "key": "key8"
            },
            {
               "value": "valueXX",
               "key": "key6"
            },
            {
               "value": "valueXX",
               "key": "key0"
            },
            {
               "value": "value1",
               "key": "key1"
            },
            {
               "value": "value7",
               "key": "key7"
            },
            {
               "value": "valueXX",
               "key": "key9"
            }],
            "resource_id": "8693187d-1590-4f9f-ae34-eb9e3037cf68"
         }]
      }
      

返回值

  • 正常

    200

  • 异常

    返回值

    说明

    400 Bad Request

    请求错误。

    401 Unauthorized

    鉴权失败。

    403 Forbidden

    没有操作权限。

    404 Not Found

    找不到资源。

    500 Internal Server Error

    服务内部错误。

    503 Service Unavailable

    服务不可用。