Le API Open Cloud del Motore ti consentono di gestire oggetti Instance nei tuoi giochi Roblox dal web.
Restrizioni beta
Queste API sono attualmente in beta e hanno le seguenti restrizioni:
Puoi solo leggere e aggiornare oggetti Script, LocalScript e ModuleScript.
Non puoi aggiornare script attualmente aperti in Roblox Studio.
Non puoi aggiornare script che fanno parte di un pacchetto.
Puoi usare solo l'autenticazione con chiave API. Crea una chiave API con universe-place-instances aggiunto come sistema API.
Devi specificare i giochi a cui vuoi che la chiave abbia accesso, oltre agli ambiti di permesso di lettura e scrittura desiderati.
Devi avere una sessione collaborativa abilitata per il gioco a cui vuoi accedere.
I corpi delle richieste, come per Aggiorna Istanza, sono limitati a 200 KB.
Elenca i figli
Elenca tutti i figli di un'istanza specifica specificando un ID di istanza e chiamando il metodo Elenca Figli dell'Istanza.
La prima volta che usi questi metodi, specifica root per l'ID dell'istanza. Dopo aver ricevuto l'elenco dei figli di livello superiore e dei loro ID, puoi effettuare chiamate aggiuntive per trovare istanze più in profondità nell'gerarchia delle istanze del tuo posto.
import requests
# Generato su https://create.roblox.com/dashboard/credentials
apiKey = "<API_KEY>"
# Trova su https://create.roblox.com/dashboard/creations nel menu a discesa di una scheda gioco
universeId = "<UNIVERSE_ID>"
# Trova l'ID del posto iniziale su https://create.roblox.com/dashboard/creations nel menu a discesa di una scheda gioco
placeId = "<PLACE_ID>"
# L'ID predefinito per la radice del modello di dati di qualsiasi posto
instanceId = "root"
# Intestazione della richiesta
apiKeyHeaderKey = "x-api-key"
# URL dell'endpoint per il metodo Elenco Figli
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("Risultati dell'operazione:", response.status_code, response.text)
# Analizza il percorso dell'oggetto Operazione per ottenere successivamente la risorsa dell'istanza. Vedi la sezione Polling per i Risultati per ulteriori informazioni.
operationPath = response.json()['path']
Invece di elencare semplicemente i figli, la risposta include un oggetto Operation con un endpoint diverso. Polling di questo endpoint per recuperare in modo asincrono l'elenco effettivo dei figli. Un campione di codice più completo sembra così:
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("Risultati dell'operazione:", response.status_code, response.text)
# Analizza il percorso dell'oggetto Operazione da usare nel polling per la risorsa dell'istanza.
operationPath = response.json()['path']
response = PollForResults(operationPath)
print("Risposta:", 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 su JSON per trovare un particolare ID di istanza:
Gli script contengono alcune informazioni aggiuntive nell'oggetto Details, come il tipo di script, il codice sorgente e se sono abilitati.
Ottieni un'istanza
Questo metodo restituisce una singola Istanza.
import requests
# Generato su https://create.roblox.com/dashboard/credentials
apiKey = "<API_KEY>"
# Trova su https://create.roblox.com/dashboard/creations nel menu a discesa di una scheda gioco
universeId = "<UNIVERSE_ID>"
# Trova l'ID del posto iniziale su https://create.roblox.com/dashboard/creations nel menu a discesa di una scheda gioco
placeId = "<PLACE_ID>"
# L'ID predefinito per la radice del modello di dati di qualsiasi posto
instanceId = "<INSTANCE_ID>"
# Intestazione della richiesta
apiKeyHeaderKey = "x-api-key"
# URL dell'endpoint per il metodo Ottieni Istanza
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("Risposta:", response.status_code, response.text)
# Analizza il percorso dell'oggetto Operazione dalla risposta. Vedi la sezione Polling per i Risultati per ulteriori informazioni.
operationPath = response.json()['path']
Proprio come il metodo Elenca Figli dell'Istanza, la risposta include un oggetto Operation che devi seguire per recuperare l'istanza effettiva. Vedi Polling per risultati per ulteriori informazioni.
Aggiorna istanze
Dopo aver ottenuto l'ID dell'istanza appropriato, puoi aggiornarlo. Polling per risultati dopo aver effettuato la richiesta di aggiornamento iniziale.
import json
import requests
# Generato su https://create.roblox.com/dashboard/credentials
apiKey = "<API_KEY>"
# Trova su https://create.roblox.com/dashboard/creations nel menu a discesa di una scheda gioco
universeId = "<UNIVERSE_ID>"
# Trova l'ID del posto iniziale su https://create.roblox.com/dashboard/creations nel menu a discesa di una scheda gioco
placeId = "<PLACE_ID>"
instanceId = "<INSTANCE_ID>"
instanceType = ""
propertyName = ""
propertyValue = ""
# Intestazione della richiesta
apiKeyHeaderKey = "x-api-key"
contentTypeHeaderKey = "Content-type"
contentTypeHeaderValue = "application/json"
# URL dell'endpoint per il metodo Aggiorna 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("Risposta:", response.status_code, response.text)
# Analizza il percorso dell'oggetto Operazione dalla risposta. Effettua il polling per risultati per eseguire
# l'aggiornamento.
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 dell'Editor di Script. Puoi anche controllare l'output di Studio per errori aggiuntivi, come Engine_OC_API: Processing Error - Live scripting session is active.
Polling per risultati
Tutti i metodi attuali Istanza restituiscono un oggetto Operation invece della risorsa richiesta. Quest'oggetto ti consente di eseguire asincronicamente l'operazione originale. Usa il percorso dell'oggetto Operation (incluso nella risposta iniziale) per eseguire il polling per sapere quando la risorsa è pronta.
Puoi utilizzare una varietà di strategie di polling, come l'uso del backoff esponenziale o un ritardo fisso tra le richieste. L'esempio seguente esegue il polling ogni cinque secondi, fino a 10 volte.
import requests
import time
# Generato su https://create.roblox.com/dashboard/credentials
apiKey = "<API_KEY>"
# Usa il percorso dell'Operazione dalla tua richiesta iniziale
# Assume la forma di "universes/<UNIVERSE_ID>/places/<PLACE_ID>/instances/<INSTANCE_ID>/operations/<OPERATION_ID>"
operationPath = "<OPERATION_PATH>"
# Costanti di polling
numberOfRetries = 10
retryPollingCadence = 5
# Intestazione della richiesta
apiKeyHeaderKey = "x-api-key"
# URL dell'endpoint per il polling delle operazioni a lungo termine
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("Risposta:", response.status_code, response.text)
Demo del negozio di pozioni
La demo Google Sheets del Negozio di Pozioni ti mostra come aggiornare lo script di un gioco dal web. La demo si compone dei seguenti elementi:
- Un posto non copiabile con un'interfaccia utente simulata che mostra varie pozioni e i loro prezzi.
- Un file .ods che importi in Google Sheets. Questo foglio di calcolo ti consente di specificare e aggiornare valori per le proprietà all'interno del gioco.
- Codice per uno Script Google Apps che legge i dati dal Foglio Google e aggiorna lo script ReplicatedStorage > ItemList nel gioco del Negozio di Pozioni.
Imposta la demo
Vai alla pagina di scoperta Demo Negozio di Pozioni. Clicca sul menu a discesa, quindi su Modifica in Studio. Studio si apre con una copia del posto.
Clicca su File → Salva su Roblox e compila le informazioni necessarie per salvare la Demo Negozio di Pozioni come il posto predefinito per il tuo gioco. Testa il gioco. 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 in seguito utilizzando Open Cloud!
Imposta il foglio
- Scarica il file del foglio di calcolo del Negozio di Pozioni.
- Vai su Google Sheets e clicca su Foglio di calcolo vuoto.
- Nel foglio che appare, clicca su File > Importa, e clicca sulla scheda Carica.
- Trascina il file del foglio di calcolo del Negozio di Pozioni nella finestra di upload.
- Scegli Sostituisci foglio di calcolo, quindi Importa dati.
- Nella scheda AppScript del foglio, copia il codice nella cella A1.
- Clicca sul menu Estensioni > Apps Script e incolla il codice nel file Code.gs. Quindi salva il progetto.
- Torna al foglio di calcolo, seleziona la scheda Aggiorna Negozio di Pozioni. Clicca sul pulsante Aggiorna Script, clicca sul menu a discesa e seleziona Assegna script.
- Nella finestra Assegna script, inserisci UpdateScript e clicca su OK.
Crea una chiave API
Vai alla pagina Chiavi API Open Cloud di Creator Hub e clicca su Crea chiave API.
Compila il modulo con le seguenti informazioni.
- Nome: NegozioDiPozioni
- Sistema API: Aggiungi il sistema API universe-place-instances. Aggiungi il tuo gioco del Negozio di Pozioni al sistema. Per Operazioni Esperienze, aggiungi accesso in lettura e scrittura.
- Indirizzi IP accettati: Aggiungi 0.0.0.0/0 come indirizzo IP
- Scadenza: Nessuna scadenza
- Clicca su Salva e genera chiave, quindi Copia chiave negli appunti.
Incolla la chiave API nella cella Chiave API (D2) della scheda Intro del tuo Google Sheet.
Ottieni l'ID dell'universo e del posto
- Vai alla pagina Creazioni di Creator Hub, passa il mouse sopra la scheda del gioco del Negozio di Pozioni e clicca sul menu a discesa.
- Seleziona Copia ID Universo e incollalo nella cella ID Universo (E2) della scheda Intro del tuo Google Sheet.
- Seleziona Copia ID Posto Iniziale e incollalo nella cella ID Posto (F2) della scheda Intro del tuo Google Sheet.
Aggiorna i valori dello script
- Nella scheda Aggiorna Negozio di Pozioni del foglio, modifica eventuali valori che desideri e clicca sul pulsante Aggiorna Script.
- Se Google Sheets ti richiede l'autorizzazione, clicca su OK e consenti al tuo account di eseguire lo script.
- In Studio, esegui un test del gioco del Negozio di Pozioni per vedere eventuali cambiamenti riflessi. Dalla finestra Esplora, puoi anche aprire lo script ReplicatedStorage > ItemList per ispezionare le modifiche.