體驗配置 | 文件 - Roblox 創作者中心

configs 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，你可以在創作者儀表板中找到。單擊體驗區塊的溢出菜單，然後複製宇宙 ID。

有關完整的端點參考、請求和回應架構及錯誤代碼，請參見 Cloud API 參考。

倉庫

對配置端點的請求使用路徑中的 repository 和請求主體中的 entries 對象。例如，這個請求添加了一個草稿配置：


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

Repositories 根據產品而異，並將配置按系統分開。
Entries 是配置的鍵值對。你發送和接收一個扁平的鍵值對象。

本指南涵蓋體驗內配置，因此所有請求都使用 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 值。你需要這個哈希以便發布。如果你更喜歡只調整草稿中的幾個鍵，則使用 PATCH 方法在 /draft 端點上，只發送你想更改的條目（鍵）。

有關草稿哈希的說明

草稿哈希是一個不透明的標識符，用於表示你草稿的當前狀態。在對草稿進行任何讀取或寫入操作（創建、更新、覆蓋、重置、還原）後，API 會返回它。

在更新或發布草稿時，你可以在請求主體中發送 previousDraftHash。如果哈希與服務器當前的草稿不匹配（例如，其他人此時發布或編輯），請求將失敗。然後你可以重新讀取更新的草稿，獲取新的哈希，然後重試或合併更改。

如果你使用 previousDraftHash，請務必在調用發布或進行另一個草稿更改之前保存最後草稿響應中的 draftHash。

發布更改

當你對草稿感到滿意時，發布它以便新值上線。傳遞來自草稿響應的 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 參考。