DataStoreEntry

A key-value entry in a data store.

  • CHEMINS POUR RESSOURCES
  • /cloud/v2/universes/{universe_id}/data-stores/{data_store_id}/entries
  • /cloud/v2/universes/{universe_id}/data-stores/{data_store_id}/scopes/{scope_id}/entries

Attributs

pathstring

The resource path of the data store entry.

Formats:

  • universes/{universe_id}/data-stores/{data_store_id}/entries/{data_store_entry_id}
  • universes/{universe_id}/data-stores/{data_store_id}/scopes/{data_store_scope_id}/entries/{data_store_entry_id}.
createTimestring
Sortie seule

The timestamp when the data store entry was created. Ce string est formatée en tant que Timestamp.

revisionIdstring
Immuable
Sortie seule

The revision ID of the data store entry.

A new revision is committed whenever the data store entry is changed in any way.

The format is an arbitrary string. Example: "foo".

revisionCreateTimestring
Sortie seule

The timestamp when the revision was created. Ce string est formatée en tant que Timestamp.

stateEnum<string>
Sortie seule

The state of the data store entry.

Possible values:

ValueDescription
STATE_UNSPECIFIEDThe default value. This value is used if the state is omitted.
ACTIVEThe default state of a newly created data store entry.
DELETEDThe data store entry is marked as deleted. At some point in the future, it will be permanently deleted.
etagstring

This checksum is computed by the server based on the value of other fields, and may be sent on update and delete requests (and potentially on certain custom methods) to ensure the client has an up-to-date value before proceeding.

valueJSON value

The value of the entry.

Une valeur JSON peut être null, boolean, string, number, array, ou object.

idstring
Sortie seule

The resource ID of the entry.

This matches the last segment of the resource path, and is provided only for convenience.

usersarray<string>

Users associated with the entry.

attributesobject

An arbitrary set of attributes associated with the entry.

URL de base
https://apis.roblox.com
La ressource DataStoreEntry
{

  "path": "universes/123/data-stores/some-data-store/entries/some-data-store-entry",

  "createTime": "2023-07-05T12:34:56Z",

  "revisionId": "string",

  "revisionCreateTime": "2023-07-05T12:34:56Z",

  "state": "STATE_UNSPECIFIED",

  "etag": "string",

  "value": "JSON value",

  "id": "string",

  "users": [

    "string"

  ],

  "attributes": "object"

}

DataStoreEntry

List Data Store Entries
Bêta

GET /cloud/v2/universes/{universe_id}/data-stores/{data_store_id}/entries

Returns a list of entries from a data store.

Only the path and id fields are populated; use GetDataStoreEntry to retrieve other fields.

Specify the wildcard scope (-) to list entries from all scopes.

Périmètres d'application
universe-datastores.objects:list
RequêteParamètres du chemin
universe_idstring
Requis

The universe ID.

data_store_idstring
Requis

The data-store ID.

Paramètres de requête
maxPageSizenumber

The maximum number of data store entries to return. The service might return fewer than this value. If unspecified, at most 10 data store entries are returned. The maximum value is 256 and higher values are set to 256.

pageTokenstring

A page token, received from a previous call, to retrieve a subsequent page.

When paginating, all other parameters provided to the subsequent call must match the call that provided the page token.

filterstring

This field may be set in order to filter the resources returned.

The filter field supports a very small subset of CEL:

  • Only the id field is supported.
  • Only the startsWith function is available; no other operators nor built-ins are supported.

Example filter: id.startsWith("foo").

showDeletedboolean

If true, resources marked for pending deletion will be included in the results.

Réponse

A list of DataStoreEntries in the parent collection.

dataStoreEntriesarray<DataStoreEntry>

The DataStoreEntries from the specified DataStore or DataStoreScope.

nextPageTokenstring

A token that you can send as a pageToken parameter to retrieve the next page. If this field is omitted, there are no subsequent pages.

GET /cloud/v2/universes/{universe_id}/data-stores/{data_store_id}/entries
curl -L -X GET 'https://apis.roblox.com/cloud/v2/universes/{universe_id}/data-stores/{data_store_id}/entries?maxPageSize=10&pageToken={string}&filter={string}&showDeleted={boolean}' \

  -H 'x-api-key: {your-api-key}'
