Deneyim yapılandırmaları

Yapılandırmalar API'si, deneyim yapılandırmalarını programatik olarak yönetmenizi sağlar, böylece Creator Hub veya Studio kullanmanıza gerek kalmaz. Bu kılavuz, tipik bir akışı kapsar:

• Bir taslak yapılandırması oluşturun veya güncelleyin.
• Yayınlayın.
• En son yapılandırma değerlerini alın.
• Sürüm geçmişini kullanarak önceki bir değere geri dönün.

Yayımladığınız değerler, deneyiminizde hemen kullanılabilir hale gelir. Sunucu betiklerinde yapılandırmaları okumak ve gerçek zamanlı güncellemelere tepki vermek için ConfigService kullanın. ConfigService:GetConfigAsync() ve ConfigSnapshot:GetValue() değerleri okumanızı sağlar ve ConfigSnapshot.UpdateAvailable ile ConfigSnapshot:Refresh() veya ConfigSnapshot:GetValueChangedSignal() değerlerin değiştiğinde tepki vermenizi sağlar. Luau kod örnekleri ve daha fazla ayrıntı için, Kodunuza yapılandırmalar ekleyin ve Anlık görüntüleri yenileyin başlıklarını deneyim yapılandırmaları kılavuzunda inceleyin.

Başlamadan önce, bir API anahtarı oluşturun veya bir OAuth 2.0 uygulaması yapılandırın. Okuma işlemleri universe:read kapsamını gerektirir. Yazma işlemleri (taslaklar, yayımlama, geri yükleme) ise universe:write gerektirir.

Tüm uç noktalar, Creator Dashboard üzerinde bulabileceğiniz evren ID'nizi kullanır. Deneyim karosu taşma menüsüne tıklayın ve Evren ID'sini Kopyala seçeneğini tıklayın.

Tam uç nokta referansı, istek ve yanıt şemaları ve hata kodları için, Cloud API referansı başlığına bakın.

Depolar

Yapılandırmalar uç noktalarına yapılan istekler, yol içinde bir depo ve istek gövdesinde bir girdi nesnesi kullanır. Örneğin, bu istek bir taslak yapılandırması ekler:

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

• Depolar, ürünlere göre farklılık gösterir ve yapılandırmaları sistemlere göre ayırır.
• Girdiler, yapılandırma anahtar-değer çiftleridir. Gönderdiğiniz ve aldığınız anahtarlar ve değerlerden oluşan tek bir düz nesne gönderirsiniz.

Bu kılavuz, deneyim içi yapılandırmaları kapsar, bu nedenle tüm istekler için InExperienceConfig deposu kullanılır. Depolar, zamanla ek ürünleri ve kullanım senaryolarını kapsayacak şekilde genişleyecektir.

Yapılandırmalar oluşturma veya güncelleme

Canlıya geçmeden önce, yapılandırma değişiklikleri taslak olarak sahnelenir. İsterseniz tüm yapılandırmayı bir işlemde ayarlayabilir veya memnun kalıncaya kadar kısmi güncellemeler uygulayabilirsiniz:

• Başlangıçtan başlayarak veya her şeyi değiştirmek — Yükleme uç noktasını kullanın, böylece yük yüklemesi istenen durumun tamamıdır. Atladığınız herhangi bir anahtar kaldırılmış olarak kabul edilir.
• Yalnızca bazı anahtarları değiştirmek — Kısmi güncelleme uç noktasını kullanın, böylece yalnızca gönderdiğiniz anahtarlar güncellenir; diğer her şey olduğu gibi kalır.

Bu örnek kod, bossHealth değerini 100 olarak ayarlar ve yükleme uç noktasını kullanır:

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

# İsteğe bağlı: mevcut bir taslağınız varsa ve iyimser eşzamanlılık istiyorsanız previousDraftHash gönderin
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"]  # Yayımlamak için bunu saklayın
print("Taslak sahnelendi. draftHash:", draft_hash)

Yanıt, draftHash değerini içerir. Bu hash, yayımlamak için gereklidir. Taslağınızdaki yalnızca birkaç anahtarı ayarlamak isterseniz, /draft uç noktasında PATCH yöntemini kullanın ve yalnızca değiştirmek istediğiniz girişleri (anahtarları) gönderin.

Taslak hash'leri hakkında

Taslak hash şu anki taslağınızın opak bir tanımlayıcısıdır. API, herhangi bir okuma veya yazma işlemi gerçekleştikten sonra (oluşturma, güncelleme, üzerine yazma, sıfırlama, geri yükleme) bunu döndürür.

