การตั้งค่าประสบการณ์

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 reference

รีโพสิตอรี

คำขอไปยังจุดสิ้นสุดการตั้งค่าจะใช้ รีโพสิตอรี ในเส้นทางและอ็อบเจ็กต์ entries ในคำขอ ตัวอย่างเช่น คำขอนี้จะเพิ่มการตั้งค่าร่าง:

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

• รีโพสิตอรี จะแตกต่างกันไปตามผลิตภัณฑ์และแยกการตั้งค่าโดยระบบ
• Entries คือคู่ค่าและคีย์การตั้งค่า คุณจะส่งและรับอ็อบเจ็กต์แบนเดียวที่มีคีย์และค่า

คู่มือนี้ครอบคลุมการตั้งค่าในประสบการณ์ ดังนั้นคำขอทั้งหมดจะใช้ InExperienceConfig สำหรับรีโพสิตอรี รีโพสิตอรีจะขยายให้ครอบคลุมผลิตภัณฑ์และกรณีการใช้งานเพิ่มเติมในอนาคต

สร้างหรืออัปเดตการตั้งค่า

ก่อนที่จะเผยแพร่ การเปลี่ยนแปลงการตั้งค่าจะถูกสร้างเป็นร่าง คุณสามารถตั้งค่าการตั้งค่าทั้งหมดในครั้งเดียวหรือใช้การอัปเดตบางส่วนจนกว่าคุณจะพอใจกับมัน:

• เริ่มจากศูนย์หรือการแทนที่ทุกอย่าง — ใช้จุดสิ้นสุดการเขียนทับ ดังนั้น Payload จะอยู่ในสถานะที่ต้องการทั้งหมด ใด ๆ ที่คุณละเว้นจะถูกมองว่าเป็นการลบออก
• เปลี่ยนแปลงเพียงบางคีย์ — ใช้จุดสิ้นสุดการอัปเดตบางส่วน ดังนั้นเพียงคีย์ที่คุณส่งจะได้รับการอัปเดต ส่วนที่เหลือจะยังคงเหมือนเดิม

ตัวอย่างโค้ดนี้ตั้งค่า 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"}

# Optional: send previousDraftHash if you have an existing draft and want optimistic concurrency
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"]  # Keep this for publishing
print("Draft staged. draftHash:", draft_hash)

การตอบกลับรวมถึงค่า draftHash คุณต้องใช้แฮชนี้ในการเผยแพร่ หากคุณต้องการปรับแต่งเพียงไม่กี่คีย์ในร่างของคุณ ให้ใช้วิธี PATCH ที่จุดสิ้นสุด /draft และส่งเพียงอ็อบเจ็กต์ entries (คีย์) ที่คุณต้องการเปลี่ยนแปลงเท่านั้น

เกี่ยวกับรหัสร่าง

รหัสร่าง เป็นตัวระบุที่ไม่โปร่งใสสำหรับสถานะปัจจุบันของร่างของคุณ API จะส่งคืนหลังจากการดำเนินการอ่านหรือเขียนใด ๆ บนร่าง (สร้าง, อัปเดต, เขียนทับ, รีเซ็ต, คืนค่า)

เมื่อเจรจาหรือเผยแพรร่าง คุณสามารถส่ง previousDraftHash ในร่างของคำขอ หากแฮชไม่ตรงกับร่างปัจจุบันของเซิร์ฟเวอร์ (เช่น มีผู้อื่นเผยแพร่หรือแก้ไขในระหว่างเวลา) คำขอจะล้มเหลว คุณสามารถอ่านร่างที่อัปเดตใหม่ รับแฮชใหม่ และลองใหม่หรืิอรวมการเปลี่ยนแปลง

ควรบันทึก draftHash จากการตอบกลับร่างล่าสุดก่อนที่จะเรียกเผยแพร่หรือก่อนที่จะทำการเปลี่ยนแปลงร่างอีกครั้งหากคุณใช้ previousDraftHash

เผยแพร่การเปลี่ยนแปลงของคุณ

เมื่อคุณพอใจกับร่างแล้ว ให้เผยแพร่เพื่อให้ค่าที่ใหม่เผยแพร่สู่สาธารณะ ส่งผ่าน draftHash จากการตอบกลับร่าง message เพื่อประวัติรุ่น และ deploymentStrategy (เลือก GradualRollout สำหรับการเผยแพร่ภายใน 15 นาทีหรือ Immediate) ตัวอย่างโค้ดด้านล่างเผยแพร่การตั้งค่าแบบทันที:

publish_payload = {
    "draftHash": draft_hash,
    "message": "Set boss health to 100",
    "deploymentStrategy": "Immediate"
}
r = requests.post(f"{BASE}/publish", headers=headers, json=publish_payload)
r.raise_for_status()
result = r.json()
print("Published. configVersion:", result["configVersion"])

หลังจากการเผยแพร่ที่สำเร็จ ร่างจะถูกลบข้อมูลและประสบการณ์ของคุณจะได้รับการตั้งค่าใหม่ตามกลยุทธ์การเผยแพร่ การตอบกลับจะรวมถึงรุ่นการตั้งค่าใหม่:

{
  "configVersion": 6
}

รับการตั้งค่าที่เผยแพร่ของคุณ

เพื่อยืนยันว่าการเปลี่ยนแปลงเป็นไปตามที่ต้องการ ให้ดึงการตั้งค่า ที่เผยแพร่ล่าสุด ใช้จุดสิ้นสุดเฉพาะค่าเมื่อคุณต้องการแค่คีย์และค่า; ใช้จุดสิ้นสุดเต็มเมื่อคุณต้องการข้อมูลเมตา (คำอธิบาย เวลาที่เข้าถึงล่าสุด ฯลฯ) ตัวอย่างโค้ดนี้ใช้จุดสิ้นสุดเฉพาะค่า โดยมีจุดสิ้นสุดเต็มที่ถูกคอมเมนต์ออก:

# Values only (same shape RCC and your game see)
r = requests.get(BASE, headers=headers)
r.raise_for_status()
config = r.json()
boss_health = config["entries"].get("bossHealth")
print("Published 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 ที่คุณต้องการเพิกถอน ซึ่งจะลบร่างปัจจุบันและสร้างการย้อนกลับ commit โดยจะไม่เผยแพร่ เพื่อให้เผยแพร่ คุณต้องเรียก publish พร้อมกับ draftHash ที่ส่งคืน เช่นเดียวกับการเผยแพร่การเปลี่ยนแปลงใหม่

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": "Rollback to previous config",
    "deploymentStrategy": "Immediate"
}
r = requests.post(f"{BASE}/publish", headers=headers, json=publish_payload)
r.raise_for_status()
print("Rollback published. configVersion:", r.json()["configVersion"])

ข้อจำกัด

คำขอที่เกินขีดจำกัดเหล่านี้จะล้มเหลว สำหรับข้อจำกัดเฉพาะประเภทค่าต่าง ๆ (ตัวอย่างเช่น สตริง vs JSON) ในประสบการณ์ของคุณ ดูที่ Limits ในคู่มือการตั้งค่าประสบการณ์

สำหรับรายละเอียดทั้งหมดเกี่ยวกับจุดสิ้นสุดทั้งหมดในคู่มือนี้ ดูที่ Cloud API reference.