• Key Management Service

kms
  1. Help Center
  2. Key Management Service
  3. API Reference
  4. APIs
  5. Querying CMK Instances

Querying CMK Instances

Function

This API allows you to query CMK instances.

You can use the tag filtering function to query the detailed information about a specified CMK.

URI

  • URI format

    POST /v1.0/{project_id}/kms/resource_instances/action

  • Parameter description

    Parameter

    Type

    Mandatory

    Description

    project_id

    string

    Yes

    Project ID

Requests

Request parameters

Parameter

Type

Mandatory

Description

tags

JSONArray

No

list of tags, including tag keys and tag values.
  • key indicates the tag key. a CMK can have a maximum of 10 keys, and each of them is unique and cannot be empty. A key cannot have duplicate values. The value of key contains a maximum of 36 characters.
  • value indicates the tag value. Each tag value can contain a maximum of 43 characters. The relationship between values is AND.

limit

string

No

Number of queried records. If action is set to count, this parameter does not need to be set. If action is set to filter, the default value is 10.

The value ranges from 1 to 1000.

offset

string

No

Index location. The query starts from the next piece of data indexed by this parameter. When data on the first page is queried, the value of this parameter queried on previous page is contained. If action is count, this parameter does not need to be set. If action is set to filter, the default value is 0.

The value must be a numeral and cannot be a negative number.

action

string

Yes

Operation ID, which can be set to filter or count.

  • filter: indicates filtering.
  • count: indicates the number of queried records.

matches

JSONArray

No

Search field.

  • key indicates the field to be matched, for example, resource_name.
  • value indicates the value to be matched, which contains a maximum of 255 characters and cannot be empty.

sequence

string

No

36-byte serial number of a request message

Example: 919c82d4-8046-4722-9094-35c3c6524cff

Responses

  • Response parameters

    Parameter

    Type

    Mandatory

    Description

    resources

    JSONArray

    Yes

    Resource instance list

    total_count

    Integer

    Yes

    Total number of records

  • Description of the resource field

    Parameter

    Type

    Mandatory

    Description

    resource_id

    string

    Yes

    Resource ID

    resource_detail

    string

    Yes

    Resource details. JSON character string. For details, see responses in Querying the Information About a CMK.

    tags

    JSONArray

    Yes

    Lists of tags. If there is no tag, the array is empty by default.

    resource_name

    string

    Yes

    Resource name. This parameter is an empty string by default.

Examples

The following example describes how to query key instances.

  • Example request
       {
              "offset": "100", 
              "limit": "100", 
              "action": "filter", 
              "matches":[
              {
                       "key": "resource_name", 
                       "value": "resource1"
                    }
               ], 
              "tags": [
                   {
                       "key": "key1", 
                       "values": [
                                "value1", 
                                "value2"
                       ]
                   }
              ]
         }
  • Example response
    { 
     "resources": [{
           "resource_id": "90c03e67-5534-4ed0-acfa-89780e47a535",
           "resource_detail": {
                  "key_id": "90c03e67-5534-4ed0-acfa-89780e47a535",
                  "domain_id": "4B688Fb77412Aee5570E7ecdbeB5afdc",
                  "key_alias": "tagTest_xmdmi",
                  "key_description": "123",
                  "creation_date": 1521449277000,
                  "scheduled_deletion_date": "",
                  "key_state": 2,
                  "default_key_flag": 0,
                  "key_type": 1
           },
           "resource_name": "tagTest_xmdmi",
           "tags": [{
                  "key": "$",
                  "value": "testValue!"
           }, {
                  "key": "1",
                  "value": "ccwZ"
           }, {
                  "key": "1&",
                  "value": "testValue!"
           }, {
                  "key": "abcd",
                  "value": "1&"
           }, {
                  "key": "efg",
                  "value": "1&"
           }, {
                  "key": "faregbqer",
                  "value": "AAaa00-99"
           }, {
                  "key": "fcwefwq",
                  "value": "$"
           }, {
                  "key": "fwqegqwrg",
                  "value": "1&"
           }, {
                  "key": "haha",
                  "value": "qzzahnzgoqbkabppdehnbrrgbrkvlxkkfoosqyhdylq"
           }, {
                  "key": "quapxpysduboguiluwargcgmvcgxinianbhl",
                  "value": "testValue!"
           }]
     }]
     "total_count": "1"}

    or

    {     
           "error": {        
           "error_code": "KMS.XXXX",         
           "error_msg": "XXX"     
            }
     }

Status Codes

Table 1 lists the normal status code returned by the response.
Table 1 Status codes

Status Code

Status

Description

200

OK

Request processed successfully.

Exception status code. For details, see Status Codes.