Istânze del motore

Le API Open Cloud del motore ti consentono di gestire Instance oggetti nelle tue esperienze Roblox dal web.

Restrizioni beta

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

Puoi leggere e aggiornare solo Script , LocalScript e ModuleScript oggetti.
Non puoi aggiornare gli script attualmente aperti in Roblox Studio.
Non puoi aggiornare gli script che fanno parte di un pacchetto.
Puoi utilizzare solo l'autenticazione della chiave API. Crea un chiave API con universi-posti-istanze aggiunti come sistema API.

Devi specificare le esperienze a cui vuoi che la chiave abbia accesso nonché gli scopi di lettura e scrittura desiderati.
Devi avere una sessione collaborativa abilitata per l'esperienza a cui vuoi Accesso.
Le richieste di corpi, come a Aggiorna istanza, sono limitate a 200 KB.

Elenca i figli

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

La prima volta che utilizzi questi metodi, specifica root per l'ID dell'istanza.Dopo aver ricevuto l'elenco dei figli di alto livello e dei loro ID, puoi fare ulteriori chiamate per trovare istanze più profonde all'interno della gerarchia delle istanze del tuo Posto.


import requests

# Genera a https://create.roblox.com/ashboard/credenziali
apiKey = "<API_KEY>"
# Trova a https://create.roblox.com/ashboard/creations nel menu di sovrapposizione di una Piastrelladi esperienza
universeId = "<UNIVERSE_ID>"
# Trova l'ID del luogo di partenza a https://create.roblox.com/ashboard/creations nell'interfaccia di sovrascrizione di una Piastrelladi esperienza
placeId = "<PLACE_ID>"
# L'ID predefinito per il root del modello di dati di qualsiasi Posto
instanceId = "root"

# Header di richiesta
apiKeyHeaderKey = "x-api-key"
# URL finale 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 Istanza. Vedi la sezione Polling for Results per ulteriori informazioni.
operationPath = response.json()['path']

Piuttosto che elencare semplicemente i figli, la risposta include un oggetto Operation con un endpoint diverso.Vota questo endpoint per recuperare in modo asincrono l'elenco reale dei figli.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 da utilizzare nel polling per la risorsa dell'istanza.
operationPath = response.json()['path']
response = PollForResults(operationPath)
print("Response:", response.status_code, response.text)

La risposta finale potrebbe sembrare qualcosa del genere:


{
  "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 iterare sul JSON per trovare un particolare ID di 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 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.

Ottieni un'esempio

Questo metodo restituisce una singola istanza.


import requests

# Genera a https://create.roblox.com/ashboard/credenziali
apiKey = "<API_KEY>"
# Trova a https://create.roblox.com/ashboard/creations nel menu di sovrapposizione di una Piastrelladi esperienza
universeId = "<UNIVERSE_ID>"
# Trova l'ID del luogo di partenza a https://create.roblox.com/ashboard/creations nell'interfaccia di sovrascrizione di una Piastrelladi esperienza
placeId = "<PLACE_ID>"
# L'ID predefinito per il root del modello di dati di qualsiasi Posto
instanceId = "<INSTANCE_ID>"

# Header di richiesta
apiKeyHeaderKey = "x-api-key"
# URL finale per il metodo 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)

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

Proprio come il metodo List Instance Children, la risposta include un oggetto Operation che polli per recuperare l'esempioreale.Vedi Sondaggio per i risultati per ulteriori informazioni.

Aggiorna istanze

Dopo aver ottenuto l'ID istanza appropriato, puoi aggiornarlo. Vota per i risultati dopo aver fatto la Richiestadi aggiornamento iniziale.


import json
import requests

# Genera a https://create.roblox.com/ashboard/credenziali
apiKey = "<API_KEY>"
# Trova a https://create.roblox.com/ashboard/creations nel menu di sovrapposizione di una Piastrelladi esperienza
universeId = "<UNIVERSE_ID>"
# Trova l'ID del luogo di partenza a https://create.roblox.com/ashboard/creations nell'interfaccia di sovrascrizione di una Piastrelladi esperienza
placeId = "<PLACE_ID>"
instanceId = "<INSTANCE_ID>"
instanceType = ""
propertyName = ""
propertyValue = ""

# Header di richiesta
apiKeyHeaderKey = "x-api-key"
contentTypeHeaderKey = "Content-type"
contentTypeHeaderValue = "application/json"
# URL finale per il metodo Update Instance
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. Poll per i risultati da eseguire
# l'aggiornarmento.
operationPath = response.json()['path']

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

Sondaggio per i risultati

Tutti i metodi attuali dell'istanza ritornano un oggetto Operation invece della risorsa richiesta.Questo oggetto ti consente di eseguire in modo asincrono l'operazione originale.Usa il percorso dell'oggetto Operation (incluso nella risposta iniziale) per votare quando la risorsa è pronta.

Puoi utilizzare una varietà di strategie di rilevamento, come l'utilizzo di un ritardo esponenziale o un ritardo fisso tra le richieste.Il seguente esempio effettua sondaggi ogni cinque secondi, fino a 10 volte.


import requests
import time

# Genera a https://create.roblox.com/ashboard/credenziali
apiKey = "<API_KEY>"
# Usa il percorso di operazione dalla tua Richiestainiziale
# Assume la forma di "universi/<UNIVERSE_ID>/places/<PLACE_ID>/instances/<INSTANCE_ID>/ operations/<OPERATION_ID>"
operationPath = "<OPERATION_PATH>"

# Costanti di polling
numberOfRetries = 10
retryPollingCadence = 5

# Header di richiesta
apiKeyHeaderKey = "x-api-key"
# URL finale per il polling dell'operazione a lunga esecuzione
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 di pozioni

La demo di Google Sheets del negozio di pozioni ti mostra come aggiornare lo script di un'esperienza dal web. La demo consiste nel Seguendo:

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

Configura la demo

Vai alla pagina Demo del negozio di pozioni Scopri.Fai clic sul menu di sovrapposizione, quindi 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 Demo del Potion Shop come luogo predefinito per la tua esperienza.Prova l'esperienza.Dovresti vedere l'interfaccia utente per la demo del negozio di pozioni.Prendi nota del nome, del costo e dei colori delle pozioni.Li cambierai più tardi usando Open Cloud!

Imposta la foglia

Scarica il file della tabella di Potion Shop.
Vai a Google Sheets e clicca Spreadsheet vuoto .
Nella scheda che appare, fai clic su File > Importa e fai clic sulla scheda Carica .
Trascina il file della tabella di Excel del negozio di pozioni nella finestra di caricamento.
Scegli Sostituisci foglio di calcolo e poi Importa dati .
Nella scheda AppScript della foglia, copia il codice nella cella A1.
Fai clic sul menu Estensioni> Apps Script e incolla il codice nel file Code.gs. Quindi salva il progetto.
Torna nella scheda di foglio di calcolo, seleziona la scheda Aggiorna negozio di pozioni .Fai clic sul pulsante Aggiorna script , fai clic sul menu di sovrapposizione e seleziona Assegnare script .
Nella finestra Assegna script , inserisci UpdateScript e clicca OK .

Crea una chiave API

Vai alla pagina Creator Hub Open Cloud API Keys e clicca Crea chiave API .
Compila il modulo con le seguenti informazioni.
- Nome : PotionShop
- Sistema API : Aggiungi il sistema API universe-place-instances .Aggiungi la tua esperienza di negozio di pozioni al sistema.Per Operazioni di esperienza , aggiungi l'Accessodi lettura e scrittura.
- Indirizzi IP accettati : Aggiungi 0.0.0.0/0 come indirizzo IP
- Scadenza : Nessuna scadenza
- Fai clic su Salva e genera chiave e poi Copia chiave negli appunti .
Incolla la chiave API nella cella Chiave API (D2) sulla scheda Intro della tua Google Sheet.

Ottieni l'ID dell'universo e del luogo

Vai alla pagina Creazioni del Creator Hub, passa il mouse sull'Piastrelladell'esperienza del Potion Shop e fai clic sul menu di sovrapposizione.
Seleziona Copia ID Universo e pasta nella cella ID Universo (E2) sulla scheda Intro della tua Google Sheet.
Seleziona Copia ID luogo di partenza e pasta nella cella ID luogo (F2) sulla scheda Intro della tua Google Sheet.

Aggiorna i valori dello script

Nella scheda Aggiorna negozio di pozioni della foglia, modifica qualsiasi valore che desideri e fai clic sul pulsante Aggiorna script .
Se Google Sheets ti richiede l'autorizzazione, clicca OK e permetti al tuo account di eseguire lo script.
In Studio, playtest il negozio di pozioni per vedere eventuali modifiche riflesse.Dalla finestra Explorer , puoi anche aprire lo script ReplicatedStorage > ItemList per ispezionare le modifiche.

Su questa pagina