Engine-Instanzen

Die Engine Open Cloud-APIs ermöglichen es dir, Instance Objekte in deinen Roblox-Erlebnissen von der Webseite aus zu verwalten.

Beta-Einschränkungen

Diese APIs sind derzeit in der Beta und haben die folgenden Einschränkungen:

Du kannst nur lesen und aktualisieren Script , LocalScript und ModuleScript Objekte.
Du kannst Skripte nicht aktualisieren, die derzeit in Roblox Studio geöffnet sind.
Du kannst keine Skripte aktualisieren, die Teil eines Pakets sind.
Du kannst nur die API-Schlüsselauthentifizierung verwenden. Erstelle einen API-Schlüssel mit Universum-Platz-Instanzen , die als API-System hinzugefügt wurden.

Du musst die Erlebnisse angeben, zu denen der Schlüssel Zugriff haben soll, sowie die gewünschten Lesen- und Schreibberechtigungsbereiche.
Du musst eine kooperative Sitzung für die Erfahrung aktivieren, auf die du Zugriffmöchtest.
Anforderungskörper, wie z. B. Instanz aktualisieren, sind auf 200 KB beschränkt.

Kinder listen

Liste alle Kinder einer bestimmten Instanz, indem du eine Instanz-ID angibst und die Methode Instanzkindern listen aufrufst.

Das erste Mal, wenn du diese Methoden verwendest, gib root für die Instanz-ID an.Nachdem du die Liste der obersten Kinder und ihre IDs erhalten hast, kannst du zusätzliche Anrufe starten, um Instanzen tiefer in der Instanzarchitektur deines Ortzu finden.


import requests

# Erstellen unter https://create.roblox.com/ashboard/credentials
apiKey = "<API_KEY>"
# Finde es unter https://create.roblox.com/ashboard/creations im Überlaufmenü einer Erlebniskachel
universeId = "<UNIVERSE_ID>"
# Finde die Startplatz-ID unter https://create.roblox.com/ashboard/creations im Überlaufmenü einer Erlebniskachel
placeId = "<PLACE_ID>"
# Die Standard-ID für das Modelleines Ortes
instanceId = "root"

# Anforderungskopf
apiKeyHeaderKey = "x-api-key"
# Endpunkt-URL für Methode 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)

# Parst den Weg des Operation-Objekts, um die Instanzressource später zu erhalten. Siehe den Abschnitt "Ergebnisse abrufen" für weitere Informationen.
operationPath = response.json()['path']

Anstatt nur die Kinder aufzulisten, enthält die Antwort ein Operation Objekt mit einer anderen Endpunkt. Stimme dieser Endpunkt ab, um die tatsächliche Liste der Kinder asynchron abzurufen.Ein vollständigeres Codebeispiel 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("Operation Results:", response.status_code, response.text)
# Parst den Weg des Operation-Objekts, um ihn bei der Abfrage der Instanzressource zu verwenden.
operationPath = response.json()['path']
response = PollForResults(operationPath)
print("Response:", 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": {}
        }
      },

      ...

    ]
  }
}

Du kannst dann über die JSON iterieren, um eine bestimmte 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:
  # Du hast jetzt eine Instanz-ID und kannst sie erhalten oder aktualisieren.
else:
  # The name wasn't found.

Skripte enthalten einige zusätzliche Informationen im Details Objekt, wie zum Beispiel den eingeben, die Ausgangstextund ob sie aktiviert sind.

Erhalte eine Instanz

Diese Methode gibt eine einzige Instanz zurück.


import requests

# Erstellen unter https://create.roblox.com/ashboard/credentials
apiKey = "<API_KEY>"
# Finde es unter https://create.roblox.com/ashboard/creations im Überlaufmenü einer Erlebniskachel
universeId = "<UNIVERSE_ID>"
# Finde die Startplatz-ID unter https://create.roblox.com/ashboard/creations im Überlaufmenü einer Erlebniskachel
placeId = "<PLACE_ID>"
# Die Standard-ID für das Modelleines Ortes
instanceId = "<INSTANCE_ID>"

