Instansi Engine | Dokumentasi - Pusat Kreator Roblox

API Open Cloud Engine memungkinkan Anda mengelola objek Instance dalam game Roblox Anda dari web.

Pembatasan Beta

API ini saat ini dalam versi beta dan memiliki pembatasan berikut:

Anda hanya dapat membaca dan memperbarui objek Script, LocalScript, dan ModuleScript.
Anda tidak dapat memperbarui skrip yang saat ini terbuka di Roblox Studio.
Anda tidak dapat memperbarui skrip yang merupakan bagian dari paket.
Anda hanya dapat menggunakan otentikasi kunci API. Buat kunci API dengan universe-place-instances ditambahkan sebagai sistem API.

Anda harus menentukan game yang ingin Anda beri akses dengan kunci tersebut serta ruang lingkup izin baca dan tulis yang diinginkan.
Anda harus memiliki sesi kolaboratif yang diaktifkan untuk game yang ingin Anda akses.
Badan permintaan, seperti untuk Perbarui Instansi, dibatasi hingga 200 KB.

Daftar anak

Daftar semua anak dari instansi tertentu dengan menentukan ID instansi dan memanggil metode List Instance Children.

Saat pertama kali Anda menggunakan metode ini, tetapkan root untuk ID instansi. Setelah mendapatkan daftar anak tingkat atas dan ID-nya, Anda dapat melakukan pemanggilan tambahan untuk menemukan instansi lebih dalam dalam hierarki instansi tempat Anda.


import requests

# Dihasilkan di https://create.roblox.com/dashboard/credentials
apiKey = "<API_KEY>"
# Temukan di https://create.roblox.com/dashboard/creations dalam menu overflow tile game
universeId = "<UNIVERSE_ID>"
# Temukan ID Tempat Awal di https://create.roblox.com/dashboard/creations dalam menu overflow tile game
placeId = "<PLACE_ID>"
# ID default untuk akar model data tempat mana pun
instanceId = "root"

# Header permintaan
apiKeyHeaderKey = "x-api-key"
# URL Endpoint untuk metode Daftar Anak
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("Hasil Operasi:", response.status_code, response.text)

# Parse jalur objek Operasi untuk kemudian mendapatkan sumber daya Instance. Lihat bagian Polling for Results untuk informasi lebih lanjut.
operationPath = response.json()['path']

Alih-alih hanya mencantumkan anak-anak, respons menyertakan objek Operation dengan endpoint yang berbeda. Polling endpoint ini untuk secara asinkron mendapatkan daftar anak yang sebenarnya. Contoh kode yang lebih lengkap tampak seperti ini:


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("Hasil Operasi:", response.status_code, response.text)
# Parse jalur objek Operasi untuk digunakan dalam polling untuk sumber daya instance.
operationPath = response.json()['path']
response = PollForResults(operationPath)
print("Respons:", response.status_code, response.text)

Respons akhir mungkin terlihat seperti ini:


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

      ...

    ]
  }
}

Anda kemudian dapat mengiterasi JSON untuk menemukan ID instansi tertentu:


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

if replicatedStorageId:
  # Anda sekarang memiliki ID instansi dan dapat mengambil atau memperbaruinya.
else:
  # Nama tidak ditemukan.

Skrip berisi informasi tambahan dalam objek Details, seperti jenis skrip, sumber, dan apakah skrip tersebut diaktifkan.

Dapatkan instansi

Metode ini mengembalikan satu Instansi.


import requests

# Dihasilkan di https://create.roblox.com/dashboard/credentials
apiKey = "<API_KEY>"
# Temukan di https://create.roblox.com/dashboard/creations dalam menu overflow tile game
universeId = "<UNIVERSE_ID>"
# Temukan ID Tempat Awal di https://create.roblox.com/dashboard/creations dalam menu overflow tile game
placeId = "<PLACE_ID>"
# ID default untuk akar model data tempat mana pun
instanceId = "<INSTANCE_ID>"

# Header permintaan
apiKeyHeaderKey = "x-api-key"
# URL Endpoint untuk metode Dapatkan Instansi
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("Respons:", response.status_code, response.text)

# Parse jalur objek Operasi dari respons. Lihat bagian Polling for Results untuk informasi lebih lanjut.
operationPath = response.json()['path']

Sama seperti metode Daftar Anak Instansi, respons menyertakan objek Operation yang Anda polling untuk mendapatkan instansi yang sebenarnya. Lihat Polling untuk hasil untuk informasi lebih lanjut.

Perbarui instansi

Setelah Anda mendapatkan ID instansi yang sesuai, Anda dapat memperbaruinya. Lakukan polling untuk hasil setelah membuat permintaan perbarui awal.


import json
import requests

# Dihasilkan di https://create.roblox.com/dashboard/credentials
apiKey = "<API_KEY>"
# Temukan di https://create.roblox.com/dashboard/creations dalam menu overflow tile game
universeId = "<UNIVERSE_ID>"
# Temukan ID Tempat Awal di https://create.roblox.com/dashboard/creations dalam menu overflow tile game
placeId = "<PLACE_ID>"
instanceId = "<INSTANCE_ID>"
instanceType = ""
propertyName = ""
propertyValue = ""

# Header permintaan
apiKeyHeaderKey = "x-api-key"
contentTypeHeaderKey = "Content-type"
contentTypeHeaderValue = "application/json"
# URL Endpoint untuk metode Perbarui Instansi
updateInstanceUrl = "https://apis.roblox.com/cloud/v2/universes/%s/places/%s/instances/%s"
# Kunci 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("Respons:", response.status_code, response.text)

