Configurations d'expérience

L'API des configurations vous permet de gérer les configurations d'expérience par programme plutôt que d'utiliser Creator Hub ou Studio. Ce guide couvre un flux typique :

• Créer ou mettre à jour une configuration de brouillon.
• La publier.
• Obtenir les dernières valeurs de configuration.
• Revenir à une valeur antérieure en utilisant l'historique des versions.

Les valeurs que vous publiez sont immédiatement disponibles dans votre expérience. Dans les scripts serveur, utilisez ConfigService pour lire les configurations et réagir aux mises à jour en temps réel. ConfigService:GetConfigAsync() et ConfigSnapshot:GetValue() vous permettent de lire les valeurs, et ConfigSnapshot.UpdateAvailable avec ConfigSnapshot:Refresh() ou ConfigSnapshot:GetValueChangedSignal() vous permet de répondre aux changements de valeurs. Pour des exemples de code Luau et plus de détails, voir Ajouter des configurations à votre code et Rafraîchir les instantanés dans le guide des configurations d'expérience.

Avant de commencer, générez une clé API ou configurez une application OAuth 2.0. Les opérations de lecture nécessitent le champ universe:read. Les opérations d'écriture (brouillons, publication, restauration) nécessitent universe:write.

Tous les points de terminaison utilisent l'ID de votre univers, que vous pouvez trouver sur le Tableau de bord Creator. Cliquez sur le menu déroulant de la tuile de l'expérience et Copier l'ID de l'univers.

Pour la référence complète des points de terminaison, des schémas de requête et de réponse, et des codes d'erreur, voir la référence de l'API Cloud.

Dépôts

Les requêtes aux points de terminaison des configurations utilisent un dépôt dans le chemin et un objet entries dans le corps de la requête. Par exemple, cette requête ajoute une configuration de brouillon :

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

• Dépôts diffèrent selon le produit et séparent les configurations par système.
• Entries sont les paires clé-valeur de configuration. Vous envoyez et recevez un seul objet plat de clés et de valeurs.

Ce guide couvre les configurations au sein de l'expérience, donc toutes les requêtes utilisent InExperienceConfig pour le dépôt. Les dépôts finiront par s'étendre pour couvrir des produits et des cas d'utilisation supplémentaires.

Créer ou mettre à jour des configurations

Avant de passer en production, les changements de configuration sont mis en attente sous forme de brouillons. Vous pouvez soit définir l'ensemble de la configuration en une seule opération, soit appliquer des mises à jour partielles jusqu'à ce que vous soyez satisfait :

• Partir de zéro ou remplacer tout — Utilisez le point de terminaison de remplacement afin que la charge utile soit l'état complet souhaité. Toute clé que vous omettez est considérée comme supprimée.
• Changer seulement quelques clés — Utilisez le point de terminaison de mise à jour partielle afin que seules les clés que vous envoyez soient mises à jour ; tout le reste reste inchangé.

Ce code d'exemple définit bossHealth à 100 et utilise le point de terminaison de remplacement :

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

# Optionnel : envoyer previousDraftHash si vous avez un brouillon existant et souhaitez une concurrence optimiste
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"]  # Gardez ceci pour la publication
print("Brouillon mis en attente. draftHash:", draft_hash)

La réponse comprend la valeur draftHash. Vous avez besoin de ce hash pour publier. Si vous préférez ne modifier que quelques clés dans votre brouillon, utilisez la méthode PATCH sur le point de terminaison /draft et envoyez seulement les entrées (clés) que vous souhaitez changer.

À propos des hash de brouillon

Un hash de brouillon est un identifiant opaque pour l'état actuel de votre brouillon. L'API le renvoie après toute opération de lecture ou d'écriture sur un brouillon (création, mise à jour, remplacement, réinitialisation, restauration).

Lorsque vous mettez à jour ou publiez des brouillons, vous pouvez envoyer previousDraftHash dans le corps de la requête. Si le hash ne correspond pas au brouillon actuel du serveur (par exemple, quelqu'un d'autre a publié ou édité entre-temps), la requête échoue. Vous pouvez alors relire le brouillon mis à jour, obtenir le nouveau hash et réessayer ou fusionner les changements.

N'oubliez jamais de sauvegarder le draftHash de la dernière réponse de brouillon avant d'appeler la publication ou avant de faire un autre changement de brouillon si vous utilisez previousDraftHash.

Publiez vos changements

Lorsque vous êtes satisfait du brouillon, publiez-le pour que les nouvelles valeurs soient mises en ligne. Passez draftHash de la réponse au brouillon, message à des fins d'historique de version, et deploymentStrategy (soit GradualRollout pour un déploiement de 15 minutes ou Immediate). Le code d'exemple suivant déploie la configuration immédiatement :

publish_payload = {
    "draftHash": draft_hash,
    "message": "Fixer la santé du boss à 100",
    "deploymentStrategy": "Immediate"
}
r = requests.post(f"{BASE}/publish", headers=headers, json=publish_payload)
r.raise_for_status()
result = r.json()
print("Publié. configVersion :", result["configVersion"])

Après une publication réussie, le brouillon est effacé, et votre expérience reçoit la nouvelle configuration selon la stratégie de déploiement. La réponse comprend la nouvelle version de la configuration :

{
  "configVersion": 6
}

Obtenez votre configuration publiée

Pour confirmer que le changement a été effectué, récupérez la dernière configuration publiée. Utilisez le point de terminaison des valeurs uniquement lorsque vous avez seulement besoin de clés et de valeurs ; utilisez le point de terminaison complet lorsque vous avez aussi besoin de métadonnées (descriptions, temps d'accès, etc.). Ce code d'exemple utilise le point de terminaison des valeurs uniquement, avec le point de terminaison complet commenté :

# Valeurs uniquement (même structure que RCC et votre jeu voit)
r = requests.get(BASE, headers=headers)
r.raise_for_status()
config = r.json()
boss_health = config["entries"].get("bossHealth")
print("Health du boss publié :", boss_health)  # Devrait être 100

# Ou avec les métadonnées complètes :
# r = requests.get(f"{BASE}/full", headers=headers)

Vérifiez que entries.bossHealth (ou votre clé) correspond à ce que vous avez publié.

Afficher l'historique et revenir en arrière

Chaque publication crée une révision, tout comme un système de contrôle de version. Vous pouvez lister les révisions pour voir qui a changé quoi et quand, puis restaurer une révision antérieure si vous devez revenir en arrière.

Ce code d'exemple appelle le point de terminaison des révisions et imprime les résultats. Chaque révision comprend revisionId, version, time, publishedBy, message et changes (la clé, la valeur "avant", et la valeur "aprè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"])

Pour revenir en arrière, appelez le point de terminaison de restauration avec le revisionId auquel vous souhaitez revenir. Cela annule le brouillon actuel et prépare un commit de retour ; cela ne publie pas. Pour publier, vous devez appeler publish avec le draftHash retourné, tout comme lors de la publication d'un nouveau changement.

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

# Publier le retour
publish_payload = {
    "draftHash": restore_hash,
    "message": "Retour à la configuration précédente",
    "deploymentStrategy": "Immediate"
}
r = requests.post(f"{BASE}/publish", headers=headers, json=publish_payload)
r.raise_for_status()
print("Retour publié. configVersion :", r.json()["configVersion"])

Limitations

Les requêtes qui dépassent ces limites échoueront. Pour les limites spécifiques à chaque type de valeur (par exemple, chaîne par rapport à JSON) dans votre expérience, voir Limites dans le guide des configurations d'expérience.

Pour des détails complets sur tous les points de terminaison de ce guide, voir la référence de l'API Cloud.