Configurações de experiência

A API de configurações permite que você gerencie configurações de experiência programaticamente, em vez de usar o Creator Hub ou o Studio. Este guia abrange um fluxo típico:

• Criar ou atualizar uma configuração de rascunho.
• Publicá-la.
• Obter os valores mais recentes da configuração.
• Reverter para um valor anterior usando o histórico de versões.

Os valores que você publica estão disponíveis em sua experiência imediatamente. Em scripts de servidor, use ConfigService para ler configurações e reagir a atualizações em tempo real. ConfigService:GetConfigAsync() e ConfigSnapshot:GetValue() permitem que você leia valores, e ConfigSnapshot.UpdateAvailable com ConfigSnapshot:Refresh() ou ConfigSnapshot:GetValueChangedSignal() permitem que você responda quando os valores mudam. Para exemplos de código em Luau e mais detalhes, veja Adicionar configurações ao seu código e Atualizar instantâneas no guia de configurações de experiência.

Antes de começar, gerar uma chave de API ou configurar um aplicativo OAuth 2.0. As operações de leitura requerem o escopo universe:read. As operações de gravação (rascunhos, publicar, restaurar) precisam de universe:write.

Todos os endpoints usam seu ID de universo, que você pode encontrar no Painel do Criador. Clique no menu de transbordo do tile da experiência e Copiar ID do Universo.

Para a referência completa do endpoint, esquemas de solicitação e resposta, e códigos de erro, consulte a referência da API Cloud.

Repositórios

As solicitações para os endpoints de configurações usam um repositório no caminho e um objeto entries no corpo da solicitação. Por exemplo, esta solicitação adiciona uma configuração de rascunho:

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

• Repositórios diferem por produto e separam configurações por sistema.
• Entries são os pares chave-valor da configuração. Você envia e recebe um único objeto plano de chaves e valores.

Este guia abrange configurações in-experiência, portanto todas as solicitações usam InExperienceConfig para o repositório. Repositórios eventualmente se expandirão para cobrir produtos e casos de uso adicionais.

Criar ou atualizar configurações

Antes de entrar em operação, as alterações de configuração são organizadas como rascunhos. Você pode definir toda a configuração em uma operação ou aplicar atualizações parciais até ficar satisfeito com ela:

• Começando do zero ou substituindo tudo — Use o endpoint de sobrescrever para que a carga seja o estado desejado completo. Qualquer chave que você omitir é tratada como removida.
• Mudando apenas algumas chaves — Use o endpoint de atualização parcial para que apenas as chaves que você enviar sejam atualizadas; tudo o mais permanece como está.

Este código de exemplo define bossHealth como 100 e usa o endpoint de sobrescrever:

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: envie previousDraftHash se você tiver um rascunho existente e quiser concorrência otimista
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"]  # Mantenha isso para publicação
print("Rascunho organizado. draftHash:", draft_hash)

A resposta inclui o valor draftHash. Você precisa desse hash para publicar. Se preferir mudar apenas algumas chaves em seu rascunho, use o método PATCH no endpoint /draft e envie apenas as entradas (chaves) que deseja alterar.

Sobre hashes de rascunho

Um hash de rascunho é um identificador opaco para o estado atual do seu rascunho. A API o retorna após qualquer operação de leitura ou gravação em um rascunho (criar, atualizar, sobrescrever, redefinir, restaurar).

Ao atualizar ou publicar rascunhos, você pode enviar previousDraftHash no corpo da solicitação. Se o hash não corresponder ao rascunho atual do servidor (por exemplo, alguém publicou ou editou nesse intervalo), a solicitação falha. Você pode então ler o rascunho atualizado, obter o novo hash e tentar novamente ou mesclar as alterações.

Sempre salve o draftHash da última resposta de rascunho antes de chamar a publicação ou antes de fazer outra alteração de rascunho se você usar previousDraftHash.

Publique suas alterações

Quando estiver satisfeito com o rascunho, publique-o para que os novos valores entrem em operação. Passe draftHash da resposta do rascunho, message para fins de histórico de versões e deploymentStrategy (seja GradualRollout para uma implementação de 15 minutos ou Immediate). O seguinte código de exemplo publica a configuração imediatamente:

publish_payload = {
    "draftHash": draft_hash,
    "message": "Definir saúde do chefe como 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"])

Após uma publicação bem-sucedida, o rascunho é limpo, e sua experiência recebe a nova configuração de acordo com a estratégia de implementação. A resposta inclui a nova versão da configuração:

{
  "configVersion": 6
}

Obtenha sua configuração publicada

Para confirmar que a mudança foi realizada, busque a configuração publicada mais recente. Use o endpoint somente valores quando precisar apenas de chaves e valores; use o endpoint completo quando também precisar de metadados (descrições, tempo do último acesso, etc.). Este código de exemplo usa o endpoint somente valores, com o endpoint completo comentado:

# Somente valores (mesmo formato que RCC e seu jogo vê)
r = requests.get(BASE, headers=headers)
r.raise_for_status()
config = r.json()
boss_health = config["entries"].get("bossHealth")
print("Saúde do chefe publicada:", boss_health)  # Deve ser 100

# Ou com metadados completos:
# r = requests.get(f"{BASE}/full", headers=headers)

Verifique se entries.bossHealth (ou sua chave) corresponde ao que você publicou.

Ver histórico e reverter

Cada publicação cria uma revisão, assim como um sistema de controle de versão. Você pode listar revisões para ver quem mudou o quê e quando, e então restaurar uma revisão anterior se precisar reverter.

Este código de exemplo chama o endpoint de revisões e imprime os resultados. Cada revisão inclui revisionId, version, time, publishedBy, message e changes (a chave, o valor "antes" e o valor "depois").

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 reverter, chame o endpoint de restauração com o revisionId ao qual você deseja reverter. Isso limpa o rascunho atual e organiza um commit de reversão; ele não publica. Para publicar, você deve chamar publish com o draftHash retornado, assim como ao publicar uma nova alteração.

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

# Publicar a reversão
publish_payload = {
    "draftHash": restore_hash,
    "message": "Reverter para configuração anterior",
    "deploymentStrategy": "Immediate"
}
r = requests.post(f"{BASE}/publish", headers=headers, json=publish_payload)
r.raise_for_status()
print("Reversão publicada. configVersion:", r.json()["configVersion"])

Limitações

Solicitações que excedem esses limites falharão. Para limites de valores específicos de tipo (por exemplo, string vs JSON) em sua experiência, veja Limites no guia de configurações de experiência.

Para detalhes completos sobre todos os endpoints deste guia, veja a referência da API Cloud.