Engine-Instanzen | Dokumentation

Die Engine Open Cloud-APIs ermöglichen es Ihnen, Instance Objekte in Ihren Roblox-Erlebnissen aus dem Web zu verwalten.

Beta-Einschränkungen

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

Du kannst nur Script, LocalScript und ModuleScript Objekte lesen und aktualisieren.
Du kannst nicht Skripte aktualisieren, die in Roblox Studio offen sind.
Du kannst nicht Skripte aktualisieren, die Teil eines Pakets sind.
Du kannst nur API-Schlüssel-Authentisierung verwenden. Er erstelle einen API-Schlüssel mit Universum-Platz-Instanzen als API-System.

Du musst die Erlebnisse angeben, zu denen du den Zugriff über den Schlüssel haben möchtest, sowie die gewünschten Leseverifizierungs- und Schreibberechtigungs-Skope.
Du musst eine kooperative Sitzung aktiviert haben für das Erlebnis, auf das du Zugriffmöchtest.
Anfragen, wie z. B. um eine Instanz zu aktualisieren, sind auf 200 KB begrenzt.

Kinder aufzählen

Liste alle Kinder einer bestimmten Instanz, indem du eine Instanz-ID angeben und den Liste-Instanz-Kinder-Methode aufrufst.

Die erste Zeit, in der Sie diese Methoden verwenden, geben Sie root für die Instanz-ID an. Nachdem Sie die Liste der obersten Kinder und ihre IDs erhalten haben, können Sie zusätzliche Anrufe ausführen, um Instanzen innerhalb der Instanz-Hierarchie Ihres Ortzu finden.


import requests

# Erstellen Sie an https://create.roblox.com/ashboard/credentials
apiKey = "<API_KEY>"
# Finden Sie es unter https://create.roblox.com/dashboards/creations im Überschwemmungsmenü einer Erlebnistaste
universeId = "<UNIVERSE_ID>"
# Finde die Startplatz-ID unter https://create.roblox.com/dashboards/creations im Überschwemmungsmenü einer Kachel
placeId = "<PLACE_ID>"
# Die Standard-ID für die Wurzel eines jeden Modell
instanceId = "root"

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

# Parse the Operation Objekt's path to later obten the Instance resource. Siehe den Polling for Results-Abschnitt für mehr Informationen.
operationPath = response.json()['path']

Statt einfach die Kinder aufzulisten, enthält die Antwort ein Operation -Objekt mit einem anderen Endpunkt. Pollen Sie diesen Endpunkt , um die aktuelle Liste der Kinder asynchron abzurufen. Ein kompletter Codebeispiel sieht wie folgt 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)
# Parse the Operation Objekt's path to use in polling for the Instanzressource.
operationPath = response.json()['path']
response = PollForResults(operationPath)
print("Response:", response.status_code, response.text)

Die endgültige Antwort sieht vielleicht so aus:


{
  "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 JSONiteration eine bestimmte Instanz-ID 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 den eingeben, die Ausgangstextund ob sie aktiviert sind.

Eine Instanz erhalten

Diese Methode gibt eine einzige Instanz zurück.


import requests

# Erstellen Sie an https://create.roblox.com/ashboard/credentials
apiKey = "<API_KEY>"
# Finden Sie es unter https://create.roblox.com/dashboards/creations im Überschwemmungsmenü einer Erlebnistaste
universeId = "<UNIVERSE_ID>"
# Finde die Startplatz-ID unter https://create.roblox.com/dashboards/creations im Überschwemmungsmenü einer Kachel
placeId = "<PLACE_ID>"
# Die Standard-ID für die Wurzel eines jeden Modell
instanceId = "<INSTANCE_ID>"

# Anfrage-Header
apiKeyHeaderKey = "x-api-key"
# Endpunkt-URL für die Methode Holen Sie sich eine Instanz
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)

# Parse the Operation Objekt's path from response. Siehe den Polling for Results-Bereich für weitere Informationen.
operationPath = response.json()['path']

Wie die Methode List Instanz Kinder , enthält die Antwort ein Operation -Objekt, das Sie abrufen, um die aktuelle Instanz zu extrahieren. Siehe Polling for Results für weitere Informationen.

Instanzen aktualisieren

Nachdem Sie die entsprechende Instanz-ID erhalten haben, können Sie sie aktualisieren. Poll for results nach dem Erstellen der ersten Anfrage.


import json
import requests

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

# Anfrage-Header
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)

# Parse the Operation Objekt's path from response. Poll for results to perform
# das update.
operationPath = response.json()['path']

Wenn Sie beim Versuch, ein Skript, das. PL: die Skriptszu aktualisieren, ein TypeError erhalten, überprüfen Sie, dass das Skript nicht in Roblox Studio geöffnet ist. Wenn es geöffnet ist, schließen Sie seine Skript-Editor-Registerkarte. Sie können auch den Studio-Ausgabe für zusätzliche Fehler überprüfen, z. B. Engine_OC_API: Processing Error - Live scripting session is active.

Ergebnisse abrufen

Alle aktuellen Instanz--Methode zurückgeben ein Operation -Objekt anstelle des Ressourcen, die Sie angefordert haben. Dieses Objekt ermöglicht es Ihnen, die ursprüngliche Operation asynchron auszuführen. Verwenden Sie den Pfad des Operation -Objekts in der ursprünglichen Antwort, um zu Pollen, wenn die Ressource bereit ist.

