Instâncias do Engine | Documentação - Central de Criadores Roblox

As APIs Open Cloud do Engine permitem que você gerencie objetos Instance em seus jogos Roblox pela web.

Restrições beta

Essas APIs estão atualmente em beta e possuem as seguintes restrições:

Você pode apenas ler e atualizar objetos Script, LocalScript e ModuleScript.
Você não pode atualizar scripts que estão atualmente abertos no Roblox Studio.
Você não pode atualizar scripts que fazem parte de um pacote.
Você pode usar apenas autenticação de chave de API. Crie uma chave de API com universe-place-instances adicionada como um sistema de API.

Você deve especificar os jogos que deseja que a chave tenha acesso, bem como os escopos de permissão de leitura e gravação desejados.
Você deve ter uma sessão colaborativa ativada para o jogo que deseja acessar.
Os corpos das solicitações, como para Atualizar Instância, estão limitados a 200 KB.

Listar crianças

Liste todas as crianças de uma instância específica especificando um ID de instância e chamando o método Listar Crianças da Instância.

Na primeira vez que você usar esses métodos, especifique root para o ID da instância. Depois de receber a lista das crianças de nível superior e seus IDs, você pode fazer chamadas adicionais para encontrar instâncias mais profundas dentro da hierarquia de instâncias do seu lugar.


import requests

# Gerar em https://create.roblox.com/dashboard/credentials
apiKey = "<API_KEY>"
# Encontrar em https://create.roblox.com/dashboard/creations no menu suspenso de um bloco de jogo
universeId = "<UNIVERSE_ID>"
# Encontrar o ID do Lugar Inicial em https://create.roblox.com/dashboard/creations no menu suspenso de um bloco de jogo
placeId = "<PLACE_ID>"
# O ID padrão para a raiz do modelo de dados de qualquer lugar
instanceId = "root"

# Cabeçalho da solicitação
apiKeyHeaderKey = "x-api-key"
# URL do endpoint para o método Listar Crianças
listChildrenUrl = "https://apis.roblox.com/cloud/v2/universes/%s/places/%s/instances/%s:listChildren"

def ListChildren():
  url = listChildrenUrl % (universeId, placeId, instanceId)
  headerData = {apiKeyHeaderKey: apiKey}
  results = requests.get(url, headers = headerData)
  return results

response = ListChildren()
print("Resultados da Operação:", response.status_code, response.text)

# Analise o caminho do objeto Operação para obter posteriormente o recurso da Instância. Veja a seção Polling for Results para mais informações.
operationPath = response.json()['path']

Em vez de apenas listar as crianças, a resposta inclui um objeto Operação com um endpoint diferente. Poll este endpoint para recuperar assincronamente a lista real de crianças. Um exemplo de código mais completo se parece com isto:


import requests
import time

apiKey = "<API_KEY>"
universeId = "<UNIVERSE_ID>"
placeId = "<PLACE_ID>"
instanceId = "root"

apiKeyHeaderKey = "x-api-key"

listChildrenUrl = "https://apis.roblox.com/cloud/v2/universes/%s/places/%s/instances/%s:listChildren"
getOperationUrl = "https://apis.roblox.com/cloud/v2/%s"

numberOfRetries = 10
retryPollingCadence = 5

doneJSONKey = "done"

def ListChildren():
  url = listChildrenUrl % (universeId, placeId, instanceId)
  headerData = {apiKeyHeaderKey: apiKey}
  results = requests.get(url, headers = headerData)
  return results

def GetOperation(operationPath):
  url = getOperationUrl % (operationPath)
  headerData = {apiKeyHeaderKey: apiKey}
  results = requests.get(url, headers = headerData)
  return results

def PollForResults(operationPath):
  currentRetries = 0
  while (currentRetries < numberOfRetries):
    time.sleep(retryPollingCadence)
    results = GetOperation(operationPath)
    currentRetries += 1

    if (results.status_code != 200 or results.json()[doneJSONKey]):
      return results

response = ListChildren()
print("Resultados da Operação:", response.status_code, response.text)
# Analise o caminho do objeto Operação para usar na pollagem do recurso da instância.
operationPath = response.json()['path']
response = PollForResults(operationPath)
print("Resposta:", response.status_code, response.text)

A resposta final pode se parecer com isto:


{
  "path": "universes/1234567890/places/98765432109/instances/root/operations/a1a2a3a4-a1a2-a1a2-a1a2-a1a2a3a4a5a6",
  "done": true,
  "response": {
    "@type": "type.googleapis.com/roblox.open_cloud.cloud.v2.ListInstanceChildrenResponse",
    "instances": [
      {
        "path": "universes/1234567890/places/98765432109/instances/b1b2b3b4-b1b2-b1b2-b1b2-b1b2b3b4b5b6",
        "hasChildren": true,
        "engineInstance": {
          "Id": "b1b2b3b4-b1b2-b1b2-b1b2-b1b2b3b4b5b6",
          "Parent": "a1a2a3a4-a1a2-a1a2-a1a2-a1a2a3a4a5a6",
          "Name": "Workspace",
          "Details": {}
        }
      },

      ...

    ]
  }
}

