@dynatrace-sdk/client-state

中文文档

1.11.0发布于 2026/09/25Apache-2.0TypeScriptESM + CJS近 30 天下载 1.5万

Provides key-value storage for apps so that app developers can persist and get small chunks of state in the context of their app.

文档目录28 节

Installation
Getting help
License
stateClient
deleteAppState
deleteAppStates
deleteUserAppState
deleteUserAppStates
getAppState
getAppStates
getUserAppState
getUserAppStates
setAppState
setUserAppState
Types
AppState
AppStates
Error
ErrorDetails
ErrorResponse
ListAppState
ListUserAppState
ModificationInfo
PersistenceState
UserAppState
UserAppStates
Enums
ErrorDetailsErrorCode

@dynatrace-sdk/client-state

Overview

Provides key-value storage for apps so that app developers can persist and get small chunks of state in the context of their app.

States can either be stored in the context of an app (= app states) or in the context of an app and user (= user app states).

States stored per app can be read by every user of the app.
States stored per app and user can only be read and updated by the user who originally set that state. Please visit the Dynatrace Developer to learn more about app states and user app states.

Installation

npm install @dynatrace-sdk/client-state

Getting help

Visit SDK for Typescript guide in the Dynatrace Developer
Ask a question in the Dynatrace Community

License

This SDK is distributed under the Apache License, Version 2.0, see LICENSE for more information.

API reference

Full API reference for the latest version of the SDK is also available at the Dynatrace Developer.

stateClient

import { stateClient } from '@dynatrace-sdk/client-state';

deleteAppState

stateClient.deleteAppState(config): Promise<void>

Deletes app state

Required scope: state:app-states:delete

Parameters

Name	Type	Description
config.key^*required	string	Specify the key of the state Example: `some-key`

Throws

Error Type	Error Message
Unauthorized	Unauthorized
Forbidden	Forbidden
NotFound	Not found
InternalServerError	Internal server error
GeneralError	Unexpected error

Code example

import { stateClient } from "@dynatrace-sdk/client-state";

const data = await stateClient.deleteAppState({
  key: "some-key",
});

deleteAppStates

stateClient.deleteAppStates(config): Promise<void>

Delete all app states

Required scope: state:app-states:delete

Deletes all app states for an app to reset the app into a clean state.

Throws

Error Type	Error Message
GeneralError	Unexpected error

Code example

import { stateClient } from "@dynatrace-sdk/client-state";

const data = await stateClient.deleteAppStates();

deleteUserAppState

stateClient.deleteUserAppState(config): Promise<void>

Delete user app state

Required scope: state:user-app-states:delete

Parameters

Name	Type	Description
config.key^*required	string	Specify the key of the state Example: `some-key`

Throws

Error Type	Error Message
Unauthorized	Unauthorized
Forbidden	Forbidden
NotFound	Not found
InternalServerError	Internal server error
GeneralError	Unexpected error

Code example

import { stateClient } from "@dynatrace-sdk/client-state";

const data = await stateClient.deleteUserAppState({
  key: "some-key",
});

deleteUserAppStates

stateClient.deleteUserAppStates(config): Promise<void>

Delete all user app states

Required scope: state:user-app-states:delete

Deletes all user app states for the calling user and app.

Throws

Error Type	Error Message
GeneralError	Unexpected error

Code example

import { stateClient } from "@dynatrace-sdk/client-state";

const data = await stateClient.deleteUserAppStates();

getAppState

stateClient.getAppState(config): Promise<AppState>

Gets app state

Required scope: state:app-states:read

Parameters

Name	Type	Description
config.key^*required	string	Specify the key of the state Example: `some-key`

Returns

Return type	Status code	Description
AppState	200	The app state

Throws

Error Type	Error Message
Unauthorized	Unauthorized
Forbidden	Forbidden
NotFound	Not found
InternalServerError	Internal server error
GeneralError	Unexpected error

Code example

import { stateClient } from "@dynatrace-sdk/client-state";

const data = await stateClient.getAppState({
  key: "some-key",
});

getAppStates

stateClient.getAppStates(config): Promise<AppStates>

List app states

