Istances del motore | Documentazione

Le API Engine Open Cloud ti consentono di gestire Instance oggetti nelle tue esperienze Roblox dalla web.

Limitazioni della Beta

Queste API sono attualmente in beta e hanno le seguenti restrizioni:

Puoi leggere e aggiornare solo oggetti Script, LocalScript, e ModuleScript .
Non puoi aggiornare gli script che sono attualmente aperti in Roblox Studio.
Non puoi aggiornare gli script che fanno parte di un pacchetto .
Puoi utilizzare solo l'autenticazione API. Crea un API key con uniiverse-place-instances aggiunto come sistema API.

Devi specificare le esperienze che vuoi che la chiave abbia accesso e anche gli scopi di autorizzazione di lettura e scrittura desiderati.
Devi avere una sessione collaborativa abilitata per l'esperienza che vuoi Accesso.
I richieste dei corpi, come per Aggiorna istanza , sono limitati a 200 KB.

Elenco dei figli

Elenca tutti i figli di un'istanza specifica specificando un ID dell'istanza e chiamando il metodo Elenca figli dell'istanza.

La prima volta che utilizzi questi metodi, specifica root per l'ID dell'istanza. Dopo aver ricevuto la lista dei figli di livello superiore e dei loro ID, puoi fare chiamate aggiuntive per trovare istanze più profonde nella gerarchia dell'istanza del tuo Posto.


import requests

# Genera a https://create.roblox.com/ashboard/credentials
apiKey = "<API_KEY>"
# Trova a https://create.roblox.com/dashboard/creations nel menu di feedback di un'esperienza
universeId = "<UNIVERSE_ID>"
# Trova Start Place ID a https://create.roblox.com/dashboard/creations nel menu di feedback di un'esperienza
placeId = "<PLACE_ID>"
# L'ID predefinito per il root di qualsiasi modello di dati
instanceId = "root"

# Richiedi HTTP
apiKeyHeaderKey = "x-api-key"
# URL del punto di fine per il metodo 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)

# Analizza il percorso dell'oggetto Operazione per ottenere in seguito la risorsa dell'istanza. Vedi la sezione Polling for Results per ulteriori informazioni.
operationPath = response.json()['path']

Invece di elencare semplicemente i figli, la risposta include un oggetto Operation con un端口不同. Poll this endpoint per recuperare in modo asincrono la lista dei figli attuali. Un esempio di codice più completo sembra questo:


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)
# Analizza il percorso dell'oggetto Operazione per utilizzare nel sondaggio per la risorsa dell'istanza.
operationPath = response.json()['path']
response = PollForResults(operationPath)
print("Response:", response.status_code, response.text)

L'ultima risposta potrebbe sembrare qualcosa come questo:


{
  "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": {}
        }
      },

      ...

    ]
  }
}

Puoi quindi itere su JSON per trovare un particolare ID dell'istanza:


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

if replicatedStorageId:
  # Ora hai un ID dell'istanza e puoi ottenerlo o aggiornarlo.
else:
  # The name wasn't found.

Gli script contengono alcune informazioni aggiuntive nell'oggetto Details, come il inserisci / scrividi script, la Sorgentee se sono abilitati.

Ottenere un'istanza

Questo metodo restituisce un singolo istanza .


import requests

# Genera a https://create.roblox.com/ashboard/credentials
apiKey = "<API_KEY>"
# Trova a https://create.roblox.com/dashboard/creations nel menu di feedback di un'esperienza
universeId = "<UNIVERSE_ID>"
# Trova Start Place ID a https://create.roblox.com/dashboard/creations nel menu di feedback di un'esperienza
placeId = "<PLACE_ID>"
# L'ID predefinito per il root di qualsiasi modello di dati
instanceId = "<INSTANCE_ID>"

# Richiedi HTTP
apiKeyHeaderKey = "x-api-key"
# URL del punto di fine per ottenere il metodo Get Instance
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)

# Analizza il percorso dell'oggetto Operazione dalla risposta. Vedi la sezione Polling for Results per ulteriori informazioni.
operationPath = response.json()['path']

Come la metodo List Instanza Bambini , la risposta include un oggetto Operation che si pollina per recuperare l'istanza esempio. Vedi Polling for Results per ulteriori informazioni.

Aggiornamento delle istanze

Dopo aver ottenuto l'ID dell'istanza appropriato, puoi aggiornarlo. Vota i risultati dopo aver fatto la Richiestainiziale di aggiornamento.


import json
import requests

# Genera a https://create.roblox.com/ashboard/credentials
apiKey = "<API_KEY>"
# Trova a https://create.roblox.com/dashboard/creations nel menu di feedback di un'esperienza
universeId = "<UNIVERSE_ID>"
# Trova Start Place ID a https://create.roblox.com/dashboard/creations nel menu di feedback di un'esperienza
placeId = "<PLACE_ID>"
instanceId = "<INSTANCE_ID>"
instanceType = ""
propertyName = ""
propertyValue = ""

# Richiedi HTTP
apiKeyHeaderKey = "x-api-key"
contentTypeHeaderKey = "Content-type"
contentTypeHeaderValue = "application/json"
# URL del punto di fine per l'aggiornamento della istanza
updateInstanceUrl = "https://apis.roblox.com/cloud/v2/universes/%s/places/%s/instances/%s"
# Chiavi 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)

