Instancje silnika | Dokumentacja – Centrum twórców Roblox

Interfejsy API Engine Open Cloud umożliwiają zarządzanie Instance obiektami w Twoich doświadczeniach Roblox z witryny.

Ograniczenia Beta

Te API są obecnie w wersji beta i mają następujące ograniczenia:

Możesz tylko czytać i aktualizować Script, LocalScript i ModuleScript obiekty.
Nie możesz aktualizować skryptów, które są obecnie otwarte w Roblox Studio.
Nie możesz aktualizować skrypt, które są częścią pakietu.
Możesz używać tylko uwierzytelniania klucza API. Stwórz klucz API z place-instances universe-place dodanym jako system API.

Musisz określić doświadczenia, których chcesz, aby klucz miał dostęp, a także zakresy uprawnień czytania i zapisu.
Musisz mieć włączoną sesję współpracy dla doświadczenia, do którego chcesz uzyskać dostęp.
Żądania ciała, takie jak Aktualizuj przypadek, są ograniczone do 200 KB.

Lista Dzieci

Lista wszystkich dzieci określonego instancji poprzez określenie ID instancji i wezwanie metody List Child Instances.

Po raz pierwszy, gdy używasz tych metod, określ root dla ID instancji. Po otrzymaniu listy dzieci i ich ID, możesz wykonać dodatkowe wezwania, aby znaleźć instancje głębsze w hierarchii instancji twojego miejsce.


import requests

# Generuj pod adresem https://create.roblox.com/dash/credentials
apiKey = "<API_KEY>"
# Znajdź w https://create.roblox.com/dashboards/creations w menu przepustowym wtyczki
universeId = "<UNIVERSE_ID>"
# Znajdź ID punktu wyjścia na https://create.roblox.com/dash/creations w menu przepustki doświadczenia
placeId = "<PLACE_ID>"
# Domyślny identyfikator dla korzenia dowolnego modelu danych
instanceId = "root"

# Żądaj nagłówka
apiKeyHeaderKey = "x-api-key"
# Endpoint URL dla metody 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)

# Zbierz ścieżkę obiektu Operacji, aby później uzyskać zasób Instancji. Zobacz sekcję Polling for Results po więcej informacji.
operationPath = response.json()['path']

Zamiast po prostu wymieniać dzieci, odpowiedź zawiera obiekt Operation z innym końcem. Zagłosuj na ten końc aby w pełni odzyskać aktualną listę dzieci. Bardziej kompletny przykład kodu wygląda następująco:


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)
# Zbierz ścieżkę obiektu Operacji do użycia w głosowaniu na zasoby instancji.
operationPath = response.json()['path']
response = PollForResults(operationPath)
print("Response:", response.status_code, response.text)

Ostateczna odpowiedź może wyglądać coś takiego:


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

      ...

    ]
  }
}

Następnie możesz przetestować JSON, aby znaleźć określny identyfikator instancji:


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

if replicatedStorageId:
  # Teraz masz ID instancji i możesz ją uzyskać lub aktualizować.
else:
  # The name wasn't found.

Skrypty zawierają dodatkowe informacje w obiekcie Details, takie jak wpisywaćskryptu, kod źródłowyi czy są włączone.

Zdobycie instancji

Ten metod returnuje pojedynczą Instancję .


import requests

# Generuj pod adresem https://create.roblox.com/dash/credentials
apiKey = "<API_KEY>"
# Znajdź w https://create.roblox.com/dashboards/creations w menu przepustowym wtyczki
universeId = "<UNIVERSE_ID>"
# Znajdź ID punktu wyjścia na https://create.roblox.com/dash/creations w menu przepustki doświadczenia
placeId = "<PLACE_ID>"
# Domyślny identyfikator dla korzenia dowolnego modelu danych
instanceId = "<INSTANCE_ID>"

# Żądaj nagłówka
apiKeyHeaderKey = "x-api-key"
# URL końcowy dla metody 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)

# Zbierz ścieżkę obiektu Operacji z odpowiedzi. Zobacz sekcję Badanie wyników, aby uzyskać więcej informacji.
operationPath = response.json()['path']

Podobnie jak metoda List Instancia Children, odpowiedź zawiera obiekt Operation, który pollujesz, aby odzyskać rzeczywistą instancja. Zobacz Polling for Results dla więcej informacji.

Aktualizowanie instancji

Po uzyskaniu odpowiedniego identyfikatora instancji możesz go aktualizować. Zagłosuj na wyniki po dokonaniu pierwszej prośbao aktualizację.


import json
import requests

# Generuj pod adresem https://create.roblox.com/dash/credentials
apiKey = "<API_KEY>"
# Znajdź w https://create.roblox.com/dashboards/creations w menu przepustowym wtyczki
universeId = "<UNIVERSE_ID>"
# Znajdź ID punktu wyjścia na https://create.roblox.com/dash/creations w menu przepustki doświadczenia
placeId = "<PLACE_ID>"
instanceId = "<INSTANCE_ID>"
instanceType = ""
propertyName = ""
propertyValue = ""

# Żądaj nagłówka
apiKeyHeaderKey = "x-api-key"
contentTypeHeaderKey = "Content-type"
contentTypeHeaderValue = "application/json"
# Endpoint URL dla metody Update Institution
updateInstanceUrl = "https://apis.roblox.com/cloud/v2/universes/%s/places/%s/instances/%s"
# Klucze 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)

# Zbierz ścieżkę obiektu Operacji z odpowiedzi. Zapytaj o wyniki, aby wykonić
# aktualizacja.
operationPath = response.json()['path']