Required scope: state:app-states:read

Lists app states. By default, only provides property key per state. Use add-fields parameter to include more fields and the filter parameter to narrow down the returned states.

Parameters

Name Type Description

config.addFields string Provide a comma separated list of additional properties to be included in the response.

Example: value,modificationInfo

config.filter

Name	Type	Description
config.addFields	string	Provide a comma separated list of additional properties to be included in the response. Example: `value,modificationInfo`
config.filter	string	The filter parameter for filtering the set of returned resources If this parameter is omitted, no filtering is applied and all states will be returned. Filtering by string type parameters `key`, `modificationInfo.lastModifiedBy` when using one of the operators `contains`, `starts-with` and `ends-with` is case insensitive. When using the operators `=`and `!=`, filtering is case sensitive. The following fields are legal filtering parameters - any other field names will result in a HTTP 400 response: `key`, supported operators: `=`, `!=`, `contains`, `starts-with`, `ends-with`: `modificationInfo.lastModifiedTime`, supported operators: `=`, `!=`, `<`, `<=`, `>`, `>=` `modificationInfo.lastModifiedBy`, supported operators: `=`, `!=`, `contains`, `starts-with`, `ends-with` `validUntilTime`, supported operators: `=`, `!=`, `<`, `<=`, `>`, `>=` The following constraints apply: Field names are case-sensitive. Conditions can be connected via operators `and` and `or`. A single condition can be negated by `not`. Strings must be enclosed in single quotes. e.g. `key contains 'my-string'` Single quotes within a string must be escaped with a backslash: e.g. `key starts-with 'it\'s a string'` Maximum nesting depth (via brackets) is 2. Maximum length is 256 characters. Examples: `key starts-with 'game-'` `modificationInfo.lastModifiedTime >= '2022-07-01T00:10:05.000Z' and not (key contains 'new')` Example: `modificationInfo.lastModifiedTime >= '2022-02-06T11:00:00Z'`

string

The filter parameter for filtering the set of returned resources If this parameter is omitted, no filtering is applied and all states will be returned.

Filtering by string type parameters key, modificationInfo.lastModifiedBy when using one of the operators contains, starts-with and ends-with is case insensitive.

When using the operators =and !=, filtering is case sensitive.

The following fields are legal filtering parameters - any other field names will result in a HTTP 400 response:

key, supported operators: =, !=, contains, starts-with, ends-with:
modificationInfo.lastModifiedTime, supported operators: =, !=, <, <=, >, >=
modificationInfo.lastModifiedBy, supported operators: =, !=, contains, starts-with, ends-with
validUntilTime, supported operators: =, !=, <, <=, >, >=

The following constraints apply:

Field names are case-sensitive.
Conditions can be connected via operators and and or. A single condition can be negated by not.
Strings must be enclosed in single quotes. e.g. key contains 'my-string'
Single quotes within a string must be escaped with a backslash: e.g. key starts-with 'it\'s a string'
Maximum nesting depth (via brackets) is 2.
Maximum length is 256 characters.

Examples:

key starts-with 'game-'
modificationInfo.lastModifiedTime >= '2022-07-01T00:10:05.000Z' and not (key contains 'new')

Example: modificationInfo.lastModifiedTime >= '2022-02-06T11:00:00Z'

Returns

Return type	Status code	Description
AppStates	200	The list of app states

Throws

Error Type	Error Message
Unauthorized	Unauthorized
Forbidden	Forbidden
InternalServerError	Internal server error
GeneralError	Unexpected error

Code example

import { stateClient } from "@dynatrace-sdk/client-state";

const data = await stateClient.getAppStates();

getUserAppState

stateClient.getUserAppState(config): Promise<UserAppState>

Get user app state

Required scope: state:user-app-states:read

Parameters

Name	Type	Description
config.key^*required	string	Specify the key of the state Example: `some-key`

Returns

Return type	Status code	Description
UserAppState	200	The user app state

Throws

Error Type	Error Message
Unauthorized	Unauthorized
Forbidden	Forbidden
NotFound	Not found
InternalServerError	Internal server error
GeneralError	Unexpected error

Code example

