Configuraciones de experiencia

La API de configuraciones te permite administrar configuraciones de experiencia programáticamente en lugar de usar Creator Hub o Studio. Esta guía cubre un flujo típico:

• Crear o actualizar una configuración borrador.
• Publicarla.
• Obtener los valores de configuración más recientes.
• Volver a un valor anterior utilizando el historial de versiones.

Los valores que publicas están disponibles en tu experiencia de inmediato. En scripts de servidor, utiliza ConfigService para leer configuraciones y reaccionar a actualizaciones en tiempo real. ConfigService:GetConfigAsync() y ConfigSnapshot:GetValue() te permiten leer valores, y ConfigSnapshot.UpdateAvailable con ConfigSnapshot:Refresh() o ConfigSnapshot:GetValueChangedSignal() te permiten responder cuando los valores cambian. Para ejemplos de código Luau y más detalles, consulta Agregar configuraciones a tu código y Actualizar instantáneas en la guía de configuraciones de experiencia.

Antes de comenzar, genera una clave API o configura una aplicación OAuth 2.0. Las operaciones de lectura requieren el alcance universe:read. Las operaciones de escritura (borradores, publicar, restaurar) necesitan universe:write.

Todos los puntos finales utilizan tu ID de universo, que puedes encontrar en el Tablero de Creador. Haz clic en el menú de desbordamiento de la ficha de experiencia y Copiar ID de Universo.

Para la referencia completa de puntos finales, esquemas de solicitud y respuesta, y códigos de error, consulta la referencia de la API de Cloud.

Repositorios

Las solicitudes a los puntos finales de configuraciones utilizan un repositorio en la ruta y un objeto de entradas en el cuerpo de la solicitud. Por ejemplo, esta solicitud agrega una configuración borrador:

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

• Repositorios difieren por producto y separan configuraciones por sistema.
• Entradas son los pares clave-valor de las configuraciones. Envías y recibes un único objeto plano de claves y valores.

Esta guía cubre configuraciones dentro de la experiencia, por lo que todas las solicitudes utilizan InExperienceConfig como repositorio. Los repositorios eventualmente se expandirán para cubrir productos y casos de uso adicionales.

Crear o actualizar configuraciones

Antes de salir en vivo, los cambios de configuración se almacenan como borradores. Puedes establecer toda la configuración en una sola operación o aplicar actualizaciones parciales hasta que estés satisfecho con ella:

• Comenzando desde cero o reemplazando todo — Usa el punto final de sobreescritura para que la carga útil sea el estado completo deseado. Cualquier clave que omitas se considera eliminada.
• Cambiando solo algunas claves — Usa el punto final de actualización parcial para que solo se actualicen las claves que envíes; todo lo demás permanece igual.

Este código de muestra establece bossHealth en 100 y utiliza el punto final de sobreescritura:

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

# Opcional: envía previousDraftHash si tienes un borrador existente y deseas concurrencia optimista
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"]  # Manten esto para publicar
print("Borrador preparado. draftHash:", draft_hash)

La respuesta incluye el valor draftHash. Necesitas este hash para publicar. Si prefieres ajustar solo algunas claves en tu borrador, usa el método PATCH en el punto final /draft y envía solo las entradas (claves) que deseas cambiar.

Acerca de los hashes de borrador

Un hash de borrador es un identificador opaco para el estado actual de tu borrador. La API lo devuelve después de cualquier operación de lectura o escritura a un borrador (crear, actualizar, sobreescribir, restablecer, restaurar).

Al actualizar o publicar borradores, puedes enviar previousDraftHash en el cuerpo de la solicitud. Si el hash no coincide con el borrador actual del servidor (por ejemplo, alguien más publicó o editó en el ínterin), la solicitud falla. Luego puedes volver a leer el borrador actualizado, obtener el nuevo hash y reintentar o fusionar cambios.

Siempre guarda el draftHash de la última respuesta de borrador antes de llamar a publicar o antes de hacer otro cambio de borrador si usas previousDraftHash.

Publica tus cambios

Cuando estés satisfecho con el borrador, publícalo para que los nuevos valores entren en acción. Pasa el draftHash de la respuesta de borrador, un message para fines del historial de versiones, y deploymentStrategy (ya sea GradualRollout para un despliegue de 15 minutos o Immediate). El siguiente código de muestra despliega la configuración de inmediato:

publish_payload = {
    "draftHash": draft_hash,
    "message": "Establecer la salud del jefe en 100",
    "deploymentStrategy": "Immediate"
}
r = requests.post(f"{BASE}/publish", headers=headers, json=publish_payload)
r.raise_for_status()
result = r.json()
print("Publicado. configVersion:", result["configVersion"])

Después de una publicación exitosa, el borrador se borra y tu experiencia recibe la nueva configuración de acuerdo con la estrategia de despliegue. La respuesta incluye la nueva versión de configuración:

{
  "configVersion": 6
}

Obtén tu configuración publicada

Para confirmar que el cambio se realizó, obtén la configuración publicada más reciente. Usa el punto final de solo valores cuando solo necesites claves y valores; usa el punto final completo cuando también necesites metadatos (descripciones, hora de último acceso, etc.). Este código de muestra utiliza el punto final de solo valores, con el punto final completo comentado:

# Solo valores (forma misma que RCC y tu juego)
r = requests.get(BASE, headers=headers)
r.raise_for_status()
config = r.json()
boss_health = config["entries"].get("bossHealth")
print("Salud del jefe publicada:", boss_health)  # Debería ser 100

# O con metadatos completos:
# r = requests.get(f"{BASE}/full", headers=headers)

Verifica que entries.bossHealth (o tu clave) coincida con lo que publicaste.

Ver historial y volver atrás

Cada publicación crea una revisión, igual que un sistema de control de versiones. Puedes listar revisiones para ver quién cambió qué y cuándo, y luego restaurar a una revisión anterior si necesitas volver atrás.

Este código de muestra llama al punto final de revisiones e imprime los resultados. Cada revisión incluye revisionId, version, time, publishedBy, message y changes (la clave, el valor "antes" y el valor "después").

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

Para volver atrás, llama al punto final de restauración con el revisionId al que deseas revertir. Eso borra el borrador actual y programa un commit de reversión; no publica. Para publicar, debes llamar a publish con el draftHash devuelto, igual que al publicar un nuevo cambio.

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

# Publica la reversión
publish_payload = {
    "draftHash": restore_hash,
    "message": "Revertir a configuración anterior",
    "deploymentStrategy": "Immediate"
}
r = requests.post(f"{BASE}/publish", headers=headers, json=publish_payload)
r.raise_for_status()
print("Reversión publicada. configVersion:", r.json()["configVersion"])

Limitaciones

Las solicitudes que excedan estos límites fallarán. Para límites específicos de tipo de valor (por ejemplo, cadena vs JSON) en tu experiencia, consulta Límites en la guía de configuraciones de experiencia.

Para obtener todos los detalles sobre todos los puntos finales en esta guía, consulta la referencia de la API de Cloud.