处理数据存储的 API 请求

在向标准数据存储和订阅数据存储发送请求之前，您需要了解如何正确处理它们。有关API的使用信息，请参阅使用指南。

授权

与所有开放云 API 一样，数据存储端点需要所有请求包含 x-api-key 头标，其中包含足够权限的 API 钥匙，用于满足请求。这需要您将钥匙应用到体验和数据存商店，端点操作被允许。如果密钥无效，403 Unauthorized将返回。了解API密钥的更多信息，请参阅管理API密钥。

限速

所有端点都有两种类型的宇宙级别限制：每分钟请求限制和带宽限制。随着每次体验，请求每分钟限制允许您每分钟发送一定数量的请求，而带宽限制允许您每分钟发送一定数量的数据，无论API密钥数量如何。

与 Luau API 不同，这些限制目前不基于用户数量进行缩放。超过这些限制会导致端点返回 429 Too Many Requests 。

标准数据存储限制带宽

请求类输入	方法	限制速度
写入	设置入口增量入口删除入口	10 MB/分钟/宇宙写入速度 300 请求/分钟/宇宙
阅读	列数据存储库列入口获取入口版本获取入口版本版本获取入口版本	20 MB/分钟/宇宙写入速度 300 请求/分钟/宇宙

订阅数据存储限制排序

请求类输入	方法	限制速度
写入	创建增量更新删除	300 请求/分钟/宇宙
阅读	列表获取	300 请求/分钟/宇宙

输入验证

在发送请求之前，请确保根据以下表格格式要求和约束验证端点参数。个人端点可以有超出这些的额外要求。如果参数不满足以下限制，端点返回一个 400 Bad Request 。

排序数据存储端点使用百分比编码对所有查询和身体参数进行编码。除非您的参数值中有特殊字符以破坏 URL，否则您不需要自己处理编码。

输入	类型	注释
universeId	数字	您体验的唯一标识。请参阅宇宙ID。
datastoreName	字符串	长度必须小于 50 字节。不能为空或为空。
scope	字符串	数据存商店的范围。请参阅范围。长度必须少于 50 字节。
entryKey	字符串	长度必须小于 50 字节。不能为空或为空。
content-md5	字符串	内容的 base-64 编码 MD5 校验。请参阅内容-MD5 。
roblox-entry-attributes	字符串	通过 JSON 对象序列化。长度必须小于 300 字节。
roblox-entry-userids	字符串	通过 0-4 数字的 JSON 阵列序列化。不超过 4 个用户 ID。
cursor	字符串	请求结果设置中可用的更多数据的指标。请参阅鼠标。

宇宙ID

宇宙ID 是您想要访问数据存储的体验唯一标识符。体验宇宙ID的值是其的值，不同于开始地点ID，识别体验的开始地点而不是整个体验。

您可以通过以下步骤获得体验的宇宙ID ：

导航到创建者仪表板。
找到你想要1) 使用权 2）通行证 3）访问权限问的数据存储体验。
将鼠标悬停在体验缩略图上，单击 ⋯ 按钮，然后选择复制宇宙ID 。

范围

您可以通过设置一个唯一的字符串为范围来组织数据存储，该范围指定入口的子目录。一旦你设置了范围，它将自动添加到数据存商店中所有操作的所有键。范围是可选的，默认为 global 对标准数据存储，但对订阅数据存储必需。

强烈建议使用参数取代排序和列出标准数据存储。

范围用字符串和 "/" 分隔符将您的数据分类，例如：

关键	范围
房屋/用户_1	房屋
宠物/用户_1	宠物
库存/用户_1	道具

所有数据存储入口操作方法都有一个 Scope 参数，当你需要访问非默认范围下存储的入口时。例如，你可能会在默认的 1234 范围下拥有一个 global 键，在 special 范围下拥有相同的键。你可以无需使用范围参数访问前者，但要访问后者，你必须在或访问 API 调用中指定范围参数为。

此外，如果你想枚举一个或多个非默认范围的数据存储中存储的所有键，你可以在方法中设置参数为 ,在此情况下，调用返回包含键字和范围的 tuple 的 tuple。在上一个例子中，将返回两者（》，）和（》，》）在响应中。

您不能在同一请求中传递 Scope 和 AllScopes 参数，否则调用将返回错误。利用开放云 API 数据存储模块中的帮助函数，以下代码展示了您如何使用自定义范围阅读数据存储中的每个键：

