Instâncias do motor

As APIs de Nuvem Aberta do Motor permitem que você gerencie Instance objetos em suas experiências do Roblox na 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 atualmente abertos no Roblox Studio.
Você não pode atualizar scripts que fazem parte de um pacote.
Você só pode usar a autenticação de chave da API. Crie uma chave da API com instâncias de lugar do universo adicionadas como um sistema de API.

Você deve especificar as experiências 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 habilitada para a experiência que deseja acesso.
Corpos de solicitação, como para Atualizar Instância, são limitados a 200 KB.

Listar filhos

Liste todos os filhos de uma instância específica especificando um ID de instância e chamando 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 alto nível e seus IDs, você pode fazer chamadas adicionais para encontrar instâncias mais profundas na hierarquia de instâncias do seu local.


import requests

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

# Cabeceio de solicitação
apiKeyHeaderKey = "x-api-key"
# URL de endpoint para método List Children
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 mais tarde o recurso de Instância. Veja a seção de Polling for Results para mais informações.
operationPath = response.json()['path']

Em vez de apenas listar as crianças, a resposta inclui um objeto Operation com um ponto de extremidade diferente. Vote neste ponto final para recuperar assincronamente a lista real de crianças.Um exemplo de código mais completo parece assim:


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 para a instância de recursos.
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 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:
  # Você agora tem um ID de instância e pode obter 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 estão habilitados.

Obtenha uma instância

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


import requests

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

# Cabeceio de solicitação
apiKeyHeaderKey = "x-api-key"
# URL de 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("Response:", response.status_code, response.text)

# Analise o caminho do Objetode operação na resposta. Veja a seção de Polling for Results para mais informações.
operationPath = response.json()['path']

Assim como o método List Institute Children, a resposta inclui um objeto Operation que você solicita para recuperar a instância real.Veja Votação para resultados para mais informações.

Atualizar instâncias

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


import json
import requests

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

# Cabeceio de solicitação
apiKeyHeaderKey = "x-api-key"
contentTypeHeaderKey = "Content-type"
contentTypeHeaderValue = "application/json"
# URL de endpoint para o método Update Instance
updateInstanceUrl = "https://apis.roblox.com/cloud/v2/universes/%s/places/%s/instances/%s"
# ChavesJSON
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 a partir da resposta. Vote nos resultados a serem executados
# a atualização.
operationPath = response.json()['path']

Se você receber um TypeError quando tentar atualizar um script, verifique se o script não está aberto no Roblox Studio.Se for, feche a aba 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 .

Votação para resultados

Todos os métodos atuais de Instância retornam um objeto Operation em vez do recurso solicitado.Este objeto permite que você execute de forma assíncrona a operação original.Use o caminho do ObjetoOperation para solicitar quando a recursa está pronta.

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


import requests
import time

# Gerar em https://create.roblox.com/ashboard/credenciais
apiKey = "<API_KEY>"
# Use o caminho de operação da sua solicitar / pedirinicial
# Assume a forma de "universos/<UNIVERSE_ID>/locais/<PLACE_ID>/instâncias/<INSTANCE_ID>/operações/<OPERATION_ID>"
operationPath = "<OPERATION_PATH>"

# Constantes de pesquisa
numberOfRetries = 10
retryPollingCadence = 5

# Cabeceio de solicitação
apiKeyHeaderKey = "x-api-key"
# URL de endpoint para pesquisa de operação de longa duração
getOperationUrl = "https://apis.roblox.com/cloud/v2/%s"
# ChavesJSON
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)

Demo da Loja de Poções

A demonstração da Loja de Poções do Google Sheets mostra como atualizar o script de uma experiência da web. A demonstração consiste no seguindo:

Um local desbloqueado sem cópia com uma interface de mock que exibe várias poções e seus preços.
Um arquivo .ods que você importa para planilhas do Google. Esta planilha permite que você especifique e atualize valores para propriedades dentro da experiência.
Código para um Script do Google Apps que lê dados da Planilha Google e atualiza o script ReplicatedStorage > ItemList na experiência da Loja de Poções.

Configure a demonstração

Vá para a página Demonstração da Loja de Poções Descubra.Clique no menu de transbordamento, e então Editar no Studio .O Studio abre com uma cópia do local.
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 local padrão para sua experiência.Teste a experiência.Você deve ver a interface de usuário para a Demonstração da Loja de Poções.Faça um registro do nome, custo e cores das poções.Você as alterará mais tarde usando a Nuvem Aberta!

Configurar a folha

Baixar o arquivo da planilha da Loja de Poções.
Vá para Folhas do Google e clique em Folha em branco .
Na folha 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 folha, 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, selecione a aba Atualizar Loja de Poções .Clique no botão Atualizar Script , clique no menu de transbordamento e selecione Atribuir script .
Na janela Atribuir script , insira UpdateScript e clique em OK .

Crie uma chave de API

Vá para a página Criar Hub de Nuvem Aberta API Chaves do Criador e clique em Criar Chave da API .
Preencha o formulário com as seguintes informações.
- Nome : PotionShop
- Sistema de API : Adicione o sistema de API universal-place-instances .Adicione a sua experiência na 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 e Gerar Chave e depois em Copiar Chave para a Área de Transferência .
Cole a chave da API na célula de Chave da API (D2) na aba Intro do seu Google Sheet.

Obtenha o ID do universo e do local

Vá para a página Criações do Hub do Criador, passe o mouse sobre o tijoloda 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 ID do Universo (E2) na aba Intro do seu Google Sheet.
Selecione Copiar ID do Local de Partida e cole-o na célula ID do Local (F2) na aba Intro do seu Google Sheet.

Atualize os valores do script

Na aba Loja de Poções de Atualização da folha, modifique quaisquer valores que você deseje 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.
No Studio, teste o PlayShop de Poções para ver quaisquer alterações refletidas.Da janela Explorer , você também pode abrir o script ReplicatedStorage > ItemList para inspecionar as alterações.

Nesta página