Engine-Instanzen | Dokumentation

Die Engine Open Cloud APIs ermöglichen Ihnen die Verwaltung von Instance Objekten in Ihren Roblox-Spielen über das Web.

Beta-Beschränkungen

Diese APIs befinden sich derzeit in der Beta-Phase und haben folgende Einschränkungen:

Sie können nur Script, LocalScript und ModuleScript Objekte lesen und aktualisieren.
Sie können keine Skripte aktualisieren, die derzeit in Roblox Studio geöffnet sind.
Sie können keine Skripte aktualisieren, die Teil eines Pakets sind.
Sie können nur die API-Schlüsselauthentifizierung verwenden. Erstellen Sie einen API-Schlüssel mit universe-place-instances als API-System hinzugefügt.

Sie müssen die Spiele angeben, auf die der Schlüssel zugreifen soll, sowie die gewünschten Lese- und Schreibberechtigungsskalare.
Sie müssen eine kollaborative Sitzung für das Spiel aktiviert haben, auf das Sie zugreifen möchten.
Anfragetexte, wie unter Update Instance beschrieben, sind auf 200 KB beschränkt.

Kinder auflisten

Listen Sie alle Kinder einer bestimmten Instanz auf, indem Sie eine Instanz-ID angeben und die Methode List Instance Children aufrufen.

Beim ersten Mal, wenn Sie diese Methoden verwenden, geben Sie root für die Instanz-ID an. Nachdem Sie die Liste der obersten Kinder und deren IDs erhalten haben, können Sie zusätzliche Anfragen durchführen, um Instanzen tiefer in der Instanzhierarchie Ihres Ortes zu finden.


import requests

# Generieren unter https://create.roblox.com/dashboard/credentials
apiKey = "<API_KEY>"
# Finden Sie unter https://create.roblox.com/dashboard/creations im Überlaufmenü eines Spielkachels
universeId = "<UNIVERSE_ID>"
# Finden Sie die Start-Place-ID unter https://create.roblox.com/dashboard/creations im Überlaufmenü eines Spielkachels
placeId = "<PLACE_ID>"
# Die Standard-ID für die Wurzel des Datenmodells eines jeden Ortes
instanceId = "root"

# Anfrageheader
apiKeyHeaderKey = "x-api-key"
# Endpoint-URL für die List Children-Methode
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("Operationsergebnisse:", response.status_code, response.text)

# Parsen des Pfades des Operation-Objekts, um später die Instanzressource zu erhalten. Siehe den Abschnitt Polling for Results für weitere Informationen.
operationPath = response.json()['path']

Statt nur die Kinder aufzulisten, enthält die Antwort ein Operation-Objekt mit einem anderen Endpunkt. Abfragen Sie diesen Endpunkt, um asynchron die tatsächliche Liste der Kinder abzurufen. Ein vollständiges Beispiel sieht so aus:


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("Operationsergebnisse:", response.status_code, response.text)
# Parsen des Pfades des Operation-Objekts zur Verwendung beim Abfragen der Instanzressource.
operationPath = response.json()['path']
response = PollForResults(operationPath)
print("Antwort:", response.status_code, response.text)

Die endgültige Antwort könnte so aussehen:


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

      ...

    ]
  }
}

Sie können dann über die JSON iterieren, um eine spezielle Instanz-ID zu finden:


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

if replicatedStorageId:
  # Sie haben jetzt eine Instanz-ID und können sie abrufen oder aktualisieren.
else:
  # Der Name wurde nicht gefunden.

Skripte enthalten einige zusätzliche Informationen im Details-Objekt, wie den Skripttyp, den Quellcode und ob sie aktiviert sind.

Eine Instanz abrufen

Diese Methode gibt eine einzige Instanz zurück.


import requests

# Generieren unter https://create.roblox.com/dashboard/credentials
apiKey = "<API_KEY>"
# Finden Sie unter https://create.roblox.com/dashboard/creations im Überlaufmenü eines Spielkachels
universeId = "<UNIVERSE_ID>"
# Finden Sie die Start-Place-ID unter https://create.roblox.com/dashboard/creations im Überlaufmenü eines Spielkachels
placeId = "<PLACE_ID>"
# Die Standard-ID für die Wurzel des Datenmodells eines jeden Ortes
instanceId = "<INSTANCE_ID>"

