Erfahrungskonfigurationen

Die Konfigurations-API ermöglicht es Ihnen, Erfahrungskonfigurationen programmgesteuert zu verwalten, anstatt den Creator Hub oder das Studio zu verwenden. Dieser Leitfaden behandelt einen typischen Ablauf:

• Erstellen oder Aktualisieren einer Entwurfskonfiguration.
• Veröffentlichen.
• Abrufen der neuesten Konfigurationswerte.
• Zurücksetzen auf einen vorherigen Wert über die Versionshistorie.

Die Werte, die Sie veröffentlichen, sind sofort in Ihrer Erfahrung verfügbar. In Serverskripten verwenden Sie ConfigService, um Konfigurationen zu lesen und auf Echtzeit-Updates zu reagieren. ConfigService:GetConfigAsync() und ConfigSnapshot:GetValue() ermöglichen es Ihnen, Werte zu lesen, und ConfigSnapshot.UpdateAvailable mit ConfigSnapshot:Refresh() oder ConfigSnapshot:GetValueChangedSignal() ermöglicht es Ihnen, auf Wertänderungen zu reagieren. Für Luau-Codebeispiele und weitere Details siehe Fügen Sie Konfigurationen zu Ihrem Code hinzu und Snapshots aktualisieren im Leitfaden zu Erfahrungskonfigurationen.

Bevor Sie beginnen, generieren Sie einen API-Schlüssel oder konfigurieren Sie eine OAuth 2.0-App. Lesevorgänge erfordern den Umfang universe:read. Schreibvorgänge (Entwürfe, Veröffentlichung, Wiederherstellung) benötigen universe:write.

Alle Endpunkte verwenden Ihre Universums-ID, die Sie im Creator Dashboard finden können. Klicken Sie auf das Überlaufmenü der Erlebnis-Kachel und wählen Sie Universums-ID kopieren.

Für das vollständige Endpunktverzeichnis, Anfrage- und Antwortschemata sowie Fehlercodes siehe die Cloud API-Dokumentation.

Repositories

Anfragen an die Konfigurationsendpunkte verwenden ein Repository im Pfad und ein entries-Objekt im Anforderungstext. Zum Beispiel fügt diese Anfrage eine Entwurfskonfiguration hinzu:

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

• Repositories unterscheiden sich je nach Produkt und trennen Konfigurationen nach System.
• Entries sind die Schlüssel-Wert-Paare der Konfiguration. Sie senden und empfangen ein einzelnes flaches Objekt mit Schlüsseln und Werten.

Dieser Leitfaden behandelt Konfigurationen in der Erfahrung, daher verwenden alle Anfragen InExperienceConfig für das Repository. Die Repositories werden schließlich erweitert, um zusätzliche Produkte und Anwendungsfälle abzudecken.

Konfigurationen erstellen oder aktualisieren

Vor der Veröffentlichung werden Konfigurationsänderungen als Entwürfe bearbeitet. Sie können entweder die gesamte Konfiguration in einer Operation festlegen oder teilweise Updates durchführen, bis Sie zufrieden sind:

• Von Grund auf neu beginnen oder alles ersetzen — Verwenden Sie den Überschreib-Endpunkt, sodass die Nutzlast den vollständigen gewünschten Zustand darstellt. Jedes Schlüssel, das Sie weglassen, wird als entfernt betrachtet.
• Nur einige Schlüssel ändern — Verwenden Sie den Endpunkt für partielle Updates, sodass nur die Schlüssel, die Sie senden, aktualisiert werden; alles andere bleibt unverändert.

Dieses Beispielsetzt bossHealth auf 100 und verwendet den Überschreib-Endpunkt:

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: senden Sie previousDraftHash, wenn Sie einen vorhandenen Entwurf haben und optimistische Nebenläufigkeit wünschen
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"]  # Behalten Sie dies für die Veröffentlichung
print("Entwurf eingerichtet. draftHash:", draft_hash)

Die Antwort enthält den Wert draftHash. Sie benötigen diesen Hash, um zu veröffentlichen. Wenn Sie bevorzugen, nur einige Schlüssel in Ihrem Entwurf zu ändern, verwenden Sie die PATCH-Methode für den /draft-Endpunkt und senden Sie nur die Einträge (Schlüssel), die Sie ändern möchten.

Über Entwurfshaushalte

Ein Entwurfshaushalt ist ein undurchsichtiger Identifikator für den aktuellen Zustand Ihres Entwurfs. Die API gibt ihn nach jedem Lese- oder Schreibvorgang für einen Entwurf zurück (erstellen, aktualisieren, überschreiben, zurücksetzen, wiederherstellen).