# Parse jalur objek Operasi dari respons. Polling untuk hasil untuk melakukan
# pembaruan.
operationPath = response.json()['path']

Jika Anda menerima TypeError saat mencoba memperbarui skrip, pastikan bahwa skrip tidak terbuka di Roblox Studio. Jika terbuka, tutup tab Editor Skripnya. Anda juga dapat memeriksa output Studio untuk kesalahan tambahan, seperti Engine_OC_API: Processing Error - Live scripting session is active.

Polling untuk hasil

Semua metode Instansi saat ini mengembalikan objek Operation alih-alih sumber daya yang Anda minta. Objek ini memungkinkan Anda secara asinkron melakukan operasi asli. Gunakan jalur objek Operation (yang disertakan dalam respons awal) untuk polling ketika sumber daya siap.

Anda dapat menggunakan berbagai strategi polling, seperti menggunakan exponential backoff atau penundaan tetap di antara permintaan. Contoh berikut melakukan polling setiap lima detik, hingga 10 kali.


import requests
import time

# Dihasilkan di https://create.roblox.com/dashboard/credentials
apiKey = "<API_KEY>"
# Gunakan jalur Operasi dari permintaan awal Anda
# Mengambil bentuk "universes/<UNIVERSE_ID>/places/<PLACE_ID>/instances/<INSTANCE_ID>/operations/<OPERATION_ID>"
operationPath = "<OPERATION_PATH>"

# Konstanta polling
numberOfRetries = 10
retryPollingCadence = 5

# Header permintaan
apiKeyHeaderKey = "x-api-key"
# URL Endpoint untuk polling operasi yang berjalan lama
getOperationUrl = "https://apis.roblox.com/cloud/v2/%s"
# Kunci 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("Respons:", response.status_code, response.text)

Demo Toko Ramuan

Demo Google Sheets Toko Ramuan menunjukkan bagaimana Anda memperbarui skrip permainan dari web. Demo ini terdiri dari hal-hal berikut:

Sebuah tempat yang tidak terkunci dengan UI tiruan yang menampilkan berbagai ramuan dan harganya.
Sebuah file .ods yang Anda impor ke Google Sheets. Spreadsheet ini memungkinkan Anda menentukan dan memperbarui nilai untuk properti dalam game.
Kode untuk Google Apps Script yang membaca data dari Google Sheet dan memperbarui skrip ReplicatedStorage > ItemList dalam game Toko Ramuan.

Siapkan demo

Pergi ke halaman Demo Toko Ramuan Discover. Klik pada menu overflow, lalu Edit di Studio. Studio akan terbuka dengan salinan tempat tersebut.
Klik File → Simpan ke Roblox dan isi informasi yang diperlukan untuk menyimpan Demo Toko Ramuan sebagai tempat default untuk game Anda. Uji game tersebut. Anda harus melihat UI untuk Demo Toko Ramuan. Catat nama, biaya, dan warna dari ramuan tersebut. Anda akan mengubahnya nanti menggunakan Open Cloud!

Siapkan lembar

Unduh file spreadsheet Toko Ramuan.
Pergi ke Google Sheets dan klik Spreadsheet Kosong.
Di lembar yang muncul, klik File > Impor, dan klik tab Unggah.
Seret file spreadsheet Toko Ramuan ke jendela unggah.
Pilih Ganti spreadsheet dan kemudian Impor data.
Di tab AppScript dari lembar, salin kode di sel A1.
Klik menu Extensions > Apps Script dan tempelkan kode ke dalam file Code.gs. Kemudian simpan proyek tersebut.
Kembali ke spreadsheet, pilih tab Perbarui Toko Ramuan. Klik tombol Perbarui Skrip, klik menu overflow, dan pilih Tugaskan skrip.
Di jendela Tugaskan skrip, masukkan UpdateScript dan klik OK.

Buat kunci API

Pergi ke halaman Kunci API Open Cloud Creator Hub dan klik Buat Kunci API.
Isi formulir dengan informasi berikut.
- Nama: PotionShop
- Sistem API: Tambahkan sistem API universe-place-instances. Tambahkan game Toko Ramuan Anda ke dalam sistem. Untuk Operasi Pengalaman, tambahkan akses baca dan tulis.
- Alamat IP yang Diterima: Tambahkan 0.0.0.0/0 sebagai Alamat IP
- Kedaluwarsa: Tidak ada Kedaluwarsa
- Klik Simpan & Hasilkan Kunci dan kemudian Salin Kunci ke Clipboard.
Tempelkan kunci API ke sel Kunci API (D2) di tab Intro spreadsheet Google Anda.

Peroleh ID universe dan place

Pergi ke halaman Kreasi Creator Hub, arahkan mouse ke tile game Toko Ramuan, dan klik menu overflow.
Pilih Salin ID Universe dan tempelkan ke sel ID Universe (E2) di tab Intro spreadsheet Google Anda.
Pilih Salin ID Tempat Awal dan tempelkan ke sel ID Tempat (F2) di tab Intro spreadsheet Google Anda.

Perbarui nilai skrip

Di tab Perbarui Toko Ramuan di lembar, ubah nilai yang Anda inginkan dan klik tombol Perbarui Skrip.
Jika Google Sheets meminta Anda untuk otorisasi, klik OK dan izinkan akun Anda untuk menjalankan skrip tersebut.
Di Studio, lakukan pengujian permainan di Toko Ramuan untuk melihat perubahan yang tercermin. Dari jendela Explorer, Anda juga dapat membuka skrip ReplicatedStorage > ItemList untuk memeriksa perubahan tersebut.