import { stateClient } from "@dynatrace-sdk/client-state";

const data = await stateClient.getUserAppState({
  key: "some-key",
});

getUserAppStates

stateClient.getUserAppStates(config): Promise<UserAppStates>

List user app states

Required scope: state:user-app-states:read

Lists user app states. By default, only provides property key per state. Use add-fields parameter to include more fields and the filter parameter to narrow down the returned states

Parameters

Name Type Description

config.addFields string Provide a comma separated list of additional properties to be included in the response.

Example: value,modificationInfo

config.filter

Name	Type	Description
config.addFields	string	Provide a comma separated list of additional properties to be included in the response. Example: `value,modificationInfo`
config.filter	string	The filter parameter for filtering the set of returned resources If this parameter is omitted, no filtering is applied and all states will be returned. Filtering by string type parameters `key`, `modificationInfo.lastModifiedBy` when using one of the operators `contains`, `starts-with` and `ends-with` is case insensitive. When using the operators `=`and `!=`, filtering is case sensitive. The following fields are legal filtering parameters - any other field names will result in a HTTP 400 response: `key`, supported operators: `=`, `!=`, `contains`, `starts-with`, `ends-with`: `modificationInfo.lastModifiedTime`, supported operators: `=`, `!=`, `<`, `<=`, `>`, `>=` `modificationInfo.lastModifiedBy`, supported operators: `=`, `!=`, `contains`, `starts-with`, `ends-with` `validUntilTime`, supported operators: `=`, `!=`, `<`, `<=`, `>`, `>=` The following constraints apply: Field names are case-sensitive. Conditions can be connected via operators `and` and `or`. A single condition can be negated by `not`. Strings must be enclosed in single quotes. e.g. `key contains 'my-string'` Single quotes within a string must be escaped with a backslash: e.g. `key starts-with 'it\'s a string'` Maximum nesting depth (via brackets) is 2. Maximum length is 256 characters. Examples: `key starts-with 'game-'` `modificationInfo.lastModifiedTime >= '2022-07-01T00:10:05.000Z' and not (key contains 'new')` Example: `modificationInfo.lastModifiedTime >= '2022-02-06T11:00:00Z'`

string

The filter parameter for filtering the set of returned resources If this parameter is omitted, no filtering is applied and all states will be returned.

Filtering by string type parameters key, modificationInfo.lastModifiedBy when using one of the operators contains, starts-with and ends-with is case insensitive.

When using the operators =and !=, filtering is case sensitive.

The following fields are legal filtering parameters - any other field names will result in a HTTP 400 response:

key, supported operators: =, !=, contains, starts-with, ends-with:
modificationInfo.lastModifiedTime, supported operators: =, !=, <, <=, >, >=
modificationInfo.lastModifiedBy, supported operators: =, !=, contains, starts-with, ends-with
validUntilTime, supported operators: =, !=, <, <=, >, >=

The following constraints apply:

Field names are case-sensitive.
Conditions can be connected via operators and and or. A single condition can be negated by not.
Strings must be enclosed in single quotes. e.g. key contains 'my-string'
Single quotes within a string must be escaped with a backslash: e.g. key starts-with 'it\'s a string'
Maximum nesting depth (via brackets) is 2.
Maximum length is 256 characters.

Examples:

key starts-with 'game-'
modificationInfo.lastModifiedTime >= '2022-07-01T00:10:05.000Z' and not (key contains 'new')

Example: modificationInfo.lastModifiedTime >= '2022-02-06T11:00:00Z'

Returns

Return type	Status code	Description
UserAppStates	200	The list of user app states

Throws

Error Type	Error Message
Unauthorized	Unauthorized
Forbidden	Forbidden
InternalServerError	Internal server error
GeneralError	Unexpected error

Code example

import { stateClient } from "@dynatrace-sdk/client-state";

const data = await stateClient.getUserAppStates();

setAppState

stateClient.setAppState(config): Promise<void>

Updates app state

Required scope: state:app-states:write

Updates the cross-user app state for the given key. Be aware that other users will be able to read the value. Use the user-scoped user-app-state to only store values for the authenticated user.

Certain limits apply when updating app states.

