Instansi mesin

API Terbuka Cloud Mesin memungkinkan Anda mengelola objek Instance di pengalaman Roblox Anda dari web.

Keterbatasan beta

API ini saat ini dalam beta dan memiliki batasan berikut:

Anda hanya dapat membaca dan memperbarui Script , LocalScript , dan ModuleScript objek.
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 instansi tempat alam semesta ditambahkan sebagai sistem API.

Anda harus menentukan pengalaman yang ingin Anda berikan kunci akses ke serta scope baca dan tulis yang diinginkan.
Anda harus memiliki sesi kolaboratif untuk pengalaman yang ingin Anda akses.
Permintaan tubuh, seperti untuk Memperbarui Instansi, dibatasi hingga 200 KB.

Daftar anak-anak

Daftar semua anak dari instansi tertentu dengan menyediakan ID instansi dan memanggil metode Daftar Anak Instansi.

Pertama kali Anda menggunakan metode ini, spesifikasikan root untuk ID instansi.Setelah Anda menerima daftar anak tingkat atas dan ID mereka, Anda dapat melakukan panggilan tambahan untuk menemukan instansi yang lebih dalam dalam hierarki instans tempat Anda.


import requests

# Hasilkan di https://create.roblox.com/ashboard/credentials
apiKey = "<API_KEY>"
# Temukan di https://create.roblox.com/dashboard/creations di menu overflow pada ubin pengalaman
universeId = "<UNIVERSE_ID>"
# Temukan ID Tempat Mulai di https://create.roblox.com/dashboard/creations di menu overflow pada ubin pengalaman
placeId = "<PLACE_ID>"
# ID default untuk akar model data tempat mana pun
instanceId = "root"

# Permintaan kepala
apiKeyHeaderKey = "x-api-key"
# URL akhir untuk Metode Anak-anak Daftar
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)

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

Daripada hanya daftar anak-anak, respons termasuk objek Operation dengan endpoint yang berbeda. Polluj ujung ini untuk mengambil daftar anak-anak yang sebenarnya secara asinkron.Sampel kode yang lebih lengkap terlihat 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("Operation Results:", response.status_code, response.text)
# Analisis jalur objek Operasi untuk digunakan dalam pemungutan suara untuk sumber daya instansi.
operationPath = response.json()['path']
response = PollForResults(operationPath)
print("Response:", response.status_code, response.text)

Tanggapan terakhir 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 mengulangi atas JSON untuk menemukan ID instans khusus:


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

if replicatedStorageId:
  # Sekarang Anda memiliki ID instansi dan dapat mendapatkan atau memperbaruinya.
else:
  # The name wasn't found.

Skrip berisi beberapa informasi tambahan di objek Details, seperti jenis ketik, sumber, dan apakah mereka diaktifkan.

Dapatkan kejadian

Metode ini mengembalikan satu Instance.


import requests

# Hasilkan di https://create.roblox.com/ashboard/credentials
apiKey = "<API_KEY>"
# Temukan di https://create.roblox.com/dashboard/creations di menu overflow pada ubin pengalaman
universeId = "<UNIVERSE_ID>"
# Temukan ID Tempat Mulai di https://create.roblox.com/dashboard/creations di menu overflow pada ubin pengalaman
placeId = "<PLACE_ID>"
# ID default untuk akar model data tempat mana pun
instanceId = "<INSTANCE_ID>"

# Permintaan kepala
apiKeyHeaderKey = "x-api-key"
# URL akhir 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("Response:", response.status_code, response.text)

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

Sama seperti metode Anak Instan Daftar, respons termasuk objek Operation yang Anda polling untuk mengambil kejadiansebenarnya.Lihat Poll untuk hasil untuk informasi lebih lanjut.

Perbarui instansi

Setelah Anda mendapatkan ID instans yang tepat, Anda dapat memperbaruinya. Poll untuk hasil setelah membuat permintaan pembaruan awal.


import json
import requests

# Hasilkan di https://create.roblox.com/ashboard/credentials
apiKey = "<API_KEY>"
# Temukan di https://create.roblox.com/dashboard/creations di menu overflow pada ubin pengalaman
universeId = "<UNIVERSE_ID>"
# Temukan ID Tempat Mulai di https://create.roblox.com/dashboard/creations di menu overflow pada ubin pengalaman
placeId = "<PLACE_ID>"
instanceId = "<INSTANCE_ID>"
instanceType = ""
propertyName = ""
propertyValue = ""

