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

As APIs abertas do motor permitem que você gerencie Instance objetos em suas experiências Roblox a partir do web.

Restrições Beta

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

Você só pode ler e atualizar Script, LocalScript e ModuleScript objetos.
Você não pode atualizar scripts que estão abertos no Roblox Studio.
Você não pode atualizar scripts que fazem parte de um pacote .
Você só pode usar autenticação de chave API. Crie um chave API com lugares do universo adicionados como um sistema de API.

Você deve especificar as experiências que você 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 a experiência que você deseja acesso.
Pedidos de corpos, como atualizar instância, são limitados a 200 KB.

Listando Crianças

Liste todos os filhos de uma instância específica ao especificar um ID de instância e ao chamar o método Listar Filhos de Instância.

A primeira vez que você usa esses métodos, especifique root para o ID da instância. Depois de receber a lista de filhos de nível superior e seus IDs, você pode fazer chamadas adicionais para encontrar instâncias mais profundas na hierarquia da instância do seu local.


import requests

# Gerar em https:// criar.roblox.com/ashboard / credenciais
apiKey = "<API_KEY>"
# Encontre em https://create.roblox.com/dashboards/creations no menu de sobreposição de uma experiência
universeId = "<UNIVERSE_ID>"
# Encontre o ID de local de início em https://create.roblox.com/dashboards/creations no menu de sobreposição de uma experiência
placeId = "<PLACE_ID>"
# O ID padrão para a raiz de qualquer localde dados
instanceId = "root"

# A cabeça de pedido
apiKeyHeaderKey = "x-api-key"
# Endpoint URL para List Children método
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("Operation Results:", response.status_code, response.text)

# Analise o caminho do Objetode Operação para obter o recurso de Instância mais tarde. Veja a seção Política de Resultados para mais informações.
operationPath = response.json()['path']

Em vez de simplesmente listar as crianças, a resposta inclui um objeto Operation com um diferente ponto de terminação. Poll this endpoint para recuperar a lista real de crianças. Um exemplo de código mais completo parece como este:


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("Operation Results:", response.status_code, response.text)
# Analise o caminho do Objetode Operação para usar na pesquisa de recursos da instância.
operationPath = response.json()['path']
response = PollForResults(operationPath)
print("Response:", response.status_code, response.text)

A resposta final pode parecer algo assim:


{
  "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 iteração sobre o JSON para encontrar um ID de instância particular:


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:
  # The name wasn't found.

Scripts contêm algumas informações adicionais no ObjetoDetails, como o digitarde script, a originale se eles estão habilitados.

Obtendo uma Instância

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


import requests

# Gerar em https:// criar.roblox.com/ashboard / credenciais
apiKey = "<API_KEY>"
# Encontre em https://create.roblox.com/dashboards/creations no menu de sobreposição de uma experiência
universeId = "<UNIVERSE_ID>"
# Encontre o ID de local de início em https://create.roblox.com/dashboards/creations no menu de sobreposição de uma experiência
placeId = "<PLACE_ID>"
# O ID padrão para a raiz de qualquer localde dados
instanceId = "<INSTANCE_ID>"

# A cabeça de pedido
apiKeyHeaderKey = "x-api-key"
# Endpoint URL para obter o método GetInstance
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("Response:", response.status_code, response.text)

# Analise o caminho do Objetode Operação a partir da resposta. Veja a seção Política de Resultados para mais informações.
operationPath = response.json()['path']

Exatamente como o método List Instância Crianças , a resposta inclui um objeto Operation que você solicita para recuperar a instância real. Veja Polling for Results para mais informações.

Atualizando Instâncias

Depois de obter o ID de instância apropriado, você pode atualizá-lo. Vote para resultados depois de fazer a solicitar / pedirde atualização inicial.


import json
import requests

# Gerar em https:// criar.roblox.com/ashboard / credenciais
apiKey = "<API_KEY>"
# Encontre em https://create.roblox.com/dashboards/creations no menu de sobreposição de uma experiência
universeId = "<UNIVERSE_ID>"
# Encontre o ID de local de início em https://create.roblox.com/dashboards/creations no menu de sobreposição de uma experiência
placeId = "<PLACE_ID>"
instanceId = "<INSTANCE_ID>"
instanceType = ""
propertyName = ""
propertyValue = ""

# A cabeça de pedido
apiKeyHeaderKey = "x-api-key"
contentTypeHeaderKey = "Content-type"
contentTypeHeaderValue = "application/json"
# Endpoint URL para método de instância de atualização
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("Response:", response.status_code, response.text)

# Analise o caminho do Objetode operação da resposta. Poll para resultados para serem executados
# 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 sua aba de Editor de Scripts. Você também pode verificar a saída do Studio para obter erros adicionais, como Engine_OC_API: Processing Error - Live scripting session is active .

Enquetes para Resultados

Todos os métodos atuais Instância retornam um objeto Operation em vez do recurso que você solicitou. Este objeto permite que você execute o original Operation de maneira assíncrona. Use o caminho do Objeto1> Operation1> (incluído na resposta inicial) para pesquisar quando o recurso estiver pronto.

Você pode usar uma variedade de estratégias de pesquisa, como usar o backoff exponencial ou um atraso fixo entre pedidos. O exemplo a seguir pesquisa a cada cinco segundos, até 10 vezes.


import requests
import time

# Gerar em https:// criar.roblox.com/ashboard / credenciais
apiKey = "<API_KEY>"
# Use o caminho de operação a partir da sua solicitar / pedirinicial
# Toma a forma de "universos/<UNIVERSE_ID>/places/<PLACE_ID>/instances/<Instance_ID>/ operações/<OPERATION_ID>"
operationPath = "<OPERATION_PATH>"

# Constantes de Polimento
numberOfRetries = 10
retryPollingCadence = 5

# A cabeça de pedido
apiKeyHeaderKey = "x-api-key"
# URL do Endpoint para longa operação de pesquisa
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("Response:", response.status_code, response.text)

Loja de Poções Demo

A demonstração do Google Sheets mostra como atualizar o script de uma experiência da web. A demonstração consiste emseguindo

Um lugar desbloqueado sem cópia com uma interface de usuário de modelo que exibe várias poções e seus preços.
Um arquivo .ods que você importa no Google Sheets. Este arquivo de planilha permite que você especifique e atualize valores para propriedades dentro da experiência.
Código para um Google Apps Script que lê dados da Google Sheet e atualiza o script ReplicatedStorage > ItemList na experiência Potion Shop.

Configurando o Demo

Vá para a página Loja de Poções Demo. Clique no menu de sobreposição e, em seguida, Editar no Studio . O Studio se abre com uma cópia do local.
Clique em Arquivo → Salvar no Roblox e preencha as informações necessárias para salvar a Potion Shop Demo como o local padrão para sua experiência. Teste a experiência. Você deve ver a UI para a Potion Shop Demo. Obtenha uma nota da nome, custo e cores das poções. Você as alterará depois usando Open Cloud!

Configurando a Planilha

Baixar o arquivo de planilha de loja de poções.
Vá para Planilhas do Google e clique em Planilha em Branco.
Na planilha que aparece, clique em Arquivo > Importar e clique na aba Carregar .
Arraste o arquivo de planilha de loja de poções para a janela de upload.
Escolha Substituir planilha de distribuição 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. Em seguida, salve o projeto.
De volta na planilha de distribuição, selecione a aba Loja de Poções de Atualização. Clique no botão Atualizar Script, clique no menu de sobreposição e selecione Atribuir script.
Na Janela de script de atribuição , insira UpdateScript e clique em OK .

Criando uma Chave da API

Vá para a página Hub de Criador Open Cloud API Keys e clique em Criar Chave da API .
Preencha o formulário com as seguintes informações.
- Nome : PotionShop
- Sistema de API : Adicione o sistema instâncias do universo . Adicione sua experiência de loja de poções ao sistema. Para operações de experiência , adicione leitura e gravação de acesso.
- Endereços IP Aceitos : Adicionar 0.0.0.0/0 como um Endereço IP
- Expiração : Sem Expiração
- Clique em Salvar e Gerar Chave e depois Copiar Chave para a Área de Transferência.
Coloque a chave da API na célula da chave da API (D2) na aba Intro do seu Google Sheet.

Obtendo o ID do Universo e do Lugar

Vá para a página Criações do Hub de Criadores, passe o mouse sobre o tijolode experiência da Loja de Poções e clique no menu de sobreposição.
Selecione Copiar ID do Universo e cole-o na Célula do Universo (E2) na aba Início de sua planilha do Google.
Selecione Copiar ID do Local de Início e cole-o na célula ID do Local (F2) na aba Intro de sua planilha do Google.

Atualizando os Valores do Script

Na aba Loja de Poções de Atualização da página, modifique quaisquer valores que você goste e clique no botão Atualizar Script.
Se o Google Sheets solicitar sua autorização, clique em OK e permita que sua conta execute o script.
In Studio, playtest the Potion Shop to see any reflected changes. From the Explorer window, you can also open the ReplicatedStorage > ItemList script to inspect the changes.