# Anforderungskopf
apiKeyHeaderKey = "x-api-key"
# Endpunkt-URL für die Abruf-Methode 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)

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

Genau wie die Methode Listen-Instanz-Kinder, enthält die Antwort ein Operation Objekt, das Sie abrufen, um die tatsächliche Instanz zu erhalten.Siehe Umfrage für Ergebnisse für weitere Informationen.

Aktualisieren von Instanzen

Nachdem du die entsprechende Instanz-ID erhalten hast, kannst du sie aktualisieren. Stimme für Ergebnisse ab nachdem du die ursprüngliche Anfragegestellt hast.


import json
import requests

# Erstellen unter https://create.roblox.com/ashboard/credentials
apiKey = "<API_KEY>"
# Finde es unter https://create.roblox.com/ashboard/creations im Überlaufmenü einer Erlebniskachel
universeId = "<UNIVERSE_ID>"
# Finde die Startplatz-ID unter https://create.roblox.com/ashboard/creations im Überlaufmenü einer Erlebniskachel
placeId = "<PLACE_ID>"
instanceId = "<INSTANCE_ID>"
instanceType = ""
propertyName = ""
propertyValue = ""

# Anforderungskopf
apiKeyHeaderKey = "x-api-key"
contentTypeHeaderKey = "Content-type"
contentTypeHeaderValue = "application/json"
# Endpunkt-URL für Update-Instanz-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("Response:", response.status_code, response.text)

# Parst den Weg des Operation-Objekts aus der Antwort. Frage nach Ergebnissen zur Ausführung
# das update.
operationPath = response.json()['path']

Wenn du beim Versuch, ein Skript, das. PL: die Skriptszu aktualisieren, eine TypeError erhältst, überprüfe, dass das Skript nicht in Roblox Studio geöffnet ist.Wenn es das ist, schließe seine Skript-Editor-Registerkarte.Du kannst auch die Studio-Ausgabe auf zusätzliche Fehler überprüfen, wie z. B. Engine_OC_API: Processing Error - Live scripting session is active.

Umfrage zu Ergebnissen

Alle aktuellen Instanz-Methoden geben stattdessen ein Operation zurück, anstatt die angeforderte Ressource.Dieses Objekt ermöglicht es Ihnen, die ursprüngliche Operation asynchron auszuführen.Verwende den Pfad des Operation Objekts (enthalten in der initialen Antwort) zur Abstimmung, wann die Ressource bereit ist.

Du kannst eine Vielzahl von Umfrage-Strategien verwenden, wie z. B. die Verwendung eines exponentiellen Rückgangs oder einer festen Verzögerung zwischen den Anfragen.Das folgende Beispiel durchfragt alle fünf Sekunden, bis zu 10 Mal.


import requests
import time

# Erstellen unter https://create.roblox.com/ashboard/credentials
apiKey = "<API_KEY>"
# Verwende den Operation-Pfad von deiner ursprünglichen Anfrage
# Nimmt die Form von "Universen/<UNIVERSE_ID>/Plätze/<PLACE_ID>/Instanzen/<INSTANCE_ID>/Operationen/<OPERATION_ID>" an
operationPath = "<OPERATION_PATH>"

# Umfragekonstanten
numberOfRetries = 10
retryPollingCadence = 5

# Anforderungskopf
apiKeyHeaderKey = "x-api-key"
# Endpunkt-URL für lange laufende Betriebsumfragen
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("Response:", response.status_code, response.text)

Trank-Shop-Demo

Die Potion Shop Google Sheets-Demo zeigt Ihnen, wie Sie das Skript einer Erlebnisvom Web aktualisieren. Die Demo besteht aus dem gefolgte Profile:

Ein nicht kopierbarer Ort mit einer Test-Benutzeroberfläche, die verschiedene Tränke und ihre Preise anzeigt.
Eine .ods Datei, die du in Google-Tabellen importierst. Diese Tabelle ermöglicht es dir, Werte für Eigenschaften innerhalb des Erlebnisses zu spezifizieren und zu aktualisieren.
Code für ein Google Apps-Skript, das Daten aus der Google-Tabelle liest und das ReplicatedStorage > ItemList -Skript im Potion-Shop-Erlebnis aktualisiert.