Beim Aktualisieren oder Veröffentlichen von Entwürfen können Sie previousDraftHash im Anforderungstext senden. Wenn der Hash nicht mit dem aktuellen Entwurf des Servers übereinstimmt (z. B. wenn jemand anderes inzwischen veröffentlicht oder bearbeitet hat), schlägt die Anfrage fehl. Sie können dann den aktualisierten Entwurf erneut lesen, den neuen Hash abrufen und es erneut versuchen oder Änderungen zusammenführen.

Speichern Sie immer den draftHash aus der letzten Entwurfantwort, bevor Sie die Veröffentlichung aufrufen oder bevor Sie eine weitere Entwurfänderung vornehmen, wenn Sie previousDraftHash verwenden.

Veröffentlichen Sie Ihre Änderungen

Wenn Sie mit dem Entwurf zufrieden sind, veröffentlichen Sie ihn, damit die neuen Werte aktiv werden. Übergeben Sie draftHash aus der Entwurfantwort, message für Versionshistorie und deploymentStrategy (entweder GradualRollout für ein 15-minütiges Rollout oder Immediate). Der folgende Beispielcode veröffentlicht die Konfiguration sofort:

publish_payload = {
    "draftHash": draft_hash,
    "message": "Boss Gesundheit auf 100 setzen",
    "deploymentStrategy": "Immediate"
}
r = requests.post(f"{BASE}/publish", headers=headers, json=publish_payload)
r.raise_for_status()
result = r.json()
print("Veröffentlicht. configVersion:", result["configVersion"])

Nach einer erfolgreichen Veröffentlichung wird der Entwurf gelöscht und Ihre Erfahrung erhält die neue Konfiguration gemäß der Bereitstellungsstrategie. Die Antwort enthält die neue Konfigurationsversion:

{
  "configVersion": 6
}

Holen Sie sich Ihre veröffentlichte Konfiguration

Um zu bestätigen, dass die Änderung durchgegangen ist, rufen Sie die neueste veröffentlichte Konfiguration ab. Verwenden Sie den Wert-Only-Endpunkt, wenn Sie nur Schlüssel und Werte benötigen; verwenden Sie den vollständigen Endpunkt, wenn Sie auch Metadaten (Beschreibungen, letzte Zugriffszeit usw.) benötigen. Dieser Beispielcode verwendet den Wert-Only-Endpunkt, wobei der vollständige Endpunkt auskommentiert ist:

# Nur Werte (gleiche Form RCC und Ihr Spiel sehen)
r = requests.get(BASE, headers=headers)
r.raise_for_status()
config = r.json()
boss_health = config["entries"].get("bossHealth")
print("Veröffentlichte bossHealth:", boss_health)  # Sollte 100 sein

# Oder mit vollständigen Metadaten:
# r = requests.get(f"{BASE}/full", headers=headers)

Verifizieren Sie, dass entries.bossHealth (oder Ihr Schlüssel) dem entspricht, was Sie veröffentlicht haben.

Verlauf anzeigen und zurücksetzen

Jede Veröffentlichung erstellt eine Revision, genau wie ein Versionskontrollsystem. Sie können Revisionen auflisten, um zu sehen, wer was und wann geändert hat, und dann auf eine frühere Revision zurücksetzen, wenn Sie zurücksetzen müssen.

Dieser Beispielcode ruft den Revisionsendpunkt auf und druckt die Ergebnisse. Jede Revision enthält revisionId, version, time, publishedBy, message und changes (den Schlüssel, den "Vorher"-Wert und den "Nachher"-Wert).

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

Um zurückzusetzen, rufen Sie den Wiederherstellungs-Endpunkt mit der revisionId auf, zu der Sie zurückkehren möchten. Dadurch wird der aktuelle Entwurf gelöscht und ein Revert-Commit festgelegt; es wird nicht veröffentlicht. Zum Veröffentlichen müssen Sie publish mit dem zurückgegebenen draftHash aufrufen, genau wie bei der Veröffentlichung einer neuen Änderung.

REVISION_ID = "1234567890"  # Aus der obigen Liste
r = requests.post(f"{BASE}/revisions/{REVISION_ID}/restore", headers=headers)
r.raise_for_status()
restore_draft = r.json()
restore_hash = restore_draft["draftHash"]

# Veröffentlichen Sie das Zurücksetzen
publish_payload = {
    "draftHash": restore_hash,
    "message": "Rücksetzung auf vorherige Konfiguration",
    "deploymentStrategy": "Immediate"
}
r = requests.post(f"{BASE}/publish", headers=headers, json=publish_payload)
r.raise_for_status()
print("Rücksetzung veröffentlicht. configVersion:", r.json()["configVersion"])

Einschränkungen

Anfragen, die diese Limits überschreiten, schlagen fehl. Für typenspezifische Wertlimits (z. B. String vs JSON) in Ihrer Erfahrung siehe Limits im Leitfaden zu Erfahrungskonfigurationen.

Für vollständige Details zu allen Endpunkten in diesem Leitfaden siehe die Cloud API-Dokumentation.