Jeśli otrzymujesz TypeError podczas próby aktualizacji skryptu, sprawdź, czy skrypt nie jest otwarty w Roblox Studio. Jeśli jest, zamknij jego stronę Edytora Skryptów. Możesz również sprawdzić wynik Studio dla dodatkowych błędów, takich jak Engine_OC_API: Processing Error - Live scripting session is active .

Głosowanie na wyniki

Wszystkie obecne metody Instancja zwracają obiekt Operation zamiast zasobu, którego prośbono. Ten obiekt umożliwia wykonanie asynchronicznej operacji. Użyj ścieżki Operation w obiekcie, aby zbadać, kiedy zasób jest gotowy.

Możesz używać różnych strategii ankietowania, takich jak używanie eksponencjalnego odchylenia lub stałego opóźnienia między prośbami. Następny przykład ankietuje co pięć sekund, do 10 razy.


import requests
import time

# Generuj pod adresem https://create.roblox.com/dash/credentials
apiKey = "<API_KEY>"
# Użyj drogi operacji z twojego pierwotnego prośba
# Bierze formę "uniwersyty/<UNIVERSE_ID>/places/<PLACE_ID>/instances/< Instance_ID>/operacje/<OPERATION_ID>"
operationPath = "<OPERATION_PATH>"

# Polowanie na konstytucje
numberOfRetries = 10
retryPollingCadence = 5

# Żądaj nagłówka
apiKeyHeaderKey = "x-api-key"
# URL końcowy dla długoterminowej operacji polowania
getOperationUrl = "https://apis.roblox.com/cloud/v2/%s"
# Klucze 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)

Demonstracja sklepu z Eliksirami

Demonstracja Google Sheets Potion Shop pokazuje, jak aktualizować skrypt doświadczenia z witryny. Demonstracja składa się z obserwujeelementów:

Odblokowane miejsce z mock UI, które wyświetla różne eliksiry i ich ceny.
Plik .ods, który importujesz do Google Sheets. Ta planeta rozprzestrzeni pozwala na określenie i aktualizację wartości dla właściwości w doświadczeniu.
Kod dla Google Apps Script, który czyta dane z Google Sheet i aktualizuje ReplicatedStorage > ItemList skrypt w doświadczeniu Potion Shop.

Konfiguracja Demo

Idź do strony Potion Shop Demo Dисcover. Kliknij na menu przewijania i następnie Edytuj w Studio Studio otwiera się z kopią miejsce.
Kliknij Plik → Zapisz w Roblox i wypełnij niezbędne informacje, aby zapisać Potion Shop Demo jako domyślną lokalizację dla twojego doświadczenia. Testuj doświadczenie. Powinieneś zobaczyć UI dla Potion Shop Demo. Zapisz je później używając Open Cloud!

Ustawienie arkusza

Zapisz plik Potion Shop rozszerzenia pliku.
Idź do Google Sheets i kliknij Pusty arkusz Excel.
Występującym arkuszu kliknij Plik > Importuj i kliknij Uploaduj tab.
Przeciągnij plik rozszerzenia Potion Shop do okienka wstawienia.
Wybierz Zastąp arkusz roboczy i następnie Importuj dane .
W zakładce AppScript na liście skopiuj kod w komórce A1.
Kliknij menu Extensions > Apps Script i wklej kod w plik Code.gs. Następnie zapisz projekt.
Wróć do arkusza rozprzestrzeni, wybierz Zaktualizuj sklep z Eliksirami zakładkę. Kliknij przycisk Zaktualizuj Skrypt, kliknij menu Przekaż menu i wybierz 2>Zasuj skrypt2>.
W Okienku Assign Script , wpisz UpdateScript i kliknij OK .

Tworzenie klucza API

Idź do strony Creator Hub Open Cloud API Keys i kliknij Utwórz klucz API .
Wypełnij formularz z następującymi informacjami.
- Imię : PotionShop
- API System : Dodaj system instancje wszechświata . Dodaj swoją doświadczenie sklepu z Eliksirami do systemu. Dla Operacji doświadczeń dodaj dostęp czytania i zapisu.
- Zaakceptowane adresy IP : Dodaj 0.0.0.0/0 jako adres IP
- Expiracja : Brak Expiracji
- Kliknij Zapisz i generuj klucz i następnie Skopiuj klucz do schowka.
Wklej klucz API do komórki klucz API (D2) na stronie Intro w Twoim Google Sheet.

Uzyskanie uniwersalnego i miejscowego ID

Idź do strony Kreacje w Centrum Twórcy, połącz się z płytą główną Potion Shop i kliknij menu przepustnicy.
Wybierz Skopiuj ID wszechświata i wklej go do w celu wklejenia ID wszechświata na pasku na zakładce Intro w Twojej książki Google.
Wybierz Skopiuj ID początkowego miejsca i wklej go do Komórki ID miejsca (F2) na stronie Intro swojego Google Sheet.

Aktualizowanie wartości skryptu

W zakładce Aktualizuj sklep z eliksirami na stronie, modyfikuj wszystkie wartości, które lubisz, i kliknij przycisk Aktualizuj skrypt.
Jeśli Google Sheets prosi o autoryzację, kliknij OK i pozwól swojemu kontowi na uruchomienie skryptu.
W Studio, playtest the Potion Shop, aby zobaczyć jakiekolwiek odzwierciedlone zmiany. Z w oknie Explorer możesz również otworzyć skrypt ReplicatedStorage > ItemList , aby inspektować zmiany.