Tasıtları güncellerken veya yayımlarken, istek gövdesinde previousDraftHash gönderebilirsiniz. Eğer hash, sunucunun mevcut taslağıyla eşleşmezse (örneğin, başka biri yayımladı veya düzenlediyse), istek başarısız olur. Daha sonra güncellenmiş taslağı yeniden okuyabilir, yeni hash'i alabilir ve değişiklikleri yeniden deneyebilir veya birleştirebilirsiniz.

Her zaman son taslak yanıtından draftHash'i saklayın, yayımlama çağrısı yapmadan önce veya previousDraftHash kullanıyorsanız başka bir taslak değişikliği yapmadan önce bunu saklayın.

Değişikliklerinizi yayınlayın

Tasıtınızdan memnun kaldığınızda, yeni değerlerin canlı hale gelmesi için yayımlayın. Taslak yanıtından draftHash'i, sürüm geçmişi amacıyla message'i ve deploymentStrategy'yi (15 dakikalık bir dağıtım için GradualRollout veya Immediate) geçin. Aşağıdaki örnek kod, yapılandırmayı hemen dağıtır:

publish_payload = {
    "draftHash": draft_hash,
    "message": "Boss sağlığını 100 olarak ayarla",
    "deploymentStrategy": "Immediate"
}
r = requests.post(f"{BASE}/publish", headers=headers, json=publish_payload)
r.raise_for_status()
result = r.json()
print("Yayımlandı. configVersion:", result["configVersion"])

Başarılı bir şekilde yayımlandıktan sonra, taslak temizlenir ve deneyiminiz dağıtım stratejisine göre yeni yapılandırmayı alır. Yanıt, yeni yapılandırma sürümünü içerir:

{
  "configVersion": 6
}

Yayınladığınız yapılandırmayı alın

Değişikliğin geçtiğini doğrulamak için, en son yayımlanan yapılandırmayı alın. Anahtarlar ve değerler gerektiyse değerler yalnızca uç noktasını kullanın; hem anahtarlar hem de meta veriler (açıklamalar, son erişim zamanı, vb.) gerektiğinde tam uç noktasını kullanın. Bu örnek kod, değerler yalnızca uç noktasını kullanırken, tam uç noktayı yorum satırı haline getirmiştir:

# Sadece değerler (Aynı şekil RCC ve oyununuzda gördüğünüz)
r = requests.get(BASE, headers=headers)
r.raise_for_status()
config = r.json()
boss_health = config["entries"].get("bossHealth")
print("Yayımlanan bossHealth:", boss_health)  # 100 olmalıdır

# Ya da tam meta verilerle:
# r = requests.get(f"{BASE}/full", headers=headers)

entries.bossHealth (veya anahtarınız) yayımladığınız değerle eşleştiğinden emin olun.

Geçmişi görüntüle ve geri alın

Her yayım, bir revizyon oluşturur; versiyon kontrol sistemi gibi. Değişiklik yapan kişileri görmek ve ne zaman yapıldığını kontrol etmek için revizyonları listeleyebilir ve gerektiğinde önceki bir revizyona geri dönebilirsiniz.

Bu örnek kod, revizyonlar uç noktasını çağırır ve sonuçları yazdırır. Her revizyon revisionId, version, time, publishedBy, message ve changes (anahtar, "önceki" değer ve "sonraki" değer) içerir.

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

Geri dönmek için istekte bulunmak istediğiniz revisionId ile geri yükleme uç noktasını çağırın. Bu, mevcut taslağı temizler ve bir geri dönüş taahhüdü sahneler; yayımlamaz. Yayımlamak için, önceki değişiklikleri yayımlamak için döndürülen draftHash ile publish çağrısını yapmalısınız.

REVISION_ID = "1234567890"  # Yukarıdan listele
r = requests.post(f"{BASE}/revisions/{REVISION_ID}/restore", headers=headers)
r.raise_for_status()
restore_draft = r.json()
restore_hash = restore_draft["draftHash"]

# Geri dönmeyi yayımlayın
publish_payload = {
    "draftHash": restore_hash,
    "message": "Önceki yapılandırmaya geri dön",
    "deploymentStrategy": "Immediate"
}
r = requests.post(f"{BASE}/publish", headers=headers, json=publish_payload)
r.raise_for_status()
print("Geri dönme yayımlandı. configVersion:", r.json()["configVersion"])

Sınırlamalar

Bu limitleri aşan istekler başarısız olacaktır. Deneyiminizdeki tür özel değer limitleri (örneğin, dize veya JSON) için Sınırlamalar başlığına bakın.

Bu kılavuzda yer alan tüm uç noktalar hakkında tam ayrıntılar için Cloud API referansı bölümüne bakın.