Updated on 2023-05-09 GMT+08:00

Querying a Secret Instance

Function

  • This API is used to query a secret instance, filter user secrets by tag, and return a secret list.

Debugging

You can debug this API through automatic authentication in API Explorer or use the SDK sample code generated by API Explorer.

URI

POST /v1/{project_id}/csms/{resource_instances}/action

Table 1 Path Parameters

Parameter

Mandatory

Type

Description

resource_instances

Yes

String

Its value is resource_instances.

project_id

Yes

String

Project ID

Request Parameters

Table 2 Request header parameters

Parameter

Mandatory

Type

Description

X-Auth-Token

Yes

String

User token.

It can be obtained by calling the IAM API that is used for obtaining a user token. The value of X-Subject-Token in the response header is the user token.

Table 3 Request body parameters

Parameter

Mandatory

Type

Description

limit

No

String

Number of records to be queried. This parameter does not need to be specified if action is set to count. If action is set to filter, the parameter defaults to 10. The value of limit is in the range 1 to 1,000.

offset

No

String

Index location. The query starts from the next piece of data indexed by this parameter. When data on a page is queried, the value in the response body of the previous page is transferred to this parameter. (If action is set to count, you do not need to set this parameter.) If the action is set to filter, offset defaults to 0. The value of offset must be a number and cannot be negative.

action

No

String

Operation type. It can be:

  • filter: Filter record.

  • count: Count the total number of records.

tags

No

Array of Tag objects

Tag list, which is a collection of key-value pairs.

  • key: Tag key. A secret can have a maximum of 20 keys, and each of them is unique and cannot be left blank. A key cannot have duplicate values. It can contain up to 36 characters. The keys are in the AND relationship.

  • value: Tag value. Each tag value can contain a maximum of 43 characters. The values are in the OR relationship.

matches

No

Array of TagItem objects

Search field.

  • key indicates the search field. Currently, its value is resource_name, indicating that only the secret name can be searched.

  • value indicates the field for fuzzy match. It can contain up to 255 characters. If it is left blank, a null value is returned.

sequence

No

String

36-byte sequence number of a request message. Example: 919c82d4-8046-4722-9094-35c3c6524cff

Table 4 Tag

Parameter

Mandatory

Type

Description

key

No

String

Key. A tag key can contain a maximum of 36 Unicode characters. This parameter cannot be left blank. It cannot contain ASCII characters (0–31), asterisks (*), angle brackets (< and >), backslashes (), and equal signs (=).

values

No

Array of strings

Tag value set.

Table 5 TagItem

Parameter

Mandatory

Type

Description

key

No

String

Key. A tag key can contain a maximum of 36 Unicode characters. The value of key cannot be left blank. It cannot contain ASCII characters (0–31), asterisks (*), angle brackets (< and >), backslashes (), and equal signs (=).

value

No

String

Value. A tag value contains a maximum of 43 Unicode characters and can be left blank. It cannot contain ASCII characters (0–31), asterisks (*), angle brackets (< and >), backslashes (), and equal signs (=).

Response Parameters

Status code: 200

Table 6 Response body parameters

Parameter

Type

Description

resources

Array of ActionResources objects

Resource instance list. For details, see the data structure of the resource field.

total_count

Integer

Total number of records.

Table 7 ActionResources

Parameter

Type

Description

resource_id

String

Resource ID.

resource_detail

Secret object

Secret object.

resource_name

String

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

tags

Array of TagItem objects

Tag list. If there is no tag in the list, an empty array is returned.

sys_tags

Array of TagItem objects

Tag list, which is a collection of key-value pairs.

  • key: Tag key. A CMK can have a maximum of 10 keys, and each of them is unique and cannot be left blank. A key cannot have duplicate values. It can contain up to 36 characters.

  • value: Tag value. Each tag value can contain a maximum of 43 characters. The values are in the AND relationship.

Table 8 Secret

Parameter

Type

Description

id

String

Resource identifier of a secret.

name

String

Secret name.

state

String

Secret status. Its value can be:

  • ENABLED

  • DISABLED

  • PENDING_DELETE

  • FROZEN