列出不同范围的键
# 设置
import tutorialFunctions
DatastoresApi = tutorialFunctions.DataStores()
datastoreName = "PlayerInventory"

# 列出全球范围的键
specialScopeKeys = DatastoresApi.list_entries(datastoreName, scope = "global", allScopes = False)
print(keys.content)
# 列出特殊范围的键
specialScopeKeys = DatastoresApi.list_entries(datastoreName, scope = "special", allScopes = False)
print(keys.content)
# 列出所有范围设置为真的钥匙
specialScopeKeys = DatastoresApi.list_entries(datastoreName, allScopes = True)
print(specialScopeKeys.content)

与相应范围的钥匙在响应中返回：

不同范围的示例回应
// 全球范围的响应
{ "keys": [{ "scope": "global", "key": "User_2" }], "nextPageCursor": "" }

// 特殊范围的响应
{"keys":[{"scope":"special","key":"User_6"},{"scope":"special","key":"User_7"}],"nextPageCursor":""}

// 对于 AllScopes 的响应
{"keys":[{"scope":"global","key":"User_3"},{"scope":"global","key":"User_4"},{"scope":"global","key":"User_5"},{"scope":"special","key":"User_6"},{"scope":"special","key":"User_7"}],"nextPageCursor":""}

内容-MD5

内容-MD5是内容的基础64编码MD5校验。它是可选的设置输入端点的请求头，检查数据完整性并检测潜在问题。

如果你在请求中没有包含 content-md5 头标，虽然概率很低，但仍有可能发生数据丢失。

您可以使用自己选择的语言来计算 content-md5 头部的值。下面的例子使用了 Python。hashlib.md5() 和 base64.b64encode() 函数可用于 Python 标准库（2.7、3+）。

生成内容-MD5
# 带有提示
$ python -c "import base64, hashlib; print('content-md5: ' + str(base64.b64encode(hashlib.md5(bytes(input('content: '), encoding='utf8')).digest()), encoding='utf8'))"
content: 750
content-md5: sTf90fedVsft8zZf6nUg8g==
# 仅使用 stdin 和 stdout
$ echo "750" | python -c "import base64, hashlib; print(str(base64.b64encode(hashlib.md5(bytes(input(), encoding='utf8')).digest()), encoding='utf8'))"
sTf90fedVsft8zZf6nUg8g==

如果您遇到生成有效 content-md5 值时出现问题，您可能需要在计算校验之前将请求体编码为 UTF-8 二进制文件。

鼠标

返回数据列表的端点也可能返回 nextPageCursor 字符串。这表明请求的结果设置中包含更多数据。要收到它，在后续请求中提供此字符串在 cursor 查询参数上。如果커서参数提供但无效，端点返回 400 Bad Request。

鼠标字符串的格式不是未定义。你不应该解释或解析它们，因为它们随时可能发生变化。

过滤器

向订阅数据存储方法 List 发送请求时，您可以添加可选的 filter 查询参数来返回具有指定范围值的条目。

filter 参数支持一个逻辑运算符、&& ,和两个比较运算符、<= 来设置最大值和 >= 来设置最小值。如果您想设置一个范围包含最大值和最小值，请在两个序列之间添加 &&。

例如，要返回价值小于或等于 10 的入口，你需要输入 entry <= 10 作为 filter 值。要返回值为 10 到 50 之间的输入，输入 entry <= 50 && entry >= 10 .

要输入有效的 filter 值，您需要将所有 filter 字符串格式化为每个部分之间包含空格的顺序。每个序列的左部必须以“入口”开始，右部必须有数值。Filter 字符串也是敏感大小写的。

以下例子是错误的 filter 值，可能会导致请求失败：

entry <= 10 - 每个部分之间没有空格。
10 <= entry - entry 和比较值在错误的一侧。
entry <= 10 && entry <= 50 - && 只能用于指定两个比较操作符与最小和最大值的范围。

允许缺少的旗帜

当向 Update 方法发送请求以更新现有订阅数据存储入口时，您可以添加可选的 allow_missing 标志，以允许存在即使入口不存在。

当你将 allow_missing 旗设置为 True 时：

如果入口不存在，响应返回一个新的入口。
如果入口存在但内容与现有入口的值匹配，现有入口保持不变。
如果入口存在且内容不匹配入口的现有值，响应返回更新的新内容值的入口。

在此页面