Konfiguracje doświadczeń

API konfiguracji pozwala zarządzać konfiguracjami doświadczeń programowo, zamiast korzystać z Creator Hub lub Studio. Ten przewodnik omawia typowy przepływ:

• Utwórz lub zaktualizuj roboczą konfigurację.
• Publikuj ją.
• Odczytaj najnowsze wartości konfiguracji.
• Przywróć poprzednią wartość za pomocą historii wersji.

Wartości, które publikujesz, są dostępne w Twoim doświadczeniu od razu. W skryptach serwera użyj ConfigService, aby odczytać konfiguracje i reagować na aktualizacje w czasie rzeczywistym. ConfigService:GetConfigAsync() i ConfigSnapshot:GetValue() pozwalają odczytać wartości, a ConfigSnapshot.UpdateAvailable z ConfigSnapshot:Refresh() lub ConfigSnapshot:GetValueChangedSignal() pozwalają reagować, gdy wartości się zmieniają. Aby uzyskać przykłady kodu w Luau i szczegóły, zobacz Dodaj konfiguracje do swojego kodu oraz Odśwież migaweki w przewodniku po konfiguracjach doświadczeń.

Zanim zaczniesz, wygeneruj klucz API lub skonfiguruj aplikację OAuth 2.0. Operacje odczytu wymagają zakresu universe:read. Operacje zapisu (robocze, publikacja, przywrócenie) wymagają universe:write.

Wszystkie punkty końcowe używają identyfikatora Twojego uniwersum, który możesz znaleźć na Pulpicie nawigacyjnym Creatora. Kliknij w menu rozwijane kafla doświadczenia i wybierz Kopiuj identyfikator uniwersum.

Aby uzyskać pełną dokumentację punktów końcowych, schematy żądań i odpowiedzi oraz kody błędów, zobacz Dokumentację API w chmurze.

Repozytoria

Żądania do punktów końcowych konfiguracji używają repozytorium w ścieżce i obiektu entries w ciele żądania. Na przykład, to żądanie dodaje roboczą konfigurację:

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

• Repozytoria różnią się w zależności od produktu i oddzielają konfiguracje według systemu.
• Entries to pary klucz-wartość konfiguracji. Wysyłasz i odbierasz pojedynczy płaski obiekt kluczy i wartości.

Ten przewodnik obejmuje konfiguracje w doświadczeniu, więc wszystkie żądania używają InExperienceConfig jako repozytorium. Repozytoria w końcu rozszerzą się, aby obejmować inne produkty i przypadki użycia.

Tworzenie lub aktualizacja konfiguracji

Przed uruchomieniem, zmiany konfiguracji są przygotowywane jako robocze. Możesz ustawić całą konfigurację w jednej operacji lub zastosować częściowe aktualizacje, aż będziesz zadowolony z jej wyglądu:

• Zaczynając od zera lub zastępując wszystko — Użyj punktu końcowego nadpisania, aby ładunek był pełnym pożądanym stanem. Każdy klucz, który pominiesz, jest traktowany jako usunięty.
• Zmieniając tylko niektóre klucze — Użyj punktu końcowego aktualizacji częściowych, aby tylko klucze, które wysyłasz, zostały zaktualizowane; wszystko inne pozostaje bez zmian.

Ten przykładowy kod ustawia bossHealth na 100 i używa punktu końcowego nadpisania:

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

# Opcjonalnie: wyślij previousDraftHash, jeśli masz istniejącą roboczą wersję i chcesz optymistyczną współbieżność
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"]  # Zachowaj to do publikacji
print("Robocza wersja przygotowana. draftHash:", draft_hash)

Odpowiedź zawiera wartość draftHash. Potrzebujesz tego hasha, aby opublikować. Jeśli wolisz tylko dopracować kilka kluczy w swojej roboczej wersji, użyj metody PATCH na punkcie końcowym /draft i wyślij tylko wpisy (klucze), które chcesz zmienić.

O haszach roboczych

Hasz roboczy to nieprzezroczysty identyfikator reprezentujący aktualny stan Twojej roboczej wersji. API zwraca go po każdej operacji odczytu lub zapisu do roboczej wersji (tworzenie, aktualizacja, nadpisywanie, resetowanie, przywracanie).

