@dynatrace-sdk/client-state
v1.6.0
Published
Provides key-value storage for apps so that app developers can persist and get small chunks of state in the context of their app.
Downloads
713
Keywords
Readme
@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
Deletes app state
Required scope: state:app-states:delete
Parameters
| Name | Type | Description | | --- | --- | --- | |config.key*required|string|Specify the key of the state |
Throws
| Error Type | Error Message | |---|---| |Unauthorized|Unauthorized| |Forbidden|Forbidden| |NotFound|Not found| |InternalServerError|Internal server error|
import { stateClient } from "@dynatrace-sdk/client-state";
const data = await stateClient.deleteAppState({
key: "some-key",
});
deleteAppStates
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.
import { stateClient } from "@dynatrace-sdk/client-state";
const data = await stateClient.deleteAppStates();
deleteUserAppState
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 |
Throws
| Error Type | Error Message | |---|---| |Unauthorized|Unauthorized| |Forbidden|Forbidden| |NotFound|Not found| |InternalServerError|Internal server error|
import { stateClient } from "@dynatrace-sdk/client-state";
const data = await stateClient.deleteUserAppState({
key: "some-key",
});
deleteUserAppStates
Delete all user app states
Required scope: state:user-app-states:delete
Deletes all user app states for the calling user and app.
import { stateClient } from "@dynatrace-sdk/client-state";
const data = await stateClient.deleteUserAppStates();
getAppState
Gets app state
Required scope: state:app-states:read
Parameters
| Name | Type | Description | | --- | --- | --- | |config.key*required|string|Specify the key of the state |
Returns
The app state
Throws
| Error Type | Error Message | |---|---| |Unauthorized|Unauthorized| |Forbidden|Forbidden| |NotFound|Not found| |InternalServerError|Internal server error|
import { stateClient } from "@dynatrace-sdk/client-state";
const data = await stateClient.getAppState({
key: "some-key",
});
getAppStates
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. | |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') |
Returns
The list of app states
Throws
| Error Type | Error Message | |---|---| |Unauthorized|Unauthorized| |Forbidden|Forbidden| |InternalServerError|Internal server error|
import { stateClient } from "@dynatrace-sdk/client-state";
const data = await stateClient.getAppStates();
getUserAppState
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 |
Returns
The user app state
Throws
| Error Type | Error Message | |---|---| |Unauthorized|Unauthorized| |Forbidden|Forbidden| |NotFound|Not found| |InternalServerError|Internal server error|
import { stateClient } from "@dynatrace-sdk/client-state";
const data = await stateClient.getUserAppState({
key: "some-key",
});
getUserAppStates
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. | |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') |
Returns
The list of user app states
Throws
| Error Type | Error Message | |---|---| |Unauthorized|Unauthorized| |Forbidden|Forbidden| |InternalServerError|Internal server error|
import { stateClient } from "@dynatrace-sdk/client-state";
const data = await stateClient.getUserAppStates();
setAppState
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 |
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|
import { stateClient } from "@dynatrace-sdk/client-state";
const data = await stateClient.setAppState({
key: "some-key",
body: { value: "some-state", validUntilTime: "now+2d" },
});
setUserAppState
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 |
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|
import { stateClient } from "@dynatrace-sdk/client-state";
const data = await stateClient.setUserAppState({
key: "some-key",
body: { value: "some-state", validUntilTime: "now+2d" },
});
Types
ApiClientError
Base error for all client SDKs. All other errors extend this class.
| Name | Type | Description | | --- | --- | --- | |cause|any| | |errorType*required|ErrorType| | |isApiClientError*required|true| | |message*required|string| | |name*required|string| | |stack|string| | |prepareStackTrace|Object|Optional override for formatting stack traces | |stackTraceLimit*required|number| |
ApiGatewayError
Dedicated error response class for errors thrown by API Gateway. Autogenerated SDK Clients have built-in handler for API Gateway errors that throws this error.
| Name | Type | Description | | --- | --- | --- | |body*required|ApiGatewayErrorResponseBody| | |cause|any| | |code*required|number| | |errorType*required|ErrorType| | |isApiClientError*required|true| | |isApiGatewayError*required|true| | |isClientRequestError*required|true| | |message*required|string| | |name*required|string| | |response*required|HttpClientResponse| | |retryAfterSeconds*required|undefined | number| | |stack|string| | |prepareStackTrace|Object|Optional override for formatting stack traces | |stackTraceLimit*required|number| |
AppStateLimitsExceeded
| Name | Type | Description | | --- | --- | --- | |~~body~~*requiredDEPRECATED|ErrorResponse| | |~~cause~~DEPRECATED|any| | |~~errorType~~*requiredDEPRECATED|ErrorType| | |~~isApiClientError~~*requiredDEPRECATED|true| | |~~isAppStateLimitsExceeded~~*requiredDEPRECATED|true| | |~~isClientRequestError~~*requiredDEPRECATED|true| | |~~isErrorResponseError~~*requiredDEPRECATED|true| | |~~message~~*requiredDEPRECATED|string| | |~~name~~*requiredDEPRECATED|"AppStateLimitsExceeded"| | |~~response~~*requiredDEPRECATED|HttpClientResponse| | |~~stack~~DEPRECATED|string| | |~~prepareStackTrace~~DEPRECATED|Object|Optional override for formatting stack traces | |~~stackTraceLimit~~*requiredDEPRECATED|number| |
ClientRequestError
Generic error class for service errors, used to handle both expected and unexpected service-level errors.
| Name | Type | Description | | --- | --- | --- | |body*required|DTO| | |cause|any| | |errorType*required|ErrorType| | |isApiClientError*required|true| | |isClientRequestError*required|true| | |message*required|string| | |name*required|string| | |response*required|HttpClientResponse| | |stack|string| | |prepareStackTrace|Object|Optional override for formatting stack traces | |stackTraceLimit*required|number| |
ErrorResponseError
| Name | Type | Description | | --- | --- | --- | |~~body~~*requiredDEPRECATED|ErrorResponse| | |~~cause~~DEPRECATED|any| | |~~errorType~~*requiredDEPRECATED|ErrorType| | |~~isApiClientError~~*requiredDEPRECATED|true| | |~~isClientRequestError~~*requiredDEPRECATED|true| | |~~isErrorResponseError~~*requiredDEPRECATED|true| | |~~message~~*requiredDEPRECATED|string| | |~~name~~*requiredDEPRECATED|string| | |~~response~~*requiredDEPRECATED|HttpClientResponse| | |~~stack~~DEPRECATED|string| | |~~prepareStackTrace~~DEPRECATED|Object|Optional override for formatting stack traces | |~~stackTraceLimit~~*requiredDEPRECATED|number| |
Forbidden
| Name | Type | Description | | --- | --- | --- | |~~body~~*requiredDEPRECATED|ErrorResponse| | |~~cause~~DEPRECATED|any| | |~~errorType~~*requiredDEPRECATED|ErrorType| | |~~isApiClientError~~*requiredDEPRECATED|true| | |~~isClientRequestError~~*requiredDEPRECATED|true| | |~~isErrorResponseError~~*requiredDEPRECATED|true| | |~~isForbidden~~*requiredDEPRECATED|true| | |~~message~~*requiredDEPRECATED|string| | |~~name~~*requiredDEPRECATED|"Forbidden"| | |~~response~~*requiredDEPRECATED|HttpClientResponse| | |~~stack~~DEPRECATED|string| | |~~prepareStackTrace~~DEPRECATED|Object|Optional override for formatting stack traces | |~~stackTraceLimit~~*requiredDEPRECATED|number| |
InternalServerError
| Name | Type | Description | | --- | --- | --- | |~~body~~*requiredDEPRECATED|ErrorResponse| | |~~cause~~DEPRECATED|any| | |~~errorType~~*requiredDEPRECATED|ErrorType| | |~~isApiClientError~~*requiredDEPRECATED|true| | |~~isClientRequestError~~*requiredDEPRECATED|true| | |~~isErrorResponseError~~*requiredDEPRECATED|true| | |~~isInternalServerError~~*requiredDEPRECATED|true| | |~~message~~*requiredDEPRECATED|string| | |~~name~~*requiredDEPRECATED|"InternalServerError"| | |~~response~~*requiredDEPRECATED|HttpClientResponse| | |~~stack~~DEPRECATED|string| | |~~prepareStackTrace~~DEPRECATED|Object|Optional override for formatting stack traces | |~~stackTraceLimit~~*requiredDEPRECATED|number| |
InvalidResponseError
Dedicated error class for errors related to response serialization. Thrown when received service response can't be deserialized.
| Name | Type | Description | | --- | --- | --- | |cause|any| | |errorType*required|ErrorType| | |expectedType|string| | |isApiClientError*required|true| | |isInvalidResponseError*required|true| | |message*required|string| | |name*required|string| | |nestedError|Error| | |response*required|any| | |responseBody*required|any| | |stack|string| | |prepareStackTrace|Object|Optional override for formatting stack traces | |stackTraceLimit*required|number| |
NotFound
| Name | Type | Description | | --- | --- | --- | |~~body~~*requiredDEPRECATED|ErrorResponse| | |~~cause~~DEPRECATED|any| | |~~errorType~~*requiredDEPRECATED|ErrorType| | |~~isApiClientError~~*requiredDEPRECATED|true| | |~~isClientRequestError~~*requiredDEPRECATED|true| | |~~isErrorResponseError~~*requiredDEPRECATED|true| | |~~isNotFound~~*requiredDEPRECATED|true| | |~~message~~*requiredDEPRECATED|string| | |~~name~~*requiredDEPRECATED|"NotFound"| | |~~response~~*requiredDEPRECATED|HttpClientResponse| | |~~stack~~DEPRECATED|string| | |~~prepareStackTrace~~DEPRECATED|Object|Optional override for formatting stack traces | |~~stackTraceLimit~~*requiredDEPRECATED|number| |
Unauthorized
| Name | Type | Description | | --- | --- | --- | |~~body~~*requiredDEPRECATED|ErrorResponse| | |~~cause~~DEPRECATED|any| | |~~errorType~~*requiredDEPRECATED|ErrorType| | |~~isApiClientError~~*requiredDEPRECATED|true| | |~~isClientRequestError~~*requiredDEPRECATED|true| | |~~isErrorResponseError~~*requiredDEPRECATED|true| | |~~isUnauthorized~~*requiredDEPRECATED|true| | |~~message~~*requiredDEPRECATED|string| | |~~name~~*requiredDEPRECATED|"Unauthorized"| | |~~response~~*requiredDEPRECATED|HttpClientResponse| | |~~stack~~DEPRECATED|string| | |~~prepareStackTrace~~DEPRECATED|Object|Optional override for formatting stack traces | |~~stackTraceLimit~~*requiredDEPRECATED|number| |
UserAppStateLimitsExceeded
| Name | Type | Description | | --- | --- | --- | |~~body~~*requiredDEPRECATED|ErrorResponse| | |~~cause~~DEPRECATED|any| | |~~errorType~~*requiredDEPRECATED|ErrorType| | |~~isApiClientError~~*requiredDEPRECATED|true| | |~~isClientRequestError~~*requiredDEPRECATED|true| | |~~isErrorResponseError~~*requiredDEPRECATED|true| | |~~isUserAppStateLimitsExceeded~~*requiredDEPRECATED|true| | |~~message~~*requiredDEPRECATED|string| | |~~name~~*requiredDEPRECATED|"UserAppStateLimitsExceeded"| | |~~response~~*requiredDEPRECATED|HttpClientResponse| | |~~stack~~DEPRECATED|string| | |~~prepareStackTrace~~DEPRECATED|Object|Optional override for formatting stack traces | |~~stackTraceLimit~~*requiredDEPRECATED|number| |
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 | |value*required|string| |
AppStates
extends Array<ListAppState>
| Name | Type | Description | | --- | --- | --- | |[unscopables]*required|Object|Is an object whose properties have the value 'true' when they will be absent when used in a 'with' statement. | |length*required|number|Gets or sets the length of the array. This is a number one higher than the highest index in the array. |
Error
| Name | Type | | --- | --- | |code*required|number| |details|ErrorDetails| |message*required|string|
ErrorDetails
| Name | Type | Description | | --- | --- | --- | |errorCode|ErrorDetailsErrorCode|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 UserAppStateSizeLimitExceeded - The user app state content exceeded the size limit for a single user app state UserAppStateCountLimitExceeded - The maximum number of user app states for this user and app was exceeded |
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 | |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 | |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 | |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 | |value*required|string| |
UserAppStates
extends Array<ListUserAppState>
| Name | Type | Description | | --- | --- | --- | |[unscopables]*required|Object|Is an object whose properties have the value 'true' when they will be absent when used in a 'with' statement. | |length*required|number|Gets or sets the length of the array. This is a number one higher than the highest index in the array. |
Enums
ErrorDetailsErrorCode
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 exceededUserAppStateSizeLimitExceeded
- The user app state content exceeded the size limit for a single user app stateUserAppStateCountLimitExceeded
- The maximum number of user app states for this user and app was exceeded
Enum keys
AppStateOverallSizeLimitExceeded
| UserAppStateCountLimitExceeded
| UserAppStateSizeLimitExceeded