Você pode então iterar sobre o JSON para encontrar um ID de instância específico:


instances = response.json()['response']['instances']
replicatedStorageId = ""
for i in instances:
  if i['engineInstance']['Name'] == "ReplicatedStorage":
    replicatedStorageId = i['engineInstance']['Id']

if replicatedStorageId:
  # Agora você tem um ID de instância e pode obtê-lo ou atualizá-lo.
else:
  # O nome não foi encontrado.

Os scripts contêm algumas informações adicionais no objeto Details, como o tipo de script, fonte e se estão habilitados.

Obter uma instância

Este método retorna uma única Instância.


import requests

# Gerar em https://create.roblox.com/dashboard/credentials
apiKey = "<API_KEY>"
# Encontrar em https://create.roblox.com/dashboard/creations no menu suspenso de um bloco de jogo
universeId = "<UNIVERSE_ID>"
# Encontrar o ID do Lugar Inicial em https://create.roblox.com/dashboard/creations no menu suspenso de um bloco de jogo
placeId = "<PLACE_ID>"
# O ID padrão para a raiz do modelo de dados de qualquer lugar
instanceId = "<INSTANCE_ID>"

# Cabeçalho da solicitação
apiKeyHeaderKey = "x-api-key"
# URL do endpoint para o método Obter Instância
getInstanceUrl = "https://apis.roblox.com/cloud/v2/universes/%s/places/%s/instances/%s"

def GetInstance():
  url = getInstanceUrl % (universeId, placeId, instanceId)
  headerData = {apiKeyHeaderKey: apiKey}
  return requests.get(url, headers = headerData)

response = GetInstance()
print("Resposta:", response.status_code, response.text)

# Analise o caminho do objeto Operação da resposta. Consulte a seção Polling for Results para mais informações.
operationPath = response.json()['path']

Assim como o método Listar Crianças da Instância, a resposta inclui um objeto Operação que você poll para recuperar a instância real. Veja Poll for results para mais informações.

Atualizar instâncias

Depois de obter o ID da instância apropriado, você pode atualizá-lo. Poll for results após fazer a solicitação de atualização inicial.


import json
import requests

# Gerar em https://create.roblox.com/dashboard/credentials
apiKey = "<API_KEY>"
# Encontrar em https://create.roblox.com/dashboard/creations no menu suspenso de um bloco de jogo
universeId = "<UNIVERSE_ID>"
# Encontrar o ID do Lugar Inicial em https://create.roblox.com/dashboard/creations no menu suspenso de um bloco de jogo
placeId = "<PLACE_ID>"
instanceId = "<INSTANCE_ID>"
instanceType = ""
propertyName = ""
propertyValue = ""

# Cabeçalho da solicitação
apiKeyHeaderKey = "x-api-key"
contentTypeHeaderKey = "Content-type"
contentTypeHeaderValue = "application/json"
# URL do endpoint para o método Atualizar Instância
updateInstanceUrl = "https://apis.roblox.com/cloud/v2/universes/%s/places/%s/instances/%s"
# Chaves JSON
detailsJSONKey = "Details"
engineInstanceJSONKey = "engineInstance"

def GeneratePostData():
  propertiesDict = {propertyName: propertyValue}
  detailsDict = {instanceType: propertiesDict}
  instanceDict = {detailsJSONKey: detailsDict}
  outerDict = {engineInstanceJSONKey: instanceDict}
  return json.dumps(outerDict)

def UpdateInstance(postData):
    url = updateInstanceUrl % (universeId, placeId, instanceId)
    headerData = {apiKeyHeaderKey: apiKey,
    contentTypeHeaderKey: contentTypeHeaderValue}
    return requests.patch(url, headers = headerData, data = postData)

postData = GeneratePostData()
response = UpdateInstance(postData)
print("Resposta:", response.status_code, response.text)

# Analise o caminho do objeto Operação da resposta. Poll para resultados para realizar
# a atualização.
operationPath = response.json()['path']

Se você receber um TypeError ao tentar atualizar um script, verifique se o script não está aberto no Roblox Studio. Se estiver, feche a aba do Editor de Scripts. Você também pode verificar a saída do Studio para erros adicionais, como Engine_OC_API: Processing Error - Live scripting session is active.

Poll para resultados

Todos os métodos atuais Instância retornam um objeto Operação em vez do recurso que você solicitou. Este objeto permite que você realize assincronamente a operação original. Use o caminho do objeto Operação (incluído na resposta inicial) para pollar quando o recurso estiver pronto.