Parameters

Name	Type	Description
config.body^*required	AppState
config.key^*required	string	Specify the key of the state Example: `some-key`

Returns

Return type	Status code	Description
void	200	OK

Throws

Error Type	Error Message
AppStateLimitsExceeded	Exceeded size limit for combined size of app states of this app
Unauthorized	Unauthorized
Forbidden	Forbidden
InternalServerError	Internal server error
GeneralError	Unexpected error

Code example

import { stateClient } from "@dynatrace-sdk/client-state";

const data = await stateClient.setAppState({
  key: "some-key",
  body: { value: "some-state", validUntilTime: "now+2d" },
});

setUserAppState

stateClient.setUserAppState(config): Promise<void>

Updates user app state

Required scope: state:user-app-states:write

Updates the user specific app state for the given key and calling user.

Certain limits apply when updating user app states.

Parameters

Name	Type	Description
config.body^*required	UserAppState
config.key^*required	string	Specify the key of the state Example: `some-key`

Returns

Return type	Status code	Description
void	200	OK

Throws

Error Type	Error Message
UserAppStateLimitsExceeded	Exceeded limit for number of user app states to be stored for this user and app
Unauthorized	Unauthorized
Forbidden	Forbidden
InternalServerError	Internal server error
GeneralError	Unexpected error

Code example

import { stateClient } from "@dynatrace-sdk/client-state";

const data = await stateClient.setUserAppState({
  key: "some-key",
  body: { value: "some-state", validUntilTime: "now+2d" },
});

Types

AppState

Name	Type	Description
modificationInfo	ModificationInfo
validUntilTime	null \| string	Specify the date until the state is persisted. Allowed are values from now+1m to now+90d! Returned validUntilTimes are always a string formatted in ISO 8601 Example: `now+2d`
value^*required	string

AppStates

type: Array<ListAppState>

Error

Name	Type
code^*required	number
details	ErrorDetails
message^*required	string

ErrorDetails

Name Type Description

errorCode

"AppStateOverallSizeLimitExceeded" | "AppStateSizeLimitExceeded" | "UserAppStateSizeLimitExceeded" | "UserAppStateCountLimitExceeded" | "UserAppStateSizeLimitPerUserExceeded"

Name	Type	Description
errorCode	"AppStateOverallSizeLimitExceeded" \| "AppStateSizeLimitExceeded" \| "UserAppStateSizeLimitExceeded" \| "UserAppStateCountLimitExceeded" \| "UserAppStateSizeLimitPerUserExceeded"	Error code indicating the reason why the request failed `AppStateOverallSizeLimitExceeded` - The overall size limit for the combined size of app states of this app was exceeded `AppStateSizeLimitExceeded` - The app state value exceeded the size limit for a single app state `UserAppStateSizeLimitPerUserExceeded` - The size of user app state values of a user for an app exceeds the limit `UserAppStateSizeLimitExceeded` - deprecated The user app state content exceeded the size limit for a single user app state. No longer returned by the API. `UserAppStateCountLimitExceeded` - deprecated The maximum number of user app states for this user and app was exceeded. No longer returned by the API.
missingPermissions	Array<string>	IAM permissions that the user is missing. Present on 403 responses where the token carries the required scope but the user's IAM policies do not grant the permission.
missingScopes	Array<string>	OAuth scopes that the bearer token is missing. Present on 403 responses caused by an insufficient token scope. Add the listed scopes to the token to resolve this error.

Error code indicating the reason why the request failed

AppStateOverallSizeLimitExceeded - The overall size limit for the combined size of app states of this app was exceeded
AppStateSizeLimitExceeded - The app state value exceeded the size limit for a single app state
UserAppStateSizeLimitPerUserExceeded - The size of user app state values of a user for an app exceeds the limit
UserAppStateSizeLimitExceeded - deprecated The user app state content exceeded the size limit for a single user app state. No longer returned by the API.
UserAppStateCountLimitExceeded - deprecated The maximum number of user app states for this user and app was exceeded. No longer returned by the API.

missingPermissions Array<string> IAM permissions that the user is missing. Present on 403 responses where the token carries the required scope but the user's IAM policies do not grant the permission.