Réponse
{

  "dataStoreEntries": [

    {

      "path": "universes/123/data-stores/some-data-store/entries/some-data-store-entry",

      "createTime": "2023-07-05T12:34:56Z",

      "revisionId": "string",

      "revisionCreateTime": "2023-07-05T12:34:56Z",

      "state": "STATE_UNSPECIFIED",

      "etag": "string",

      "value": "JSON value",

      "id": "string",

      "users": [

        "string"

      ],

      "attributes": "object"

    }

  ],

  "nextPageToken": "string"

}

DataStoreEntry

Create Data Store Entry
Bêta

POST /cloud/v2/universes/{universe_id}/data-stores/{data_store_id}/entries

Creates an entry with the provided ID and value.

Returns a 400 Bad Request if the entry exists.

Périmètres d'application
universe-datastores.objects:create
RequêteParamètres du chemin
universe_idstring
Requis

The universe ID.

data_store_idstring
Requis

The data-store ID.

Paramètres de requête
idstring

The ID to use for the data store entry, which will become the final component of the data store entry's resource path.

This value should be a 1-50 character string. We strongly recommend using only lowercase letters, numeric digits, and hyphens.

Corps de la requêteDataStoreEntry
RéponseDataStoreEntry
POST /cloud/v2/universes/{universe_id}/data-stores/{data_store_id}/entries
curl -L -X POST 'https://apis.roblox.com/cloud/v2/universes/{universe_id}/data-stores/{data_store_id}/entries?id=my-entry' \

  -H 'x-api-key: {your-api-key}' \

  -H 'Content-Type: application/json' \

  --data '{

  "etag": "string",

  "value": "JSON value",

  "users": [

    "string"

  ],

  "attributes": "object"

}'
Réponse
{

  "path": "universes/123/data-stores/some-data-store/entries/some-data-store-entry",

  "createTime": "2023-07-05T12:34:56Z",

  "revisionId": "string",

  "revisionCreateTime": "2023-07-05T12:34:56Z",

  "state": "STATE_UNSPECIFIED",

  "etag": "string",

  "value": "JSON value",

  "id": "string",

  "users": [

    "string"

  ],

  "attributes": "object"

}

DataStoreEntry

Get Data Store Entry
Bêta

GET /cloud/v2/universes/{universe_id}/data-stores/{data_store_id}/entries/{entry_id}

Gets the specified entry.

To get the entry at a specific revision, add @<revisionId> to the end of the path.

For example, to get my-entry at the revision ID 08DC3D3F43F9FCC1.0000000001.08DC3D3F43F9FCC1.01, use the path /v2/universes/1234/data-stores/5678/entries/my-entry@08DC3D3F43F9FCC1.0000000001.08DC3D3F43F9FCC1.01.

If your entry ID contains one or more @ characters, and you want to get the latest version rather than at any specific revision, append the special revision ID @latest to the end of the path. Otherwise, the segment of the entry ID after the last @ will be interpreted as a revision ID.

For example, to get the latest revision of my-entry, use the path /v2/universes/1234/data-stores/5678/entries/my@entry@latest.

To get the entry that was current at a specific time, add @latest:<timestamp> to the end of the path, where <timestamp> is RFC-3339 formatted. The given timestamp must be after the Unix epoch (1/1/1970) and not more than ten minutes in the future.

For example, to get the revision of my-entry that was current on 12/2/2024 at 06:00 UTC, use the path /v2/universes/1234/data-stores/5678/entries/my-entry@latest:2024-12-02T06:00:00Z.

Périmètres d'application
universe-datastores.objects:read
RequêteParamètres du chemin
universe_idstring
Requis

The universe ID.

data_store_idstring
Requis

The data-store ID.

entry_idstring
Requis

The entry ID.

RéponseDataStoreEntry
GET /cloud/v2/universes/{universe_id}/data-stores/{data_store_id}/entries/{entry_id}
curl -L -X GET 'https://apis.roblox.com/cloud/v2/universes/{universe_id}/data-stores/{data_store_id}/entries/{entry_id}' \

  -H 'x-api-key: {your-api-key}'
