DataStoreEntry

A key-value entry in a data store.

  • ĐƯỜNG DẪN TÀI NGUYÊN
  • /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

Thuộc Tính

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
Chỉ Xuất

The timestamp when the data store entry was created. Chuỗi này được định dạng là Dấu thời gian.

revisionIdstring
Bất Biến
Chỉ Xuất

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
Chỉ Xuất

The timestamp when the revision was created. Chuỗi này được định dạng là Dấu thời gian.

stateEnum<string>
Chỉ Xuất

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.

Giá trị JSON có thể là null, boolean, string, number, array hoặc object.

idstring
Chỉ Xuất

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 Cơ Sở
https://apis.roblox.com
Tài nguyên 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ản Beta

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.

Phạm Vi
universe-datastores.objects:list
Yêu CầuTham Số Đường Dẫn
universe_idstring
Bắt Buộc

The universe ID.

data_store_idstring
Bắt Buộc

The data-store ID.

Tham Số Truy Vấn
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.

Phản Hồi

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}'
Phản Hồi
{

  "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ản Beta

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.

Phạm Vi
universe-datastores.objects:create
Yêu CầuTham Số Đường Dẫn
universe_idstring
Bắt Buộc

The universe ID.

data_store_idstring
Bắt Buộc

The data-store ID.

Tham Số Truy Vấn
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.

Yêu Cầu Cơ ThểDataStoreEntry
Phản HồiDataStoreEntry
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"

}'
Phản Hồi
{

  "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ản Beta

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.

Phạm Vi
universe-datastores.objects:read
Yêu CầuTham Số Đường Dẫn
universe_idstring
Bắt Buộc

The universe ID.

data_store_idstring
Bắt Buộc

The data-store ID.

entry_idstring
Bắt Buộc

The entry ID.

Phản HồiDataStoreEntry
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}'
Phản Hồi
{

  "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ản Beta

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.

Phạm Vi
universe-datastores.objects:delete
Yêu CầuTham Số Đường Dẫn
universe_idstring
Bắt Buộc

The universe ID.

data_store_idstring
Bắt Buộc

The data-store ID.

entry_idstring
Bắt Buộc

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ản Beta

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.

Phạm Vi
universe-datastores.objects:update
Yêu CầuTham Số Đường Dẫn
universe_idstring
Bắt Buộc

The universe ID.

data_store_idstring
Bắt Buộc

The data-store ID.

entry_idstring
Bắt Buộc

The entry ID.

Tham Số Truy Vấn
allowMissingboolean

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

Yêu Cầu Cơ ThểDataStoreEntry
Phản HồiDataStoreEntry
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"

}'
Phản Hồi
{

  "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ản Beta

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.

Phạm Vi
universe-datastores.objects:createuniverse-datastores.objects:update
Yêu CầuTham Số Đường Dẫn
universe_idstring
Bắt Buộc

The universe ID.

data_store_idstring
Bắt Buộc

The data-store ID.

entry_idstring
Bắt Buộc

The entry ID.

Yêu Cầu Cơ Thể
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.

Phản HồiDataStoreEntry
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"

}'
Phản Hồi
{

  "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ản Beta

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>.

Phạm Vi
universe-datastores.versions:list
Yêu CầuTham Số Đường Dẫn
universe_idstring
Bắt Buộc

The universe ID.

data_store_idstring
Bắt Buộc

The data-store ID.

entry_idstring
Bắt Buộc

The entry ID.

Tham Số Truy Vấn
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".

Phản Hồi

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}'
Phản Hồi
{

  "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"

}