Sie können eine Vielzahl von Umfragestrategien verwenden, z. B. Exponential-Rückgängigmachung oder eine feste Verzögerung zwischen Anfragen. Das folgende Beispiel Polls alle fünf Sekunden, bis zu 10 Mal.


import requests
import time

# Erstellen Sie an https://create.roblox.com/ashboard/credentials
apiKey = "<API_KEY>"
# Verwenden Sie den Operation-Weg von Ihrer ursprünglichen Anfrage
# Nimmt die Form an "Universen/<UNIVERSE_ID>/places/<PLACE_ID>/instances/< Instance_ID>/Operations/< OPERATION_ID>"
operationPath = "<OPERATION_PATH>"

# Konstanten abrufen
numberOfRetries = 10
retryPollingCadence = 5

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

Trankshop-Demo

Die Potion Shop Google Sheets-Demonstration zeigt Ihnen, wie Sie das Skript eines Erlebnisses aus der Web-site aktualisieren. Die Demo besteht aus dem gefolgte Profile:

Ein nicht kopierbarer Ort mit einer Mimic-Benutzeroberfläche, die verschiedene Tränke und ihre Preise anzeigt.
Ein .ods-Datei, das Sie in Google Sheets importieren. Dieser Spreadsheets ermöglicht es Ihnen, Werte für Eigenschaften innerhalb der Erlebnisanzugeben 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 Potion Shop Demo Seite. Klicke auf das Überschwemmungsmenü und dann Bearbeiten in Studio . Studio öffnet mit einer Kopie des Ortes.
Klicke auf Datei → Speichern in Roblox und fülle die notwendigen Informationen aus, um den Trankshop-Demo als Standardort für dein Erlebnis zu speichern. Teste das Erlebnis. Du solltest die UI für den Trankshop-Demo sehen. Make a Note of the name, cost, und Farben der Tränke. Du wirst sie später mit Open Cloud ändern!

Die Seite einrichten

Download die Tränke-Shop-Verkauf-Excel-Datei.
Gehe zu Google Sheets und klicke auf Leere Excel-Seite .
In der erscheinenden Tabelle klicken Sie auf Datei > Importieren und klicken Sie auf die Upload-Registerkarte .
Ziehen Sie den Trankshop-Spreadsheets in das Upload-Fenster.
Wählen Sie Erweiterungsbereich ersetzen und dann Daten importieren .
In der AppScript-Registerkarte der Seite kopieren Sie den Code in Zelle A1.
Klicken Sie auf das Extensions > Apps Script Menü und fügen Sie den Code in das Code.gs-Datei ein. Dann speichern Sie das Projekt.
Zurück in der Spreadsheetselektieren Sie die Update Trank-Shop-Registerkarte. Klicken Sie auf die Schaltfläche Skript aktualisieren und klicken Sie auf das Überlaufsmenü und wählen Sie Skript zuweisen.
In dem Skript zuweisen -Fenster geben Sie UpdateScript ein und klicken Sie auf OK .

Erstellen eines API-Schlüssels

Gehe zur Creator Hub Open Cloud API Keys Seite und klicke auf API-Schlüssel erstellen .
Füllen Sie die folgenden Informationen mit dem Formular aus.
- Name : TränkeShop
- API-System : Fügen Sie das Universum-Platz-Instanzen API-System hinzu. Fügen Sie Ihren Potion Shop-Erlebnis dem System hinzu. Für Erfahrungsoperationen fügen Sie den Zugriff auf Lesen und Schreiben hinzu.
- Akzeptierte IP-Adressen : Füge 0.0.0.0/0 als IP-Adresse hinzu
- Expiration : Keine Expiration
- Klicken Sie auf Speichern und generieren Sie Schlüssel und dann Kopieren Sie Schlüssel in die Zwischenablage .
Fügen Sie den API-Schlüssel in die API-Schlüsselzelle (D2) auf der Registerkarte Intro Ihrer Google Sheet ein.

Universum und Platz-ID erhalten

Gehe zur Creator Hub Creations Seite, bewegen Sie den Mauszeiger über die Kachel des Tränke-Shops und klicken Sie auf die Schaltfläche "Überschwemmung".
Wählen Sie Kopieren Sie Universum-ID und fügen Sie sie in die Universum-ID Zelle (E2) auf der Intro-Registerkarte Ihrer Google Sheet ein.
Wählen Sie Kopieren Startplatz-ID und fügen Sie sie in die Platz-ID-Zelle (F2) auf der Intro-Registerkarte Ihrer Google Sheet ein.

Aktualisieren der Skript-werte

In der Update Potion Shop -Registerkarte der Seite ändern Sie alle Werte, die Sie möchten, und klicken Sie auf die Schaltfläche Update Script .
Wenn Google Sheets Sie zur Autorisierung auffordert, klicken Sie auf OK und lassen Sie Ihr Konto das Skript, das. PL: die Skriptsausführen.
In Studio, testen Sie den Trank-Shop, um irgendwelche reflektierte Änderungen zu sehen. Von dem Explorer-Fenster aus können Sie auch das ReplicatedStorage-Skript öffnen, um die Änderungen zu überprüfen.