Réponse
{

  "path": "universes/123/data-stores/some-data-store/entries/some-data-store-entry",

  "createTime": "2023-07-05T12:34:56Z",

  "revisionId": "string",

  "revisionCreateTime": "2023-07-05T12:34:56Z",

  "state": "STATE_UNSPECIFIED",

  "etag": "string",

  "value": "JSON value",

  "id": "string",

  "users": [

    "string"

  ],

  "attributes": "object"

}

DataStoreEntry

Delete Data Store Entry
Bêta

DELETE /cloud/v2/universes/{universe_id}/data-stores/{data_store_id}/entries/{entry_id}

Marks the specified entry for deletion.

Entries are not be deleted immediately; instead, the state field will be set to DELETED. Permanent deletion occurs after 30 days.

On success, returns 200 OK. If the entry doesn't exist, returns 404 Not Found.

Périmètres d'application
universe-datastores.objects:delete
RequêteParamètres du chemin
universe_idstring
Requis

The universe ID.

data_store_idstring
Requis

The data-store ID.

entry_idstring
Requis

The entry ID.

DELETE /cloud/v2/universes/{universe_id}/data-stores/{data_store_id}/entries/{entry_id}
curl -L -X DELETE 'https://apis.roblox.com/cloud/v2/universes/{universe_id}/data-stores/{data_store_id}/entries/{entry_id}' \

  -H 'x-api-key: {your-api-key}'

DataStoreEntry

Update Data Store Entry
Bêta

PATCH /cloud/v2/universes/{universe_id}/data-stores/{data_store_id}/entries/{entry_id}

Updates the value, attributes, and users of an entry.

Updating specific revisions of the entry is unsupported. If you specify a revision ID in the path and allow_missing is true, the update request will instead create a new entry with the @<revisionId> suffix as part of the key.

Partial update is unsupported. If attributes or users are not provided when updating the value, they will be cleared. Value must always be provided when updating an entry.

Périmètres d'application
universe-datastores.objects:update
RequêteParamètres du chemin
universe_idstring
Requis

The universe ID.

data_store_idstring
Requis

The data-store ID.

entry_idstring
Requis

The entry ID.

Paramètres de requête
allowMissingboolean

If set to true, and the data store entry is not found, a data store entry is created.

Corps de la requêteDataStoreEntry
RéponseDataStoreEntry
PATCH /cloud/v2/universes/{universe_id}/data-stores/{data_store_id}/entries/{entry_id}
curl -L -X PATCH 'https://apis.roblox.com/cloud/v2/universes/{universe_id}/data-stores/{data_store_id}/entries/{entry_id}?allowMissing={boolean}' \

  -H 'x-api-key: {your-api-key}' \

  -H 'Content-Type: application/json' \

  --data '{

  "etag": "string",

  "value": "JSON value",

  "users": [

    "string"

  ],

  "attributes": "object"

}'
Réponse
{

  "path": "universes/123/data-stores/some-data-store/entries/some-data-store-entry",

  "createTime": "2023-07-05T12:34:56Z",

  "revisionId": "string",

  "revisionCreateTime": "2023-07-05T12:34:56Z",

  "state": "STATE_UNSPECIFIED",

  "etag": "string",

  "value": "JSON value",

  "id": "string",

  "users": [

    "string"

  ],

  "attributes": "object"

}

DataStoreEntry

Increment Data Store Entry
Bêta

POST /cloud/v2/universes/{universe_id}/data-stores/{data_store_id}/entries/{entry_id}:increment

Increments the value of the specified entry. Both the existing value and the increment amount must be integers.

If the entry doesn't exist, creates an entry with the specified value.

Incrementing specific revisions of the entry is unsupported. If you specify a revision ID in the path, the increment request will create a new entry with the @<revisionId> suffix as part of the key.

Known issue: the value may be incremented past the valid range of values. When this happens, the returned value will be clamped to the valid range, but the backend may persist the original value. This behavior is maintained for backwards compatibility reasons, but may change in a future version of this API.

Périmètres d'application
universe-datastores.objects:createuniverse-datastores.objects:update
RequêteParamètres du chemin
universe_idstring
Requis

