Configurazioni dell'esperienza

L'API delle configurazioni ti consente di gestire le configurazioni dell'esperienza in modo programmatico anziché utilizzare Creator Hub o Studio. Questa guida copre un flusso tipico:

• Crea o aggiorna una configurazione bozza.
• Pubblicala.
• Ottieni i valori di configurazione più recenti.
• Ripristina un valore precedente utilizzando la cronologia delle versioni.

I valori che pubblichi sono disponibili nella tua esperienza immediatamente. Negli script del server, utilizza ConfigService per leggere le configurazioni e reagire agli aggiornamenti in tempo reale. ConfigService:GetConfigAsync() e ConfigSnapshot:GetValue() ti consentono di leggere i valori, e ConfigSnapshot.UpdateAvailable con ConfigSnapshot:Refresh() o ConfigSnapshot:GetValueChangedSignal() ti consente di rispondere quando i valori cambiano. Per esempi di codice Luau e ulteriori dettagli, consulta Aggiungi configurazioni al tuo codice e Aggiorna snapshot nella guida alle configurazioni dell'esperienza.

Prima di iniziare, genera una chiave API o configura un'app OAuth 2.0. Le operazioni di lettura richiedono lo scope universe:read. Le operazioni di scrittura (bozze, pubblicazione, ripristino) richiedono universe:write.

Tutti gli endpoint utilizzano il tuo ID universo, che puoi trovare nel Creator Dashboard. Fai clic sul menu a discesa del riquadro dell'esperienza e Copia ID Universo.

Per il riferimento completo agli endpoint, schemi di richiesta e risposta e codici di errore, consulta il riferimento API Cloud.

Repositories

Le richieste agli endpoint delle configurazioni utilizzano un repository nel percorso e un oggetto entries nel corpo della richiesta. Ad esempio, questa richiesta aggiunge una configurazione bozza:

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

• Repositories differiscono per prodotto e separano le configurazioni per sistema.
• Entries sono le coppie chiave-valore della configurazione. Invia e ricevi un singolo oggetto piatto di chiavi e valori.

Questa guida tratta delle configurazioni in esperienza, quindi tutte le richieste utilizzano InExperienceConfig come repository. I repository si espanderanno in futuro per coprire prodotti e casi d'uso aggiuntivi.

Crea o aggiorna le configurazioni

Prima di andare live, le modifiche alle configurazioni vengono preparate come bozze. Puoi impostare l'intera configurazione in un'operazione o applicare aggiornamenti parziali fino a quando non sei soddisfatto:

• Partendo da zero o sostituendo tutto — Usa l'endpoint di sovrascrittura in modo che il payload sia lo stato desiderato completo. Qualsiasi chiave che ometti è trattata come rimossa.
• Cambiando solo alcune chiavi — Usa l'endpoint di aggiornamento parziale in modo che solo le chiavi che invii siano aggiornate; tutto il resto rimane invariato.

Questo esempio di codice imposta bossHealth a 100 e usa l'endpoint di sovrascrittura:

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

# Facoltativo: invia previousDraftHash se hai una bozza esistente e desideri concorrenza ottimistica
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"]  # Tieni questo per la pubblicazione
print("Bozza preparata. draftHash:", draft_hash)

La risposta include il valore draftHash. Hai bisogno di questo hash per pubblicare. Se preferisci modificare solo alcune chiavi nella tua bozza, utilizza il metodo PATCH sull'endpoint /draft e invia solo le entries (chiavi) che desideri cambiare.

Informazioni sugli hash delle bozze

Un draft hash è un identificatore opaco per lo stato attuale della tua bozza. L'API lo restituisce dopo ogni operazione di lettura o scrittura su una bozza (creazione, aggiornamento, sovrascrittura, ripristino, ripristino).

Quando aggiorni o pubblichi bozze, puoi inviare previousDraftHash nel corpo della richiesta. Se l'hash non corrisponde alla bozza corrente del server (ad esempio, qualcos'altro è stato pubblicato o modificato nel frattempo), la richiesta fallisce. Puoi quindi leggere nuovamente la bozza aggiornata, ottenere il nuovo hash e riprovare o unire le modifiche.