# Analizza il percorso dell'oggetto Operazione dalla risposta. Polla per i risultati per eseguire
# l'aggiornarmento.
operationPath = response.json()['path']

Se ricevi un TypeError quando tenti di aggiornare uno script, verifica che lo script non sia aperto in Roblox Studio. Se lo è, chiudi la sua scheda Editor del script. Puoi anche controllare l'uscita dello Studio per errori aggiuntivi, come Engine_OC_API: Processing Error - Live scripting session is active .

Polling per i risultati

Tutti i metodi attuali Instance restituiscono un oggetto Operation invece della risorsa che hai richiesto. Questo oggetto ti consente di eseguire in parallelo l'operazione originale. Usa il percorso dell'oggetto Operation nella risposta iniziale per ottenere la pollina quando la risorsa è pronta.

Puoi utilizzare una varietà di strategie di raccolta dei dati, come l'uso di backoff esponenziale o di un ritardo fisso tra le richieste. Il seguente esempio sonda ogni cinque secondi, fino a 10 volte.


import requests
import time

# Genera a https://create.roblox.com/ashboard/credentials
apiKey = "<API_KEY>"
# Usa il percorso Operazione dalla tua Richiestainiziale
# Prende la forma di "universi/<UNIVERSE_ID>/places/<PLACE_ID>/instances/< Instance_ID>/operazioni/<OPERATION_ID>"
operationPath = "<OPERATION_PATH>"

# Costanti di polling
numberOfRetries = 10
retryPollingCadence = 5

# Richiedi HTTP
apiKeyHeaderKey = "x-api-key"
# URL del punto di fine per l'operazione di polling in tempo reale
getOperationUrl = "https://apis.roblox.com/cloud/v2/%s"
# Chiavi 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)

Demo del negozio Pozione

La dimostrazione di Google Sheets Potion Shop ti mostra come aggiornare uno script di un'esperienza dal web. La dimostrazione consiste in quanto Seguendo:

Un luogo non bloccato con un'interfaccia utente falsa che mostra varie pozioni e i loro prezzi.
Un file .ods che importi in Google Sheets. Questa planimetria ti consente di specificare e aggiornare i valori per le proprietà all'interno dell'esperienza.
Codice per uno script Google Apps che legge i dati dalla Google Sheet e aggiorna lo script ReplicatedStorage > ItemList nella esperienza Potion Shop.

Configurazione della Demo

Vai alla pagina Potion Shop Demo . Discover page. Click on the overflow menu, and then Modifica in Studio . Studio si apre con una copia del Posto.
Fai clic su File → Salva su Roblox e compila le informazioni necessarie per salvare la Potion Shop Demo come luogo predefinito per la tua esperienza. Prova l'esperienza. Vedrai l'interfaccia utente per la Potion Shop Demo. Fai una nota dei nomi, dei costi e dei colori delle pozioni. Le cambierai in seguito usando Open Cloud!

Configurazione della foglia

Scarica la planimetria del negozio Pozioni.
Vai a Google Sheets e fai clic su Spreadsheets vuoti.
Nella scheda che appare, fai clic su File > Importa e fai clic sulla scheda Carica .
Trascina il file della tabella di espansione del Negozio Pozioni nella finestra di caricamento.
Scegli Sostituisci la foglia di calcolo e poi Importa i dati .
Nella scheda AppScript della tabella, copia il codice nella cella A1.
Click the Estensioni > Apps Script menu and paste the code in the Code.gs file. Then save the project.
Nella scheda ripartizione, seleziona la scheda Aggiorna Negozio Pozioni. Fai clic sul pulsante Aggiorna script, fai clic sul menu di sovrascrittura e seleziona Assign script.
Nella finestra Assign script , inserisci UpdateScript e fai clic su OK .

Creazione di una Chiave dell'API

Vai alla pagina Creator Hub Open Cloud API Keys e fai clic su Crea Chiave API .
Compila il form con le seguenti informazioni.
- Nome : PotionShop
- API System : Aggiungi il sistema API. Aggiungi la tua esperienza Potion Shop allo sistema. Per Operazioni dell'Esperienza , aggiungi l'Accessodi lettura e scrittura.
- Indirizzi IP accettati : Aggiungi 0.0.0.0/0 come indirizzo IP
- Scadenza : Nessuna Scadenza
- Click Salva e genera chiave and then Copia chiave negli appunti .
Incolla la chiave API nella casella chiave API (D2) sulla scheda Intro della tua Google Sheet.

Ottenere l'ID dell'Universo e del Luogo

Vai alla pagina Creazioni Creator Hub, passa il mouse sul Piastrelladell'esperienza della pozione e fai clic sul menu di sovrapposizione.
Seleziona Copia ID dell'universo e pasta in the Universe ID cell (E2) on the Intro tab of your Google Sheet.
Seleziona Copia l'ID del luogo di partenza e pasta in the Luogo ID cell (F2) on the Intro tab of your Google Sheet.

Aggiornamento dei valori dello script

Nella scheda Aggiorna Negozio Pozioni della pagina, modifica i valori che desideri e fai clic sul pulsante Aggiorna Script .
Se Google Sheets ti chiede l'autorizzazione, fai clic su OK e permetti al tuo account di eseguire lo 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.