处理数据存储 API 请求

*此内容使用人工智能（Beta）翻译，可能包含错误。若要查看英文页面，请点按 此处。

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

权限设置

与所有开放云 API 类似，数据存储端口要求所有请求包含 x-api-key 头，其中包含 API 钥匙足以为请求提供权限。这需要您将钥匙应用到体验和数据存商店，并且 API 操作是允许的。如果钥匙无效，403 Unauthorized 将返回。有

节流阀

所有端口都有两种宇宙级别的限制：请求每分钟限制和通过率限制。 在每个体验中，请求每分钟限制允许您发送特定数量的请求每分钟，无论是API钥匙的数量。

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

标准数据存储限制

请求类型方法限制油门
写入

  • 设置入口
  • 增量入口
  • 删除入口
    • >

  • 10 MB/min/universe 写入速度
  • 300 requs/min/universe
阅读

    列数据存储 列入口 获取入口版本 1> 列入口版本1>

    4> 获取入口版本

    4>

  • 20 MB/min/universe 写入速度
  • 300 requs/min/universe

订购数据存储限制

请求类型方法限制油门
写入
  • 创建
  • 增量
  • 更新

    • 1> 删除 1> >

  • 300 请求/分钟/宇宙
阅读
  • 列表
  • 获取
  • 300 请求/分钟/宇宙

输入验证

在发送请求之前，请确保在端口上验证端口参数在格式要求和限制上基于以下表。 个端口可以有额外的要求在这些限制之上。如果参数不满足以下限制，端口将返回一个 400 Bad Request。

输入类型注释
universeId数

  • 您的体验独特标识。请参阅宇宙ID。
    • >

datastoreName字符串
  • 长度必须小于 50 字节。
  • 不能为空或为 null。
scope字符串
  • 数据存商店的范围。请参阅范围。
  • 长度必须小于 50 字节。
entryKey字符串
  • 长度必须小于 50 字节。
  • 不能为空或为 null。
content-md5字符串

  • 基础 64 编码 MD5 检查Sum
    • 内容。请参阅 内容-MD5。

roblox-entry-attributes字符串
  • 通过 JSON 对象串化。
  • 长度必须小于 300 字节。
roblox-entry-userids字符串
  • 通过 JSON 阵列 0-4 个数字序列化。
  • 不超过 4 个用户 ID。
cursor字符串

  • 在请求的结果设置中可用的更多数据的指示。见 按钮 .
    • >

宇宙ID

宇宙ID 是您想要访问您的数据存储的体验的唯一标识。体验的宇宙ID值是体验的 DataModel.GameId ，不是 不 是您的开始位置 ID，它是体验的开始位置。

您可以使用以下步骤获得体验的 宇宙 ID ：

  1. 导航到创建者仪表板。

  2. 查找您想要1) 使用权 2）通行证 3）访问权限问的数据存储体验。

  3. 点击目标体验缩略图上的 ⋯ 按钮，显示选项列表，然后选择 复制宇宙ID 。

    Copy Universe ID option from Creator Dashboard

范围

您可以通过将独特字符串设置为范围，该范围指定一个子文件为入口。一旦您设置一个范围，它就会自动预付在数据存商店上的所有键。范围是可选的，默认为 global 对于标准数据存储，但是对于命令数据存储的要求。

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

钥匙范围
房屋/User_1房屋
宠物/用户_1宠物
物品/用户_1物品栏

所有数据存储入口操作方法都有一个 Scope 参数，当您需要访问在非默认范围下存储的输入

此外，如果您想要列出一个或多个非默认范围的存储数据存储在一个数据存储中，您可以在

您不能在同一请求上传 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)

# 列出所有范围键为 true 的键

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



// 所有 Scopes 的回应

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

Content-MD5 是内容的 基础-64 编码 MD5 检查Sum。它是一个可选的请求头标，检查数据完整性并检测潜在问题。

您可以使用您的选择语言来计算 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==

# 使用仅标准的输入和输出

$ 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 二进制中编码您的请求体，才能计算检查Sum。

曲线

还可能返回一个 nextPageCursor 字符串，这表示要求结果设置中的数据是更多的。要获取它，请在下一个请求中提供此字符串。如果 cursor 参数是无效的，端点将返回 cursor。

曲сор字符串的格式是 未定义 。你不应该将它们解释或解析，因为它们可能随时改变。

过滤器

在发送请求到 List 方法为订购数据存储，您可以添加一个可选的 过滤器ilter 查询参数来返回具有特定范围的输入。

过滤器ilter 参数支持一个逻辑操作，&&，以及两个比较操作，<= 为设置最大值，1> >=1> 为设置最低值。如果您想要设置一个范围，并且设置一个最大值和最小值，请在两个序列之间添加4> &&4>。

例如，要将值小于或等于 10 的输入作为 filter 返回结果，您需要输入 entry <= 50 && entry >= 10 作为值。要将值小于 10 和 50 之间的输入作为 0> entry0> 返回结果，您需要输入 3> entry3> 。

以下示例是错误的 filter 值，可能会失败您的请求：

  • entry <= 10 - 不要在每个部分的序列中留有空格。
  • 10 <= entry - entry 和比较值在错误的一边。
  • entry <= 10 && entry <= 50 - && 只能用于指定两个比较操作器为 min 和 max 值的范围。

允许丢失的旗帜

当发送请求到 Update > 方法更新现有订购数据存储入口，您可以添加一个可选的 allow_missing 标记，允许创建一个入口即使存储入口不存在。

当您将 allow_missing 旗帜设置为 True 时：

  • 如果条目不存在，响应将返回一个新的条目。

  • 如果条目存在，但内容与条目的现有值匹配，那么现有条目仍然不会更改。

  • 如果条目存在，但内容与条目的现有价值不匹配，请返回该条目以更新其新内容值。