Você pode usar uma variedade de estratégias de polling, como usar backoff exponencial ou um atraso fixo entre as solicitações. O seguinte exemplo polla a cada cinco segundos, até 10 vezes.


import requests
import time

# Gerar em https://create.roblox.com/dashboard/credentials
apiKey = "<API_KEY>"
# Use o caminho da Operação da sua solicitação inicial
# Tem a forma de "universes/<UNIVERSE_ID>/places/<PLACE_ID>/instances/<INSTANCE_ID>/operations/<OPERATION_ID>"
operationPath = "<OPERATION_PATH>"

# Constantes de polling
numberOfRetries = 10
retryPollingCadence = 5

# Cabeçalho da solicitação
apiKeyHeaderKey = "x-api-key"
# URL do endpoint para o polling da operação de longa duração
getOperationUrl = "https://apis.roblox.com/cloud/v2/%s"
# Chaves JSON
doneJSONKey = "done"

def GetOperation(operationPath):
  url = getOperationUrl % (operationPath)
  headerData = {apiKeyHeaderKey: apiKey}
  results = requests.get(url, headers = headerData)
  return results

def PollForResults(operationPath):
  currentRetries = 0
  while (currentRetries < numberOfRetries):
    time.sleep(retryPollingCadence)
    results = GetOperation(operationPath)
    currentRetries += 1

    if (results.status_code != 200 or results.json()[doneJSONKey]):
      return results

response = PollForResults(operationPath)
print("Resposta:", response.status_code, response.text)

Demonstração da Loja de Poções

A demonstração da Loja de Poções no Google Sheets mostra como atualizar o script de um jogo pela web. A demonstração consiste no seguinte:

Um lugar não bloqueado com uma interface simulada que exibe várias poções e seus preços.
Um arquivo .ods que você importa para o Google Sheets. Esta planilha permite que você especifique e atualize valores para propriedades dentro do jogo.
Código para um Google Apps Script que lê dados da Planilha Google e atualiza o script ReplicatedStorage > ItemList no jogo da Loja de Poções.

Configurar a demonstração

Vá para a Demonstração da Loja de Poções página de Descoberta. Clique no menu suspenso e, em seguida, Editar no Studio. O Studio é aberto com uma cópia do lugar.
Clique em Arquivo → Salvar no Roblox e preencha as informações necessárias para salvar a Demonstração da Loja de Poções como o lugar padrão para o seu jogo. Teste o jogo. Você deve ver a interface da Demonstração da Loja de Poções. Anote o nome, custo e cores das poções. Você as mudará mais tarde usando Open Cloud!

Configurar a planilha

Baixe o arquivo da planilha da Loja de Poções.
Vá para Google Sheets e clique em Planilha em Branco.
Na planilha que aparece, clique em Arquivo > Importar e clique na aba Carregar.
Arraste o arquivo da planilha da Loja de Poções para a janela de upload.
Escolha Substituir planilha e depois Importar dados.
Na aba AppScript da planilha, copie o código na célula A1.
Clique no menu Extensões > Apps Script e cole o código no arquivo Code.gs. Depois salve o projeto.
De volta à planilha, selecione a aba Atualizar Loja de Poções. Clique no botão Atualizar Script, clique no menu suspenso e selecione Atribuir script.
Na janela Atribuir script, digite UpdateScript e clique em OK.

Criar uma chave de API

Vá para a página Chaves da API Open Cloud do Creator Hub e clique em Criar chave de API.
Preencha o formulário com as seguintes informações.
- Nome: PotionShop
- Sistema de API: Adicione o sistema de API universe-place-instances. Adicione seu jogo da Loja de Poções ao sistema. Para Operações de Experiência, adicione acesso de leitura e gravação.
- Endereços IP Aceitos: Adicione 0.0.0.0/0 como um Endereço IP
- Expiração: Sem Expiração
- Clique em Salvar & Gerar Chave e depois Copiar Chave para a Área de Transferência.
Cole a chave da API na célula Chave da API (D2) na aba Intro da sua Planilha Google.

Obter o ID do universo e do lugar

Vá para a página Criações do Creator Hub, passe o mouse sobre o bloco do jogo da Loja de Poções e clique no menu suspenso.
Selecione Copiar ID do Universo e cole-o na célula ID do Universo (E2) na aba Intro da sua Planilha Google.
Selecione Copiar ID do Lugar Inicial e cole-o na célula ID do Lugar (F2) na aba Intro da sua Planilha Google.

Atualizar os valores do script

Na aba Atualizar Loja de Poções da planilha, modifique quaisquer valores que você gostaria e clique no botão Atualizar Script.
Se o Google Sheets solicitar autorização, clique em OK e permita que sua conta execute o script.
No Studio, teste a loja de poções para ver quaisquer alterações refletidas. Na janela Explorer, você também pode abrir o script ReplicatedStorage > ItemList para inspecionar as alterações.