# Anfrageheader
apiKeyHeaderKey = "x-api-key"
# Endpoint-URL für die Get Instance-Methode
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("Antwort:", response.status_code, response.text)

# Parsen des Pfades des Operation-Objekts aus der Antwort. Siehe den Abschnitt Polling for Results für weitere Informationen.
operationPath = response.json()['path']

Ähnlich wie die Methode List Instance Children enthält die Antwort ein Operation-Objekt, das Sie abfragen können, um die tatsächliche Instanz zu erhalten. Siehe For Results abfragen für weitere Informationen.

Instanzen aktualisieren

Nachdem Sie die entsprechende Instanz-ID erhalten haben, können Sie diese aktualisieren. For Results abfragen nach dem ersten Aktualisierungsanforderung.


import json
import requests

# Generieren unter https://create.roblox.com/dashboard/credentials
apiKey = "<API_KEY>"
# Finden Sie unter https://create.roblox.com/dashboard/creations im Überlaufmenü eines Spielkachels
universeId = "<UNIVERSE_ID>"
# Finden Sie die Start-Place-ID unter https://create.roblox.com/dashboard/creations im Überlaufmenü eines Spielkachels
placeId = "<PLACE_ID>"
instanceId = "<INSTANCE_ID>"
instanceType = ""
propertyName = ""
propertyValue = ""

# Anfrageheader
apiKeyHeaderKey = "x-api-key"
contentTypeHeaderKey = "Content-type"
contentTypeHeaderValue = "application/json"
# Endpoint-URL für die Update Instance-Methode
updateInstanceUrl = "https://apis.roblox.com/cloud/v2/universes/%s/places/%s/instances/%s"
# JSON-Schlüssel
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("Antwort:", response.status_code, response.text)

# Parsen des Pfades des Operation-Objekts aus der Antwort. Abfragen der Ergebnisse, um die
# Aktualisierung durchzuführen.
operationPath = response.json()['path']

Wenn Sie einen TypeError erhalten, wenn Sie versuchen, ein Skript zu aktualisieren, überprüfen Sie, ob das Skript nicht in Roblox Studio geöffnet ist. Wenn es geöffnet ist, schließen Sie den Tab des Skripteditors. Sie können auch die Studio-Ausgabe nach weiteren Fehlern überprüfen, wie Engine_OC_API: Processing Error - Live scripting session is active.

Ergebnisse abfragen

Alle aktuellen Instanz Methoden geben ein Operation-Objekt anstelle der angeforderten Ressource zurück. Dieses Objekt ermöglicht Ihnen, asynchron die ursprüngliche Operation durchzuführen. Verwenden Sie den Pfad des Operation-Objekts (der in der ursprünglichen Antwort enthalten ist), um abzufragen, wann die Ressource bereit ist.

Sie können eine Vielzahl von Abfragestrategien verwenden, z. B. exponentielles Backoff oder eine feste Verzögerung zwischen den Anfragen. Das folgende Beispiel fragt alle fünf Sekunden ab, bis zu 10 Mal.


import requests
import time

# Generieren unter https://create.roblox.com/dashboard/credentials
apiKey = "<API_KEY>"
# Verwenden Sie den Operation-Pfad von Ihrer ursprünglichen Anfrage
# Hat die Form "universes/<UNIVERSE_ID>/places/<PLACE_ID>/instances/<INSTANCE_ID>/operations/<OPERATION_ID>"
operationPath = "<OPERATION_PATH>"

# Abfragekonstanten
numberOfRetries = 10
retryPollingCadence = 5

# Anfrageheader
apiKeyHeaderKey = "x-api-key"
# Endpunkt-URL für die Abfrage von lang laufenden Operationen
getOperationUrl = "https://apis.roblox.com/cloud/v2/%s"
# JSON-Schlüssel
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("Antwort:", response.status_code, response.text)

Potion Shop-Demo

Die Potion Shop Google Sheets-Demo zeigt Ihnen, wie Sie das Skript eines Spiels über das Web aktualisieren. Die Demo besteht aus Folgendem:

Ein nicht kopiergesperrter Ort mit einer Mock-Benutzeroberfläche, die verschiedene Tränke und deren Preise anzeigt.
Eine .ods-Datei, die Sie in Google Sheets importieren. Dieses Tabellenblatt ermöglicht es Ihnen, Werte für Eigenschaften innerhalb des Spiels anzugeben und zu aktualisieren.
Code für ein Google Apps-Skript, das Daten aus dem Google Sheet liest und das Skript ReplicatedStorage > ItemList im Potion Shop-Spiel aktualisiert.

Demoversion einrichten

Gehen Sie zur Potion Shop-Demo Entdeckerseite. Klicken Sie auf das Überlaufmenü und wählen Sie dann Im Studio bearbeiten. Das Studio öffnet sich mit einer Kopie des Ortes.
Klicken Sie auf Datei → Nach Roblox speichern und füllen Sie die erforderlichen Informationen aus, um die Potion Shop-Demo als Standardplatz für Ihr Spiel zu speichern. Testen Sie das Spiel. Sie sollten die Benutzeroberfläche der Potion Shop-Demo sehen. Notieren Sie sich den Namen, die Kosten und die Farben der Tränke. Sie werden diese später mit Open Cloud ändern!

Blatteinrichtung

Laden Sie herunter die Potion Shop-Tabellenkalkulationsdatei.
Gehen Sie zu Google Sheets und klicken Sie auf Leere Tabelle.
Klicken Sie in dem erscheinenden Blatt auf Datei > Importieren und klicken Sie auf die Hochladen-Registerkarte.
Ziehen Sie die Potion Shop-Tabellenkalkulationsdatei in das Upload-Fenster.
Wählen Sie Spreadsheet ersetzen und dann Daten importieren.
Kopieren Sie im AppScript-Tab des Blattes den Code in Zelle A1.
Klicken Sie im Menü Erweiterungen > Apps Script und fügen Sie den Code in die Code.gs-Datei ein. Speichern Sie dann das Projekt.
Zurück im Tabellenblatt wählen Sie die Registerkarte Potion Shop aktualisieren. Klicken Sie auf die Schaltfläche Skript aktualisieren, klicken Sie auf das Überlaufmenü und wählen Sie Skript zuweisen.
Geben Sie im Fenster Skript zuweisen UpdateScript ein und klicken Sie auf OK.

Erstellen Sie einen API-Schlüssel

Gehen Sie zur Seite Creator Hub Open Cloud API-Schlüssel und klicken Sie auf API-Schlüssel erstellen.
Füllen Sie das Formular mit den folgenden Informationen aus:
- Name: PotionShop
- API-System: Fügen Sie das universe-place-instances API-System hinzu. Fügen Sie Ihr Potion Shop-Spiel zum System hinzu. Für Experience Operations lesen und schreiben Berechtigungen hinzufügen.
- Akzeptierte IP-Adressen: Fügen Sie 0.0.0.0/0 als IP-Adresse hinzu
- Ablauf: Kein Ablauf
- Klicken Sie auf Speichern & Schlüssel generieren und dann auf Schlüssel in die Zwischenablage kopieren.
Fügen Sie den API-Schlüssel in die API-Schlüssel-Zelle (D2) auf dem Intro-Tab Ihres Google Sheets ein.

Erhalten Sie die Universums- und Platz-ID

Gehen Sie zur Seite Creator Hub Creations, fahren Sie mit der Maus über das Spielkachel des Potion Shops und klicken Sie auf das Überlaufmenü.
Wählen Sie Universum-ID kopieren und fügen Sie sie in die Universum-ID-Zelle (E2) auf dem Intro-Tab Ihres Google Sheets ein.
Wählen Sie Start-Place-ID kopieren und fügen Sie sie in die Platz-ID-Zelle (F2) auf dem Intro-Tab Ihres Google Sheets ein.

Aktualisieren Sie die Skriptwerte

Ändern Sie im Tab Potion Shop aktualisieren des Blattes beliebige Werte, die Sie möchten, und klicken Sie auf die Schaltfläche Skript aktualisieren.
Wenn Google Sheets Sie zur Autorisierung auffordert, klicken Sie auf OK und erlauben Sie Ihrem Konto, das Skript auszuführen.
Testen Sie im Studio den Potion Shop, um die reflektierten Änderungen zu sehen. Im Explorer-Fenster können Sie auch das Skript ReplicatedStorage > ItemList öffnen, um die Änderungen zu inspizieren.