Podczas aktualizacji lub publikacji roboczych wersji, możesz wysłać previousDraftHash w ciele żądania. Jeśli hash nie pasuje do aktualnej roboczej wersji na serwerze (np. ktoś inny opublikował lub edytował w międzyczasie), żądanie kończy się niepowodzeniem. Możesz wtedy ponownie odczytać zaktualizowaną roboczą wersję, uzyskać nowy hash i spróbować ponownie lub scalić zmiany.

Zawsze zapisz draftHash z ostatniej odpowiedzi roboczej przed wywołaniem publikacji lub przed dokonaniem innej zmiany w roboczej wersji, jeśli używasz previousDraftHash.

Publikowanie zmian

Gdy jesteś zadowolony z roboczej wersji, opublikuj ją, aby nowe wartości stały się aktywne. Przekaż draftHash z odpowiedzi roboczej, message do celów historii wersji, oraz deploymentStrategy (czy GradualRollout dla 15-minutowego wdrożenia, czy Immediate). Poniższy przykładowy kod wdraża konfigurację natychmiast:

publish_payload = {
    "draftHash": draft_hash,
    "message": "Ustawienie zdrowia bossa na 100",
    "deploymentStrategy": "Immediate"
}
r = requests.post(f"{BASE}/publish", headers=headers, json=publish_payload)
r.raise_for_status()
result = r.json()
print("Opublikowane. configVersion:", result["configVersion"])

Po pomyślnej publikacji, robocza wersja jest czyszczona, a Twoje doświadczenie otrzymuje nową konfigurację zgodnie z strategią wdrażania. Odpowiedź zawiera nową wersję konfiguracji:

{
  "configVersion": 6
}

Odczyt opublikowanej konfiguracji

Aby potwierdzić, że zmiana została uwzględniona, pobierz najnowszą opublikowaną konfigurację. Użyj punktu końcowego tylko dla wartości, gdy potrzebujesz tylko kluczy i wartości; użyj pełnego punktu końcowego, gdy potrzebujesz również metadanych (opisów, czasu ostatniego dostępu itp.). Ten przykładowy kod używa punktu końcowego tylko dla wartości, z pełnym punktem końcowym zakomentowanym:

# Tylko wartości (ta sama forma, jaką widzi RCC i Twoja gra)
r = requests.get(BASE, headers=headers)
r.raise_for_status()
config = r.json()
boss_health = config["entries"].get("bossHealth")
print("Opublikowane bossHealth:", boss_health)  # Powinno być 100

# Lub z pełnymi metadanymi:
# r = requests.get(f"{BASE}/full", headers=headers)

Sprawdź, czy entries.bossHealth (lub Twój klucz) odpowiada temu, co opublikowałeś.

Wyświetlanie historii i przywracanie

Każda publikacja tworzy rewizję, podobnie jak system kontroli wersji. Możesz wyświetlić rewizje, aby zobaczyć, kto, co i kiedy zmienił, a następnie przywrócić do wcześniejszej rewizji, jeśli musisz cofnąć zmiany.

Ten przykładowy kod wywołuje punkt końcowy rewizji i drukuje wyniki. Każda rewizja zawiera revisionId, version, time, publishedBy, message i changes (klucz, wartość "przed" i wartość "po").

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

Aby przywrócić, wywołaj punkt końcowy przywracania z revisionId, do którego chcesz wrócić. To czyści bieżącą roboczą wersję i przygotowuje commit przywracający; nie publikuje jednak. Aby opublikować, musisz wywołać publish z zwróconym draftHash, tak jak przy publikacji nowej zmiany.

REVISION_ID = "1234567890"  # Z listy powyżej
r = requests.post(f"{BASE}/revisions/{REVISION_ID}/restore", headers=headers)
r.raise_for_status()
restore_draft = r.json()
restore_hash = restore_draft["draftHash"]

# Publikacja cofnięcia
publish_payload = {
    "draftHash": restore_hash,
    "message": "Cofnięcie do poprzedniej konfiguracji",
    "deploymentStrategy": "Immediate"
}
r = requests.post(f"{BASE}/publish", headers=headers, json=publish_payload)
r.raise_for_status()
print("Cofnięcie opublikowane. configVersion:", r.json()["configVersion"])

Ograniczenia

Żądania, które przekraczają te limity, zakończą się niepowodzeniem. Aby uzyskać limity specyficzne dla wartości typów (np. string vs JSON) w Twoim doświadczeniu, zobacz Limity w przewodniku po konfiguracjach doświadczeń.

Aby uzyskać pełne szczegóły dotyczące wszystkich punktów końcowych w tym przewodniku, zobacz Dokumentację API w chmurze.