# Permintaan kepala
apiKeyHeaderKey = "x-api-key"
contentTypeHeaderKey = "Content-type"
contentTypeHeaderValue = "application/json"
# URL akhir untuk metode Update Instance
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("Response:", response.status_code, response.text)

# Analisis jalur objek Operasi dari respons. Poll untuk hasil yang dilakukan
# update.
operationPath = response.json()['path']

Jika Anda menerima TypeError saat mencoba memperbarui skrip, verifikasikan bahwa skrip tidak terbuka di Roblox Studio.Jika demikian, 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 Instance saat ini kembali objek Operation alih-alih sumber daya yang Anda minta.Objek ini memungkinkan Anda melakukan operasi asli secara tidak sinkron.Gunakan jalur objek Operation untuk mengumpulkan suara ketika sumber daya siap.

Anda dapat menggunakan berbagai strategi pemungutan suara, seperti menggunakan penundaan eksponensial atau penundaan tetap di antara permintaan.Contoh berikut memilih setiap lima detik, hingga 10 kali.


import requests
import time

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

# Konstan pemilihan
numberOfRetries = 10
retryPollingCadence = 5

# Permintaan kepala
apiKeyHeaderKey = "x-api-key"
# URL akhir untuk polling operasi 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("Response:", response.status_code, response.text)

Demo Toko Ramuan

Demo Toko Ramuan Google Sheets menunjukkan Anda untuk memperbarui skrip pengalaman dari web. Demo terdiri dari hal mengikuti:

Tempat yang tidak disalin dengan UI m mock yang menampilkan berbagai ramuan dan harganya.
Sebuah file .ods yang Anda impor ke Google Sheets. Spreadsheet ini memungkinkan Anda untuk menentukan dan memperbarui nilai untuk properti dalam pengalaman.
Kode untuk Skrip Google Apps yang membaca data dari Google Sheet dan memperbarui skrip ReplicatedStorage > ItemList di pengalaman Toko Ramuan.

Menyiapkan demo

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

Tetapkan lembar

Unduh file spreadsheet Toko Ramuan.
Pergi ke Google Sheets dan klik Spreadsheet Kosong .
Di lembar yang muncul, klik File > Impor , dan klik tab Upload .
Seret file spreadsheet Toko Ramuan ke jendela unggahan.
Pilih Ganti spreadsheet lalu Impor data .
Di tab AppScript dari lembar, salin kode di sel A1.
Klik menu Ekstensi > Skrip Aplikasi dan tempelkan kode ke file Code.gs. Kemudian simpan proyek.
Kembali di spreadsheet, pilih tab Toko Ramuan Pembaruan .Klik tombol Update Skrip , klik menu overflow, dan pilih Aktifkan skrip .
Di jendela Menugaskan skrip , masukkan UpdateScript dan klik OK .

Buat kunci API

Pergi ke halaman Kunci API Hub Terbuka Cloud Pencipta dan klik Buat Kunci API .
Isi formulir dengan informasi berikut.
- Nama : PotionShop
- Sistem API : Tambahkan sistem API univers-place-instances .Tambahkan pengalaman Toko Ramuan Anda ke 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 .
Tempel kunci API ke sel Kunci API (D2) di tab Intro dari Google Sheet Anda.

Dapatkan alam semesta dan ID tempat

Pergi ke halaman Kreasi Pusat Pencipta, hover di atas ubin pengalaman Toko Ramuan, dan klik menu overflow.
Pilih Salin ID Univers dan tempelkan ke sel ID Univers (E2) di tab Intro dari Google Sheet Anda.
Pilih Salin ID Tempat Mulai dan tempelkan ke sel ID Tempat (F2) di tab Intro dari Google Sheet Anda.

Perbarui nilai skrip

Di tab Toko Ramuan Pembaruan dari lembar, modifikasi nilai apa pun yang Anda inginkan dan klik tombol Perbarui Skrip .
Jika Google Sheets meminta Anda untuk otorisasi, klik OK dan izinkan akun Anda menjalankan skrip.
Di Studio, uji coba toko ramuan untuk melihat perubahan yang tercermin.Dari jendela Explorer , Anda juga dapat membuka skrip ReplicatedStorage > ItemList untuk memeriksa perubahan.

Di halaman ini