kms_key_id

String

ID of the KMS CMK used to encrypt a secret value.

description

String

Description of a secret.

create_time

Long

Secret creation time. The timestamp indicates the total seconds past the start of the epoch date (January 1, 1970).

update_time

Long

Time when a secret was last updated. The timestamp indicates the total seconds past the start of the epoch date (January 1, 1970).

scheduled_delete_time

Long

Time when a secret is scheduled to be deleted. The timestamp indicates the total seconds past the start of the epoch date (January 1, 1970).

If the secret is not in the deletion plan, the value of this parameter is null.

Table 9 TagItem

Parameter

Type

Description

key

String

Key. A tag key can contain a maximum of 36 Unicode characters. The value of key cannot be left blank. It cannot contain ASCII characters (0–31), asterisks (*), angle brackets (< and >), backslashes (), and equal signs (=).

value

String

Value. A tag value contains a maximum of 43 Unicode characters and can be left blank. It cannot contain ASCII characters (0–31), asterisks (*), angle brackets (< and >), backslashes (), and equal signs (=).

Status code: 400

Table 10 Response body parameters

Parameter

Type

Description

error

ErrorDetail object

Table 11 ErrorDetail

Parameter

Type

Description

error_code

String

Error code returned for an error request.

error_msg

String

Error information returned for an error request.

Status code: 401

Table 12 Response body parameters

Parameter

Type

Description

error

ErrorDetail object

Table 13 ErrorDetail

Parameter

Type

Description

error_code

String

Error code returned for an error request.

error_msg

String

Error information returned for an error request.

Status code: 403

Table 14 Response body parameters

Parameter

Type

Description

error

ErrorDetail object

Table 15 ErrorDetail

Parameter

Type

Description

error_code

String

Error code returned for an error request.

error_msg

String

Error information returned for an error request.

Status code: 404

Table 16 Response body parameters

Parameter

Type

Description

error

ErrorDetail object

Table 17 ErrorDetail

Parameter

Type

Description

error_code

String

Error code returned for an error request.

error_msg

String

Error information returned for an error request.

Status code: 500

Table 18 Response body parameters

Parameter

Type

Description

error

ErrorDetail object

Table 19 ErrorDetail

Parameter

Type

Description

error_code

String

Error code returned for an error request.

error_msg

String

Error information returned for an error request.

Status code: 502

Table 20 Response body parameters

Parameter

Type

Description

error

ErrorDetail object

Table 21 ErrorDetail

Parameter

Type

Description

error_code

String

Error code returned for an error request.

error_msg

String

Error information returned for an error request.

Status code: 504

Table 22 Response body parameters

Parameter

Type

Description

error

ErrorDetail object

Table 23 ErrorDetail

Parameter

Type

Description

error_code

String

Error code returned for an error request.

error_msg

String

Error information returned for an error request.

Example Requests

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

Example Responses

Status code: 200

Request succeeded.

{
  "total_count" : 1,
  "resources" : [ {
    "resource_id" : "2d1152f2-290d-4756-a1d2-e12c14992416"
  }, {
    "resource_detail" : [ {
      "id" : "2d1152f2-290d-4756-a1d2-e12c14992416",
      "name" : "example_name",
      "state" : "ENABLED",
      "description" : "",
      "kms_key_id" : "1213d410-ass1-1254-1a2d-3cca2sa2w554",
      "create_time" : 1581507580000,
      "update_time" : 1581507580000,
      "scheduled_delete_time" : 1581507580000
    } ]
  }, {
    "tags" : [ {
      "key" : "key1",
      "value" : "value1"
    }, {
      "key" : "key2",
      "value" : "value2"
    } ]
  }, {
    "sys_tags" : null
  }, {
    "resource_name" : "example_name"
  } ]
}

Status Codes

Status Code

Description

200

Request succeeded.

400

Invalid request parameters.

401

You must enter a username and password to access the requested page.

403

Authentication failed.

404

The requested resource does not exist or is not found.

500

Internal service error.

502

Failed to complete the request. The server received an invalid response.

504

Gateway timeout.

Error Codes

See Error Codes.