Konfigurasi Pengalaman

API konfigurasi memungkinkan Anda mengelola konfigurasi pengalaman secara programatik daripada menggunakan Creator Hub atau Studio. Panduan ini mencakup alur kerja yang tipikal:

• Buat atau perbarui konfigurasi draf.
• Terbitkan.
• Dapatkan nilai konfigurasi terbaru.
• Kembali ke nilai sebelumnya menggunakan riwayat versi.

Nilai yang Anda terbitkan tersedia di pengalaman Anda segera. Dalam skrip server, gunakan ConfigService untuk membaca konfigurasi dan bereaksi terhadap pembaruan waktu nyata. ConfigService:GetConfigAsync() dan ConfigSnapshot:GetValue() memungkinkan Anda membaca nilai, dan ConfigSnapshot.UpdateAvailable dengan ConfigSnapshot:Refresh() atau ConfigSnapshot:GetValueChangedSignal() memungkinkan Anda merespons saat nilai berubah. Untuk contoh kode Luau dan rincian lebih lanjut, lihat Tambahkan konfigurasi ke kode Anda dan Segarkan snapshot di panduan konfigurasi pengalaman.

Sebelum Anda mulai, hasilkan kunci API atau konfigurasikan aplikasi OAuth 2.0. Operasi baca memerlukan cakupan universe:read. Operasi tulis (draf, terbitkan, kembalikan) memerlukan universe:write.

Semua titik akhir menggunakan ID alam semesta Anda, yang dapat Anda temukan di Dasbor Creator. Klik menu overflow ubin pengalaman dan Salin ID Alam Semesta.

Untuk referensi lengkap titik akhir, skema permintaan dan respons, serta kode kesalahan, lihat referensi API Cloud.

Repositories

Permintaan ke titik akhir konfigurasi menggunakan repository dalam jalur dan objek entries dalam tubuh permintaan. Sebagai contoh, permintaan ini menambahkan konfigurasi draf:

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

• Repositories berbeda berdasarkan produk dan memisahkan konfigurasi berdasarkan sistem.
• Entries adalah pasangan kunci-nilai konfigurasi. Anda mengirim dan menerima satu objek datar dari kunci dan nilai.

Panduan ini mencakup konfigurasi dalam pengalaman, jadi semua permintaan menggunakan InExperienceConfig untuk repository. Repositories pada akhirnya akan diperluas untuk mencakup produk dan kasus penggunaan tambahan.

Buat atau perbarui konfigurasi

Sebelum go live, perubahan konfigurasi diaktifkan sebagai draf. Anda bisa mengatur seluruh konfigurasi dalam satu operasi atau menerapkan pembaruan sebagian sampai Anda puas dengan itu:

• Memulai dari nol atau mengganti semuanya — Gunakan titik akhir overwrite sehingga payload adalah keadaan penuh yang diinginkan. Setiap kunci yang Anda lewatkan dianggap dihapus.
• Mengubah hanya beberapa kunci — Gunakan titik akhir pembaruan sebagian sehingga hanya kunci yang Anda kirim yang diperbarui; semuanya yang lain tetap seperti semula.

Kode contoh ini mengatur bossHealth menjadi 100 dan menggunakan titik akhir overwrite:

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

# Opsional: kirim previousDraftHash jika Anda memiliki draf yang ada dan ingin optimis dalam pengaturan bersamaan
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"]  # Simpan ini untuk penerbitan
print("Draf berhasil dibuat. draftHash:", draft_hash)

Responsnya mencakup nilai draftHash. Anda perlu hash ini untuk menerbitkan. Jika Anda lebih suka hanya mengubah beberapa kunci di draf Anda, gunakan metode PATCH pada titik akhir /draft dan hanya kirim entry (kunci) yang ingin Anda ubah.

Tentang draft hashes

Draft hash adalah pengidentifikasi tidak transparan untuk keadaan saat ini dari draf Anda. API mengembalikannya setelah operasi baca atau tulis ke draf (buat, perbarui, overwrite, reset, kembalikan).

Saat memperbarui atau menerbitkan draf, Anda dapat mengirim previousDraftHash dalam tubuh permintaan. Jika hash tidak cocok dengan draf saat ini di server (misalnya, orang lain menerbitkan atau mengedit di antara waktu tersebut), permintaan gagal. Anda kemudian dapat membaca kembali draf yang diperbarui, mendapatkan hash baru, dan mencoba lagi atau menggabungkan perubahan.