The universe ID.

data_store_idstring
Requis

The data-store ID.

entry_idstring
Requis

The entry ID.

Corps de la requête
amountnumber

The amount by which to increment the entry value. Both the existing value and the increment amount must be integers.

usersarray<string>

Users associated with the entry.

If this is not provided, existing user IDs are cleared.

attributesobject

An arbitrary set of attributes associated with the entry.

If this is not provided, existing attributes are cleared.

RéponseDataStoreEntry
POST /cloud/v2/universes/{universe_id}/data-stores/{data_store_id}/entries/{entry_id}:increment
curl -L -X POST 'https://apis.roblox.com/cloud/v2/universes/{universe_id}/data-stores/{data_store_id}/entries/{entry_id}:increment' \

  -H 'x-api-key: {your-api-key}' \

  -H 'Content-Type: application/json' \

  --data '{

  "amount": "number",

  "users": [

    "string"

  ],

  "attributes": "object"

}'
Réponse
{

  "path": "universes/123/data-stores/some-data-store/entries/some-data-store-entry",

  "createTime": "2023-07-05T12:34:56Z",

  "revisionId": "string",

  "revisionCreateTime": "2023-07-05T12:34:56Z",

  "state": "STATE_UNSPECIFIED",

  "etag": "string",

  "value": "JSON value",

  "id": "string",

  "users": [

    "string"

  ],

  "attributes": "object"

}

DataStoreEntry

List Data Store Entry Revisions
Bêta

GET /cloud/v2/universes/{universe_id}/data-stores/{data_store_id}/entries/{entry_id}:listRevisions

List revisions of the data store entry.

This method returns partial data store entries.

In particular, only the path, id, createTime, revisionCreateTime, revisionId, etag, and state fields are populated. Both the path and id fields will have an @<version> suffix.

In order to get the full entry at a revision, you can use the provided path field with the GetDataStoreEntry method, i.e. GET /v1/universes/1234/data-stores/5678/entries/my-entry@<version>.

Périmètres d'application
universe-datastores.versions:list
RequêteParamètres du chemin
universe_idstring
Requis

The universe ID.

data_store_idstring
Requis

The data-store ID.

entry_idstring
Requis

The entry ID.

Paramètres de requête
maxPageSizenumber

The maximum number of revisions to return per page.

The service might return fewer than the maximum number of revisions. If unspecified, at most 10 revisions are returned. The maximum value is 100 values and higher values are set to 100.

pageTokenstring

A page token, received from a previous call, to retrieve a subsequent page.

When paginating, all other parameters provided to the subsequent call must match the call that provided the page token.

filterstring

Supports the following subset of CEL:

  • Only the &&, <=, and >= operators are supported.
  • Only the revision_create_time field is supported.

For example:

"revision_create_time >= 2000-01-01T00:00:00Z && revision_create_time <= 2001-01-01T00:00:00Z".

Réponse

A list of revisions of a data store entry.

dataStoreEntriesarray<DataStoreEntry>

The revisions of the data_store_entry.

nextPageTokenstring

A token that you send as a pageToken parameter to retrieve the next page. If this field is omitted, there are no subsequent pages.

GET /cloud/v2/universes/{universe_id}/data-stores/{data_store_id}/entries/{entry_id}:listRevisions
curl -L -X GET 'https://apis.roblox.com/cloud/v2/universes/{universe_id}/data-stores/{data_store_id}/entries/{entry_id}:listRevisions?maxPageSize=10&pageToken={string}&filter={string}' \

  -H 'x-api-key: {your-api-key}'
Réponse
{

  "dataStoreEntries": [

    {

      "path": "universes/123/data-stores/some-data-store/entries/some-data-store-entry",

      "createTime": "2023-07-05T12:34:56Z",

      "revisionId": "string",

      "revisionCreateTime": "2023-07-05T12:34:56Z",

      "state": "STATE_UNSPECIFIED",

      "etag": "string",

      "value": "JSON value",

      "id": "string",

      "users": [

        "string"

      ],

      "attributes": "object"

    }

  ],

  "nextPageToken": "string"

}