Querying the Key Instance

Function

This API is used to query a key instance. You can use tags to filter and check CMK details.

Calling Method

For details, see Calling APIs.

URI

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

**Table 1** Path Parameters
Parameter	Mandatory	Type	Description
project_id	Yes	String	Definition Project ID. For details, see Obtaining a Project ID. Constraints N/A Range The value returned by the IAM API is used, which contains 32 characters. Default Value N/A
resource_instances	Yes	String	Definition Resource instance. The value is resource_instances. Constraints N/A Range The value is fixed at resource_instances. Default Value N/A

Request Parameters

**Table 2** Request header parameters
Parameter	Mandatory	Type	Description
X-Auth-Token	Yes	String	Definition User token. It can be obtained by calling the IAM API. The value of X-Subject-Token in the response header is the user token. Constraints N/A Range Obtain the value by calling the IAM API for obtaining the user token. Default Value N/A

**Table 3** Request body parameters
Parameter	Mandatory	Type	Description
limit	No	String	Definition Number of records to be queried Constraints This parameter is not required when action is set to count. The value of limit must be an integer. Range 1 to 1000 Default Value If action is set to filter, the default value is 10.
offset	No	String	Definition Index location. The query starts from the next data specified by offset. When you query resources on subsequent pages, set offset to the location returned in the response body for the previous query. Constraints The value of offset must be an integer. This parameter is not required when action is set to count. Range 0 to 1000 Default Value If the action is set to filter, offset is set to 0 by default.
action	No	String	Definition Operation ID Constraints N/A Range filter: Filter records. count: Count all records. Default Value N/A
tags	No	Array of Tag objects	Definition Tag list, which is the value pairs of tag keys and values. Constraints key: Tag key. A key can contain up to 10 tag keys. This parameter cannot be left empty. The key and the key value must be unique. A tag key can contain at most 36 characters. value: Tag value. Each tag value can contain up to 43 characters. A search result matches all the values. Range N/A Default Value N/A
matches	No	Array of TagItem objects	Definition Search field Constraints key: The field to be matched, for example, resource_name. value: The value to be matched. It can contain up to 255 characters and cannot be empty. Range N/A Default Value N/A
sequence	No	String	Definition A 36-byte serial number of a request message, for example, 919c82d4-8046-4722-9094-35c3c6524cff. Constraints N/A Range N/A Default Value N/A

**Table 4** Tag
Parameter	Mandatory	Type	Description
key	No	String	Definition Tag key Constraints The value can contain up to 36 Unicode characters. The value cannot contain ASCII characters (0–31), asterisks (), angle brackets (< and >), backslashes (), or equal signs (=). The value cannot be empty. Range* N/A Default Value N/A
values	No	Array of strings	Definition Tag value Constraints The value can contain up to 43 Unicode characters. The value cannot contain ASCII characters (0–31), asterisks (), angle brackets (< and >), backslashes (), or equal signs (=). The value cannot be empty. Range* N/A Default Value N/A

**Table 5** TagItem
Parameter	Mandatory	Type	Description
key	Yes	String	Definition Tag key Constraints The value can contain up to 36 Unicode characters. The value cannot contain ASCII characters (0–31), asterisks (), angle brackets (< and >), backslashes (), or equal signs (=). The value cannot be empty. Range* N/A Default Value N/A
value	No	String	Definition Tag value Constraints The value can contain up to 43 Unicode characters. The value cannot contain ASCII characters (0–31), asterisks (), angle brackets (< and >), backslashes (), or equal signs (=). The value cannot be empty. Range* N/A Default Value N/A

Response Parameters

Status code: 200

**Table 6** Response body parameters
Parameter	Type	Description
resources	Array of ActionResources objects	Definition Resource instance list Range N/A
total_count	Integer	Definition Total number of records Range N/A

**Table 7** ActionResources
Parameter	Type	Description
resource_id	String	Definition Resource ID Range N/A
resource_detail	KeyDetails object	Key details.
resource_name	String	Definition Resource name Range N/A
tags	Array of TagItem objects	Definition Tag list. If there is no tag, the array is empty by default. Range N/A

**Table 8** KeyDetails
Parameter	Type	Description
key_id	String	Definition Key ID Range N/A
domain_id	String	Definition User domain ID Range N/A
key_alias	String	Definition Key alias Range N/A
realm	String	Definition Region to which the key belongs Range N/A
key_spec	String	Definition Key generation algorithm Range AES_256 SM4 RSA_2048 RSA_3072 RSA_4096 EC_P256 EC_P384 SM2
key_usage	String	Definition Key usage Range ENCRYPT_DECRYPT SIGN_VERIFY
key_description	String	Definition Key description Range N/A
creation_date	String	Definition Timestamp when a key was created, that is, the total number of seconds since January 1, 1970. Range N/A
scheduled_deletion_date	String	Definition Timestamp when a key is to be deleted as scheduled, that is, the total number of seconds since January 1, 1970. Range N/A
key_state	String	Definition Key status Range 1: To be activated 2: Enabled 3: Disabled 4: Pending deletion 5: Pending import
default_key_flag	String	Definition Master key identifier. The value is 1 for default master keys and 0 for non-default master keys. Range N/A
key_type	String	Definition Key type Range N/A
expiration_time	String	Definition Timestamp when the key material expires, that is, the total number of seconds since January 1, 1970. Range N/A
origin	String	Definition Key source Range kms: The key material is generated by KMS. external: The key material is imported.
key_rotation_enabled	String	Definition Key rotation status Range true false
sys_enterprise_project_id	String	Definition Enterprise project ID For users who have enabled the enterprise project, the resources are in the default enterprise project. For users who have not enabled the enterprise project, the resources are not in the enterprise project. Range N/A
keystore_id	String	Definition Keystore ID Range N/A
keystore_type	String	Definition Dedicated keystore cluster type Range DHSM: DHSM cluster CDMS: CDMS cluster DEFAULT: original KMS cluster

**Table 9** TagItem
Parameter	Type	Description
key	String	Definition Tag key Range N/A
value	String	Definition Tag value Range N/A

Example Requests

Query the key instance whose tag key is key1 and tag value is value1 or value2. The start position is 100 and 100 results are displayed.

{
  "offset" : "100",
  "limit" : "100",
  "action" : "filter",
  "tags" : [ {
    "key" : "key1",
    "values" : [ "value1", "value2" ]
  } ]
}

Example Responses

Status code: 200

Request succeeded.

{
  "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",
      "key_rotation_enabled" : "false",
      "expiration_time" : "",
      "origin" : "kms",
      "sys_enterprise_project_id" : "0",
      "realm" : "test"
    },
    "resource_name" : "tagTest_xmdmi",
    "tags" : [ {
      "key" : "key",
      "value" : "testValue!"
    }, {
      "key" : "haha",
      "value" : "testValue"
    } ]
  } ],
  "total_count" : 1
}