Salva sempre il draftHash dall'ultima risposta di bozza prima di chiamare la pubblicazione o prima di apportare un'altra modifica alla bozza se usi previousDraftHash.

Pubblica le tue modifiche

Quando sei soddisfatto della bozza, pubblicala affinché i nuovi valori diventino attivi. Passa draftHash dalla risposta della bozza, message per scopi di cronologia delle versioni e deploymentStrategy (o GradualRollout per un rollout di 15 minuti o Immediate). Il seguente esempio di codice distribuisce immediatamente la configurazione:

publish_payload = {
    "draftHash": draft_hash,
    "message": "Imposta la salute del boss a 100",
    "deploymentStrategy": "Immediate"
}
r = requests.post(f"{BASE}/publish", headers=headers, json=publish_payload)
r.raise_for_status()
result = r.json()
print("Pubblicato. configVersion:", result["configVersion"])

Dopo una pubblicazione riuscita, la bozza viene cancellata e la tua esperienza riceve la nuova configurazione secondo la strategia di distribuzione. La risposta include la nuova versione della configurazione:

{
  "configVersion": 6
}

Ottieni la tua configurazione pubblicata

Per confermare che la modifica sia andata a buon fine, ottieni l'ultima configurazione pubblicata. Usa l'endpoint solo valori quando hai solo bisogno di chiavi e valori; usa l'endpoint completo quando hai anche bisogno di metadati (descrizioni, ora dell'ultimo accesso, ecc.). Questo esempio di codice utilizza l'endpoint solo valori, con l'endpoint completo commentato:

# Solo valori (stessa forma che RCC e il tuo gioco vedono)
r = requests.get(BASE, headers=headers)
r.raise_for_status()
config = r.json()
boss_health = config["entries"].get("bossHealth")
print("Salute del boss pubblicata:", boss_health)  # Dovrebbe essere 100

# Oppure con metadati completi:
# r = requests.get(f"{BASE}/full", headers=headers)

Verifica che entries.bossHealth (o la tua chiave) corrisponda a ciò che hai pubblicato.

Visualizza la cronologia e ripristina

Ogni pubblicazione crea una revisione, proprio come un sistema di controllo versioni. Puoi elencare le revisioni per vedere chi ha cambiato cosa e quando, quindi ripristinare una revisione precedente se hai bisogno di tornare indietro.

Questo esempio di codice chiama l'endpoint delle revisioni e stampa i risultati. Ogni revisione include revisionId, version, time, publishedBy, message e changes (la chiave, il valore "prima" e il valore "dopo").

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

Per ripristinare, chiama l'endpoint di ripristino con il revisionId che desideri annullare. Questo cancella la bozza corrente e prepara un commit di annullamento; non pubblica non. Per pubblicare, devi chiamare publish con il draftHash restituito, proprio come pubblicare una nuova modifica.

REVISION_ID = "1234567890"  # Dalla lista sopra
r = requests.post(f"{BASE}/revisions/{REVISION_ID}/restore", headers=headers)
r.raise_for_status()
restore_draft = r.json()
restore_hash = restore_draft["draftHash"]

# Pubblica il ripristino
publish_payload = {
    "draftHash": restore_hash,
    "message": "Ripristino alla configurazione precedente",
    "deploymentStrategy": "Immediate"
}
r = requests.post(f"{BASE}/publish", headers=headers, json=publish_payload)
r.raise_for_status()
print("Ripristino pubblicato. configVersion:", r.json()["configVersion"])

Limitazioni

Le richieste che superano questi limiti falliranno. Per limiti specifici dei valori per tipo (ad es. stringa vs JSON) nella tua esperienza, consulta Limiti nella guida alle configurazioni dell'esperienza.

Per ulteriori dettagli su tutti gli endpoint in questa guida, consulta il riferimento API Cloud.