Die Demo einrichten

Gehe zur Trank-Shop-Demo Entdecke-Seite.Klicken Sie auf das Überlaufmenü und dann Bearbeiten im Studio .Studio öffnet sich mit einer Kopie des Ortes.
Klicke auf Datei → In Roblox speichern und fülle die erforderlichen Informationen aus, um den Trank-Shop-Demo als Standardplatz für deine Erfahrung zu speichern.Teste das Erlebnis.Du solltest die Benutzeroberfläche für die Potion Shop Demo sehen.Mache eine Notiz von dem Namen, der Kosten und den Farben der Tränke.Du wirst sie später mit Open Cloud ändern!

Stelle das Blatt ein

Download die Potion Shop-Tabellenk file.
Gehe zu Google-Tabellen und klicke auf Leeres Arbeitsblatt .
Klicken Sie in der erscheinenden Tabelle auf Datei > Import und klicken Sie auf die Upload Registerkarte.
Ziehe die Potion-Shop-Tabellenkalkulationsdatei in das Upload-Fenster.
Wählen Sie Tabelle ersetzen und dann Daten importieren .
Kopiere auf der Registerkarte AppScript der Tabelle den Code in Zelle A1.
Klicken Sie auf das Erweiterungen > App-Skript -Menü und fügen Sie den Code in die Code.gs ein. Speichern Sie dann das Projekt.
Kehre im Spreadsheet zur Update-Trank-Shop -Registerkarte zurück.Klicken Sie auf die Schaltfläche Aktualisierungsskript , klicken Sie auf das Überlaufmenü und wählen Sie Skript zuweisen .
Im Skript zuweisen -Fenster geben Sie UpdateScript ein und klicken Sie auf OK .

Erstelle einen API-Schlüssel

Gehen Sie auf die Seite Creator Hub Open Cloud API-Schlüssel und klicken Sie auf API-Schlüssel erstellen .
Füllen Sie die Form mit den folgenden Informationen aus.
- Name : PotionShop
- API-System : Füge das Universum-Platz-Instanz-System API-System hinzu.Füge deine Trank-Shop-Erfahrung dem System hinzu.Für Erfahrungsoperationen füge Lesen- und Zugriffhinzu.
- Akzeptierte IP-Adressen : Fügen Sie 0.0.0.0/0 als IP-Adresse hinzu
- Verfall : Kein Verfall
- Klicken Sie auf Speichern und Schlüssel generieren und dann auf Schlüssel in Zwischenablage kopieren .
Füge den API-Schlüssel in die API-Schlüsselfeldzelle (D2) auf der Intro-Registerkarte deines Google-Sheets ein.

Erhalten Sie das Universum und die Platz-ID

Gehe zur Seite Creator Hub Creations, bewegen Sie den Mauszeiger über die Kacheldes Trankladens und klicken Sie auf das Überlaufmenü.
Wählen Sie Kopieren Universitäts-ID und fügen Sie sie in die Universitäts-ID Zelle (E2) auf der Registerkarte Intro Ihrer Google-Tabelle ein.
Wählen Sie Kopieren Startplatz-ID und fügen Sie sie in die Platz-ID Zelle (F2) auf der Intro-Registerkarte Ihrer Google-Tabelle ein.

Aktualisieren Sie die Skriptwerte

In der Aktualisierungstrank-Shop -Registerkarte der Seite modifizieren Sie alle Werte, die Sie möchten, und klicken Sie auf die Schaltfläche Aktualisierungsskript aktualisieren .
Wenn Google Sheets Sie zur Autorisierung auffordert, klicken Sie auf OK und lassen Sie Ihr Konto das Skript, das. PL: die Skriptsausführen.
Im Studio teste den Trank-Shop, um alle reflektierten Änderungen zu sehen.Aus dem Explorer -Fenster kannst du auch das ReplicatedStorage > ItemList -Skript öffnen, um die Änderungen zu überprüfen.

Auf dieser Seite