missingScopes Array<string> OAuth scopes that the bearer token is missing. Present on 403 responses caused by an insufficient token scope. Add the listed scopes to the token to resolve this error.

ErrorResponse

Name	Type
error^*required	Error

ListAppState

Name	Type	Description
key^*required	string
modificationInfo	ModificationInfo
validUntilTime	null \| string	Specify the date until the state is persisted. Allowed are values from now+1m to now+90d! Returned validUntilTimes are always a string formatted in ISO 8601 Example: `now+2d`
value	string

ListUserAppState

Name	Type	Description
key^*required	string
modificationInfo	ModificationInfo
validUntilTime	null \| string	Specify the date until the state is persisted. Allowed are values from now+1m to now+90d! Returned validUntilTimes are always a string formatted in ISO 8601 Example: `now+2d`
value	string

ModificationInfo

Name	Type
lastModifiedBy^*required	string
lastModifiedTime^*required	Date

PersistenceState

Name	Type	Description
modificationInfo	ModificationInfo
validUntilTime	null \| string	Specify the date until the state is persisted. Allowed are values from now+1m to now+90d! Returned validUntilTimes are always a string formatted in ISO 8601 Example: `now+2d`
value	string

UserAppState

Name	Type	Description
modificationInfo	ModificationInfo
validUntilTime	null \| string	Specify the date until the state is persisted. Allowed are values from now+1m to now+90d! Returned validUntilTimes are always a string formatted in ISO 8601 Example: `now+2d`
value^*required	string

UserAppStates

type: Array<ListUserAppState>

Enums

ErrorDetailsErrorCode

⚠️ Deprecated Use literal values.

Error code indicating the reason why the request failed

AppStateOverallSizeLimitExceeded - The overall size limit for the combined size of app states of this app was exceeded
AppStateSizeLimitExceeded - The app state value exceeded the size limit for a single app state
UserAppStateSizeLimitPerUserExceeded - The size of user app state values of a user for an app exceeds the limit
UserAppStateSizeLimitExceeded - deprecated The user app state content exceeded the size limit for a single user app state. No longer returned by the API.
UserAppStateCountLimitExceeded - deprecated The maximum number of user app states for this user and app was exceeded. No longer returned by the API.

Enum keys

AppStateOverallSizeLimitExceeded | AppStateSizeLimitExceeded | UserAppStateCountLimitExceeded | UserAppStateSizeLimitExceeded | UserAppStateSizeLimitPerUserExceeded

版本与发布记录

@dynatrace-sdk/client-state 共发布 29 个版本，首次发布于 2023/04/03；过去 12 个月发布了 2 个版本。

版本	发布日期	距今
`1.11.0`latest	2026/09/25	1 个月前
`1.9.3`	2026/06/25	4 个月前
`1.9.2`	2025/09/24	1.1 年前
`1.9.1`	2025/07/15	1.3 年前
`1.8.3`	2025/07/01	1.4 年前
`1.8.2`	2025/06/17	1.4 年前

关于 @dynatrace-sdk/client-state 的常见问题

@dynatrace-sdk/client-state 是什么？

Provides key-value storage for apps so that app developers can persist and get small chunks of state in the context of their app.

如何安装 @dynatrace-sdk/client-state？

在项目目录运行 npm install @dynatrace-sdk/client-state，或使用 pnpm add / yarn add / bun add。

@dynatrace-sdk/client-state 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

@dynatrace-sdk/client-state 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require() 都可以使用，打包工具会自动选择合适的版本。

@dynatrace-sdk/client-state 可以商用吗？

@dynatrace-sdk/client-state 使用 Apache-2.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

@dynatrace-sdk/client-state 的下载量有多少？

根据 npm 官方下载统计，@dynatrace-sdk/client-state 在 2026/10/13 – 2026/11/11 这 30 天内被下载 15,120 次，日均约 504 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

@dynatrace-sdk/client-state 还在维护吗？

最新版本 1.11.0 发布于 2026/09/25（1 个月前）；至今共发布 29 个版本，其中过去 12 个月发布了 2 个；首次发布于 2023/04/03。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。