경험 구성 | 설명서 - 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를 사용합니다. 이 ID는 Creator Dashboard에서 찾을 수 있습니다. 경험 타일의 오버플로우 메뉴를 클릭하고 유니버스 ID 복사를 선택하십시오.

전체 엔드포인트 참조, 요청 및 응답 스키마, 오류 코드를 보려면 Cloud API 참조를 참조하십시오.

리포지토리

구성 엔드포인트에 대한 요청은 경로에서 리포지토리를 사용하고 요청 본문에 entries 객체를 포함합니다. 예를 들어, 이 요청은 초안 구성을 추가합니다:


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

리포지토리는 제품에 따라 다르고 구성은 시스템별로 구분됩니다.
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"}

# 선택 사항: 이전 초안 해시를 전송하여 기존 초안이 있는 경우 낙관적 동시성을 처리합니다.
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를 전송할 수 있습니다. 해시가 서버의 현재 초안과 일치하지 않으면(예: 누군가 그 사이에 게시하거나 편집한 경우) 요청이 실패합니다. 그런 다음 업데이트된 초안을 다시 읽고 새 해시를 가져온 후 변경 사항을 다시 시도하거나 병합할 수 있습니다.

항상 게시 호출 전 또는 previousDraftHash를 사용하는 경우 다른 초안 변경을 수행하기 전에 마지막 초안 응답에서 draftHash를 저장하십시오.

변경 사항 게시

초안이 만족스러우면 게시하여 새로운 값이 라이브 상태가 되도록 합니다. 초안 응답의 draftHash, 버전 기록 목적을 위한 message, deploymentStrategy(15분 롤아웃을 위한 GradualRollout 또는 즉시 게시)를 전달합니다. 다음 샘플 코드는 구성을 즉시 배포합니다:


publish_payload = {
    "draftHash": draft_hash,
    "message": "보스 체력을 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("게시된 보스 체력:", 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 참조를 참조하십시오.