Selalu simpan draftHash dari respons draf terakhir sebelum memanggil penerbitan atau sebelum melakukan perubahan draf lainnya jika Anda menggunakan previousDraftHash.

Terbitkan perubahan Anda

Ketika Anda puas dengan draf, terbitkan sehingga nilai baru menjadi langsung. Lewati draftHash dari respons draf, message untuk keperluan riwayat versi, dan deploymentStrategy (baik GradualRollout untuk perrollout 15 menit atau Immediate). Kode contoh berikut menerbitkan konfigurasi segera:

publish_payload = {
    "draftHash": draft_hash,
    "message": "Mengatur kesehatan bos menjadi 100",
    "deploymentStrategy": "Immediate"
}
r = requests.post(f"{BASE}/publish", headers=headers, json=publish_payload)
r.raise_for_status()
result = r.json()
print("Diterbitkan. configVersion:", result["configVersion"])

Setelah penerbitan yang berhasil, draf dihapus, dan pengalaman Anda menerima konfigurasi baru sesuai dengan strategi penerbitan. Responsnya mencakup versi konfigurasi baru:

{
  "configVersion": 6
}

Dapatkan konfigurasi yang diterbitkan

Untuk mengonfirmasi bahwa perubahan berhasil, ambil konfigurasi yang telah diterbitkan terbaru. Gunakan titik akhir nilai saja ketika Anda hanya membutuhkan kunci dan nilai; gunakan titik akhir penuh ketika Anda juga membutuhkan metadata (deskripsi, waktu terakhir diakses, dll.). Kode contoh ini menggunakan titik akhir nilai saja, dengan titik akhir penuh yang dikomentari:

# Hanya nilai (bentuk yang sama dilihat RCC dan permainan Anda)
r = requests.get(BASE, headers=headers)
r.raise_for_status()
config = r.json()
boss_health = config["entries"].get("bossHealth")
print("Kesehatan bos yang diterbitkan:", boss_health)  # Seharusnya 100

# Atau dengan metadata penuh:
# r = requests.get(f"{BASE}/full", headers=headers)

Verifikasi bahwa entries.bossHealth (atau kunci Anda) cocok dengan yang Anda terbitkan.

Lihat riwayat dan kembalikan

Setiap penerbitan membuat revisi, sama seperti sistem kontrol versi. Anda dapat mencantumkan revisi untuk melihat siapa yang mengubah apa dan kapan, kemudian mengembalikan ke revisi sebelumnya jika Anda perlu kembali.

Kode contoh ini memanggil titik akhir revisi dan mencetak hasilnya. Setiap revisi mencakup revisionId, version, time, publishedBy, message, dan changes (kunci, nilai "sebelum", dan nilai "setelah").

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"])

Untuk kembali, panggil titik akhir pemulihan dengan revisionId yang ingin Anda kembalikan. Itu akan menghapus draf saat ini dan menyiapkan komit pemulihan; ini tidak menerbitkan. Untuk menerbitkan, Anda harus memanggil publish dengan draftHash yang dikembalikan, sama seperti menerbitkan perubahan baru.

REVISION_ID = "1234567890"  # Dari daftar di atas
r = requests.post(f"{BASE}/revisions/{REVISION_ID}/restore", headers=headers)
r.raise_for_status()
restore_draft = r.json()
restore_hash = restore_draft["draftHash"]

# Terbitkan pemulihan
publish_payload = {
    "draftHash": restore_hash,
    "message": "Kembali ke konfigurasi sebelumnya",
    "deploymentStrategy": "Immediate"
}
r = requests.post(f"{BASE}/publish", headers=headers, json=publish_payload)
r.raise_for_status()
print("Rollback diterbitkan. configVersion:", r.json()["configVersion"])

Batasan

Permintaan yang melebihi batasan ini akan gagal. Untuk batasan nilai spesifik jenis (misalnya string vs JSON) di pengalaman Anda, lihat Batas di panduan konfigurasi pengalaman.

Untuk rincian lengkap tentang semua titik akhir dalam panduan ini, lihat referensi API Cloud.