体验配置 | 文档 - Roblox 创作者中心

配置 API 允许您以编程方式管理体验配置，而不是使用 Creator Hub 或 Studio。本指南涵盖典型流程：

创建或更新草稿配置。
发布配置。
获取最新的配置值。
使用版本历史记录回滚到之前的值。

您发布的值会立即在您的体验中可用。在服务器脚本中，使用 ConfigService 读取配置并响应实时更新。ConfigService:GetConfigAsync() 和 ConfigSnapshot:GetValue() 允许您读取值，而 ConfigSnapshot.UpdateAvailable 结合 ConfigSnapshot:Refresh() 或 ConfigSnapshot:GetValueChangedSignal() 使您能够在值更改时做出响应。有关 Luau 代码示例和进一步的细节，请参阅将配置添加到您的代码和刷新快照的体验配置指南。

在开始之前，请生成 API 密钥或配置 OAuth 2.0 应用。读取操作需要 universe:read 范围。写入操作（草稿、发布、恢复）需要 universe:write。

所有端点都使用您的宇宙 ID，您可以在 Creator Dashboard 上找到它。单击体验瓦片的溢出菜单并复制宇宙 ID。

有关完整的端点参考、请求和响应架构以及错误代码，请参见 Cloud API 参考。

存储库

对配置端点的请求在路径中使用存储库，并在请求体中使用 entries 对象。例如，此请求添加一个草稿配置：


PATCH /creator-configs-public-api/v1/configs/universes/<UNIVERSE_ID>/repositories/<REPOSITORY>/draft
{
  "entries": {
    "enableNewTutorial": true
  }
}

存储库按产品不同而有所不同，并按系统分隔配置。
条目是配置的键值对。您发送和接收一个包含键值的单一扁平对象。

本指南涵盖体验内配置，因此所有请求都使用 InExperienceConfig 作为存储库。存储库最终将扩展以涵盖其他产品和用例。

用例	存储库
体验内配置	InExperienceConfig

创建或更新配置

在上线之前，配置更改被暂存为草稿。您可以通过一个操作设置整个配置或应用部分更新，直到您满意为止：

从头开始或替换所有内容 — 使用覆盖端点，这样有效负载就是所需的完整状态。任何您省略的键将被视为已删除。
仅更改某些键 — 使用部分更新端点，这样您发送的键仅会被更新；其他所有内容保持不变。

以下示例代码将 bossHealth 设置为 100 并使用覆盖端点：


import requests

API_KEY = "<API_KEY>"
UNIVERSE_ID = "<UNIVERSE_ID>"
BASE = f"https://apis.roblox.com/creator-configs-public-api/v1/configs/universes/{UNIVERSE_ID}/repositories/InExperienceConfig"
headers = {"x-api-key": API_KEY, "Content-Type": "application/json"}

# 可选：如果您有现有草稿并希望进行乐观并发，请发送 previousDraftHash
payload = {
    "entries": {
        "bossHealth": 100
    }
}
r = requests.put(f"{BASE}/draft:overwrite", headers=headers, json=payload)
r.raise_for_status()
draft = r.json()
draft_hash = draft["draftHash"]  # 将其保留用于发布
print("草稿已暂存。draftHash:", draft_hash)

响应包含 draftHash 值。您需要此哈希才能发布。如果您只希望调整草稿中的几个键，请在 /draft 端点上使用 PATCH 方法，并仅发送您希望更改的条目（键）。

关于草稿哈希

草稿哈希是您草稿当前状态的一个不透明标识符。API 在任何对草稿的读写操作后（创建、更新、覆盖、重置、恢复）返回它。

在更新或发布草稿时，您可以在请求体中发送 previousDraftHash。如果哈希与服务器当前的草稿不匹配（例如，其他人此时已发布或编辑），请求将失败。然后，您可以重新读取更新后的草稿，获取新的哈希，并重试或合并更改。

在调用发布或进行另一次草稿更改之前，始终保存来自上次草稿响应的 draftHash，特别是在使用 previousDraftHash 时。

发布您的更改

当您对草稿满意时，发布它以便新值上线。传递来自草稿响应的 draftHash、用于版本历史目的的 message 和 deploymentStrategy（使用 GradualRollout 进行 15 分钟的逐步发布或使用 Immediate）。以下示例代码立即部署配置：


publish_payload = {
    "draftHash": draft_hash,
    "message": "将boss健康值设置为100",
    "deploymentStrategy": "Immediate"
}
r = requests.post(f"{BASE}/publish", headers=headers, json=publish_payload)
r.raise_for_status()
result = r.json()
print("已发布。configVersion:", result["configVersion"])

发布成功后，草稿被清除，您的体验将根据发布策略接收新配置。响应包含新配置版本：


{
  "configVersion": 6
}

获取已发布的配置

为了确认更改是否成功，请获取最新发布的配置。当您只需要键和值时，请使用仅值端点；当您也需要元数据（描述、最后访问时间等）时，请使用完整端点。以下示例代码使用仅值端点，完整端点被注释掉：


# 仅值（与 RCC 和您的游戏看到的相同形状）
r = requests.get(BASE, headers=headers)
r.raise_for_status()
config = r.json()
boss_health = config["entries"].get("bossHealth")
print("已发布的 bossHealth:", boss_health)  # 应为 100

# 或者使用完整元数据：
# r = requests.get(f"{BASE}/full", headers=headers)

确保 entries.bossHealth（或您的键）与您发布的内容匹配。

查看历史记录和回滚

每次发布都会创建一个修订版本，就像版本控制系统一样。您可以列出修订记录以查看谁更改了什么以及何时更改，然后在需要回滚时恢复到先前的修订版本。

以下示例代码调用修订端点并打印结果。每个修订都包括 revisionId、version、time、publishedBy、message 和 changes（键、“之前”的值和“之后”的值）。


r = requests.get(f"{BASE}/revisions", headers=headers, params={"MaxPageSize": 10})
r.raise_for_status()
data = r.json()
for rev in data["revisions"]:
    print(rev["version"], rev["time"], rev["message"], "— revisionId:", rev["revisionId"])

要回滚，请使用您想要恢复的 revisionId 调用还原端点。这将清除当前草稿并暂存还原提交；这并不会发布。要发布，您必须使用返回的 draftHash 调用 publish，就像发布新更改一样。


REVISION_ID = "1234567890"  # 来自上面的列表
r = requests.post(f"{BASE}/revisions/{REVISION_ID}/restore", headers=headers)
r.raise_for_status()
restore_draft = r.json()
restore_hash = restore_draft["draftHash"]

# 发布还原
publish_payload = {
    "draftHash": restore_hash,
    "message": "回滚到之前的配置",
    "deploymentStrategy": "Immediate"
}
r = requests.post(f"{BASE}/publish", headers=headers, json=publish_payload)
r.raise_for_status()
print("回滚发布成功。configVersion:", r.json()["configVersion"])

限制

限制	最大值
每个存储库的键	100
键长度	256 个字符

超出这些限制的请求将失败。有关您体验中特定值限制（例如字符串与 JSON）的详细信息，请参阅体验配置指南中的限制。

有关本指南中所有端点的完整详细信息，请参见 Cloud API 参考。