getKeysFromHierarchy

The "getKeysFromHierarchy" action retrieves all keys located at the specified hierarchical level. It only returns keys.

Use the "getValuesFromHierarchy" action to return key-value pairs and "describeValuesFromHierarchy" to return all information about a key.

This action is useful for retrieving user-defined keys. For example, your application may let users create, name, and save items in keystores. When your application needs to display the names of the saved items to the user, it can use this action to retrieve them.

 

How to use "getKeysFromHierarchy"

Use the required "keyStore" property to specify the keystore from which keys are returned, and use the required "partialKey" property to define the hierarchical level of returned keys. To ensure the action matches the hierarchical levels you want, include the hierarchical delimiter at the end of the partial key, such as "myApp/queries/".

Warning: "partialKey": "" returns all keys in the store.

When using the "role" keystore, you must set the "roleName" property to the name of the role that owns the key-value pair. The action returns an error when the current user does not have the specified role. An administrator account may set and get values for any role.

When using the "user" keystore, the action uses the session's username to identify the user's keys. When an administrator account runs the action, it can optionally use the "username" property to specify the user that owns the keys. This allows an elevated account to retrieve keys for other accounts.

 

Request examples

Global keystore

{
  "api": "db",
  "action": "getKeysFromHierarchy",
  "params": {
    "keyStore": "global", 
    "partialKey": "myApp/queries/"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

Role keystore

The action uses the specified role and returns an error if the current session's account does not have that role. An administrator account may get key-value pairs for any role.

{
  "api": "db",
  "action": "getKeysFromHierarchy",
  "params": {
    "keyStore": "role", 
    "roleName": "operator",
    "partialKey": "myApp/queries/"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

User keystore

The action automatically uses the session's username.

{
  "api": "db",
  "action": "getKeysFromHierarchy",
  "params": {
    "keyStore": "user", 
    "partialKey": "nonexistent/hierarchy/"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

User keystore request using elevated privileges

When an administrator account runs the action, it can optionally use the "username" property to specify the account of the key-value pair. This allows an elevated account to get key-value pairs for other accounts.

{
  "api": "db",
  "action": "getKeysFromHierarchy",
  "params": {
    "keyStore": "user", 
    "username": "someone_else", 
    "partialKey": "myApp/queries/"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

 

Response examples

Global keystore

{
  "result": {
    "keyStore": "global", 
    "partialKey": "myApp/queries/",
    "keys": [
      "myApp/queries/My Favorite",
      "myApp/queries/Find Errors"
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession",
  "errorCode": 0,
  "errorMessage": ""
}
 
 

Role keystore

{
  "result": {
    "keyStore": "role", 
    "roleName": "operator",
    "partialKey": "myApp/queries/",
    "keys": [
      "myApp/queries/My Favorite"
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession",
  "errorCode": 0,
  "errorMessage": ""
}
 
 

User keystore 

When the partial key has no matches, "keys" is empty.

{
  "result": {
    "keyStore": "user", 
    "username": "me", 
    "partialKey": "nonexistent/hierarchy/",
    "keys": []
  },
  "authToken": "replaceWithAuthTokenFromCreateSession",
  "errorCode": 0,
  "errorMessage": ""
}
 
 

User keystore response using elevated privileges

{
  "result": {
    "keyStore": "user", 
    "username": "me", 
    "partialKey": "myApp/queries/",
    "keys": [
      "myApp/queries/My Favorite"
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession",
  "errorCode": 0,
  "errorMessage": ""
}
 
 

 

Properties

Request properties ("params")

Property Description Default Type Limits (inclusive)

keyStore

The "keyStore" property specifies the keystore where the action stores and retrieves key-value pairs. There are three keystores: "global", "role", and "user".


The Simple Secure Key-Value API stores key-value pairs independently in each keystore; thus, the same key can exist in different keystores with different values. For example, the "settings/default/" key can exist in the global, user, and role keystores.


Within the role keystore, different roles can have the same key with different values. For example, the "operator" and "guest" roles can have their own "settings/default/" key and assign their own value to it.


Within the user keystore, different users can have the same key with different values. For example, the "db" and "sam" users can have their own "settings/default/" key and assign their own value to it.


When using the "role" keystore, you must set the "roleName" property to the name of the role that owns the key-value pair. The action returns an error when the current user does not have the specified role. An administrator account may set and get values for any role.


When using the "user" keystore, the action uses the session's username to identify the user's keys. When an administrator account runs the action, it can optionally use the "username" property to specify the user that owns the keys. This allows an elevated account to create and modify keys for other accounts.

 Required - No default value string enum

"global"

"role"

"user"

partialKey

The "partialKey" property defines the range of returned records. For more details, see "partialKey". 

Optional with default of "" or []

Required in the Key-Value API 

 string or array

1 or more strings/arrays

1 to 128 bytes in the Key-Value API 

roleName

The "roleName" property specifies the key's role, which must match an RBAC role that exists in the server. It is not used with the other keystores. 


Within the role keystore, different roles can have the same key with different values. For example, the "operator" and "guest" roles can have their own "settings/default/" key and assign their own value to it.

 Required when "keystore": "role" string 1 to 64 bytes

username

The "username" property specifies the name that uniquely identifies the account. 

 

In "alter" actions, this property specifies the account that will be altered.

 

In Key-Value actions, the "username" property is optionally used with the user keystore. It allows an administrator account or an account with the "keyValueAdmin" privilege to manage a key-value pair for another account; otherwise, the server automatically uses the session's account. This approach ensures that an ordinary account can only set and retrieve its own key-value pairs.


Within the User keystore, different users can have the same key with different values. For example, the "db" and "sam" users can have their own "settings/default/" key and assign their own value to it.
 

Required - No default value

 

Optional with default of the account name of the currently logged-in user for Key-Value actions

 

 string 1 to 64 bytes

 

Response properties ("result")

Property Description Type Limits (inclusive)

keys

 The "keys" property contains an array of keys for an action to work on and return, such as [ "key1", "key2" ]. array of strings one or more key strings

keyStore

The "keyStore" property specifies the keystore where the action stores and retrieves key-value pairs. There are three keystores: "global", "role", and "user".


The Simple Secure Key-Value API stores key-value pairs independently in each keystore; thus, the same key can exist in different keystores with different values. For example, the "settings/default/" key can exist in the global, user, and role keystores.


Within the role keystore, different roles can have the same key with different values. For example, the "operator" and "guest" roles can have their own "settings/default/" key and assign their own value to it.


Within the user keystore, different users can have the same key with different values. For example, the "db" and "sam" users can have their own "settings/default/" key and assign their own value to it.


When using the "role" keystore, you must set the "roleName" property to the name of the role that owns the key-value pair. The action returns an error when the current user does not have the specified role. An administrator account may set and get values for any role.


When using the "user" keystore, the action uses the session's username to identify the user's keys. When an administrator account runs the action, it can optionally use the "username" property to specify the user that owns the keys. This allows an elevated account to create and modify keys for other accounts.

 string enum

"global"

"role"

"user"

partialKey

The "partialKey" property defines the range of returned records. For more details, see "partialKey". 

 string or array

1 or more strings/arrays

1 to 128 bytes in the Key-Value API 

roleName

The "roleName" property specifies the key's role, which must match an RBAC role that exists in the server. It is not used with the other keystores. 


Within the role keystore, different roles can have the same key with different values. For example, the "operator" and "guest" roles can have their own "settings/default/" key and assign their own value to it.

 string 1 to 64 bytes

username

The "username" property specifies the name that uniquely identifies the account. 

 

In "alter" actions, this property specifies the account that will be altered.

 

In Key-Value actions, the "username" property is optionally used with the user keystore. It allows an administrator account or an account with the "keyValueAdmin" privilege to manage a key-value pair for another account; otherwise, the server automatically uses the session's account. This approach ensures that an ordinary account can only set and retrieve its own key-value pairs.


Within the User keystore, different users can have the same key with different values. For example, the "db" and "sam" users can have their own "settings/default/" key and assign their own value to it.
 

 string 1 to 64 bytes

Was this article helpful?

Give feedback about this article

Related Articles