Querying Key Pair Instances

Function

This API is used to query key pair instances, filter key pairs by tag, and return the key pair list.

Calling Method

For details, see Calling APIs.

Authorization Information

Each account has all the permissions required to call all APIs, but IAM users must be assigned the required permissions.

If you are using role/policy-based authorization, see Permissions Policies and Supported Actions for details on the required permissions.
If you are using identity policy-based authorization, no identity policy-based permission required for calling this API.

URI

POST /v3/{project_id}/keypairs/resource-instances/filter

**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

**Table 2** Query Parameters
Parameter	Mandatory	Type	Description
limit	No	Integer	Definition Number of records to be queried Constraints The value of limit must be an integer. Range 1 to 1000 Default Value 1000
offset	No	Integer	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. Range N/A Default Value The default value of offset is 0.

Request Parameters

**Table 3** 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 4** Request body parameters
Parameter	Mandatory	Type	Description
tags	No	Array of Tag objects	Definition Tag list, which is the value pairs of tag keys and values. There can be at most 10 value pairs. Constraints N/A Range N/A Default Value N/A
without_any_tag	No	Boolean	Definition Resources without any tags are queried. If this parameter is set to true, all resources without any tags are queried. In this case, skip the tags field. If this parameter is set to false or not specified, it does not take effect, meaning that all resources are returned or resources are filtered by tags or matches. If this parameter is not specified, an empty value is returned. Constraints N/A Range N/A Default Value N/A
matches	No	Array of TagMatches objects	Definition Search field. key indicates the search field. Currently, only the key pair name can be searched. The value is resource_name. value indicates the fuzzy match value, which can contain at most 255 characters. If this parameter is not specified, an empty value is returned. Constraints N/A Range N/A Default Value N/A
sys_tags	No	Array of Tag objects	Definition Tag list, which is the value pairs of tag keys and values. There can be at most 10 value pairs. Constraints N/A Range N/A Default Value N/A

**Table 5** TagMatches
Parameter	Mandatory	Type	Description
key	No	String	Definition Field to be matched Constraints The value can only be a key pair name. Range N/A Default Value N/A
value	No	String	Definition Tag value Constraints N/A Range The value can contain at most 255 characters and must match the regular expression *^([\p{L}\p{Z}\p{N}_.:\/=+\-@])$. Default Value** N/A

**Table 6** Tag
Parameter	Mandatory	Type	Description
key	No	String	Definition Tag key Constraints N/A Range N/A Default Value N/A
values	No	Array of strings	Definition Tag value set. There can be at most 10 tag values. Tag values in a tag list must be unique. If the tag list is empty, any tag value is matched. When there are multiple values in the tag list and the key requirements are met, a value in the request is matched. Constraints N/A Range N/A Default Value N/A

Response Parameters

Status code: 200

**Table 7** Response body parameters
Parameter	Type	Description
total_count	Integer	Definition Total number of records Range N/A
resources	Array of Resources objects	Definition Resource instance list. For details, see the data structure description of the resource field. Range N/A

**Table 8** Resources
Parameter	Type	Description
resource_id	String	Definition Secret ID Range N/A
resource_name	String	Definition Resource name. This parameter is an empty string by default. Range N/A
tags	Array of TagItem objects	Definition Tag list. If there is no tag, the array is empty by default. Definition N/A
sys_tags	Array of TagItem objects	Definition System tag list. If there is no tag in the list, an empty array is returned by default. Range N/A
resource_detail	KeypairDetails object	Definition Resource information Range N/A
total_count	Integer	Definition Number of tags Range N/A

**Table 9** TagItem
Parameter	Type	Description
key	String	Definition Tag name Constraints The tag keys of a key pair cannot have duplicate values. A tag key can be used for multiple key pairs. A key pair can have up to 20 tags. Range The value can contain 1 to 128 characters and must match the regular expression *^((?!\s)(?!sys)[\p{L}\p{Z}\p{N}_.:=+\-@])(?<!\s)$. Default Value** N/A
value	String	Definition Tag value Constraints N/A Range The value can contain at most 255 characters and must match the regular expression *^([\p{L}\p{Z}\p{N}_.:\/=+\-@])$. Default Value** N/A

**Table 10** KeypairDetails
Parameter	Type	Description
name	String	Definition Key pair name. The value can contain at most 255 characters. Only letters, digits, underscores (_), and hyphens (-) are allowed. Range N/A
uuid	String	Definition Key pair UUID Range N/A
id	Long	Definition Key pair ID Range N/A
type	String	Definition Key pair type Range ssh x509
scope	String	Definition Domain to which the key pair belongs, which can be tenant-level or user-level. Range domain user
public_key	String	Definition Public key information about an SSH key pair Range N/A
fingerprint	String	Definition Fingerprint information about an SSH key pair Range N/A
project_id	String	Definition Project ID. It can be obtained by calling the IAM API for obtaining the project list of a specified IAM user. Constraints N/A Range The value returned by the IAM API is used, which contains 32 characters. Default Value N/A
domain_id	String	Definition ID of the tenant to which the key pair belongs. Range N/A
description	String	Definition SSH key pair description Range N/A
user_id	String	Definition ID of the user to which the SSH key pair belongs Range N/A
created_at	Long	Definition Timestamp when the SSH key pair was created, that is, the total seconds since January 1, 1970. Range N/A
update_at	Long	Definition Timestamp when the SSH key pair was updated, that is, the total seconds since January 1, 1970. Range N/A
freeze_flag	Integer	Definition Key frozen status Range 0: normal 1: frozen due to common causes 2: frozen by the public security bureau 3: frozen due to common causes and frozen by the public security bureau 4: frozen due to violations 5: frozen due to common causes and violations 6: frozen by the public security bureau and due to violations 7: frozen by the public security bureau and due to common causes and violations 8: frozen due to the lack of real-name authentication 9: frozen due to common causes and the lack of real-name authentication 10: frozen by the public security bureau and due to the lack of real-name authentication
encrypt_id	String	Definition Algorithm Range N/A
key_id	String	Definition Key ID Range N/A
is_key_protection	Boolean	Definition Whether to host keys Range true or false
frozen_state	String	Definition Key frozen status Range 0: normal 1: frozen due to common causes 2: frozen by the public security bureau 3: frozen due to common causes and frozen by the public security bureau 4: frozen due to violations 5: frozen due to common causes and violations 6: frozen by the public security bureau and due to violations 7: frozen by the public security bureau and due to common causes and violations 8: frozen due to the lack of real-name authentication 9: frozen due to common causes and the lack of real-name authentication 10: frozen by the public security bureau and due to the lack of real-name authentication

Example Requests

{
  "tags" : [ {
    "key" : "key1",
    "values" : [ "val1" ]
  } ]
}

Example Responses

Status code: 200

Request succeeded.

{
  "total_count" : 1,
  "resources" : [ {
    "resource_id" : "2d1152f2-290d-4756-a1d2-e12c14992416"
  } ]
}

Status Codes

Status Code	Description
200	Request succeeded.
400	Invalid parameter.
401	Authorization failed.
403	Insufficient permissions.
404	Resource not found.
500	System error.

Error Codes

See Error Codes.

Parent Topic: Key Pair Tag Management

Previous topic: Key Pair Tag Management

Next topic: Querying the Number of Key Pair Instances