อินสแตนซ์ของเอนจิน

API ของเอนจิน Open Cloud ช่วยให้คุณจัดการวัตถุ Instance ในประสบการณ์ Roblox ของคุณจากเว็บ

ข้อจำกัดเบต้า

API เหล่านี้อยู่ในช่วงเบต้าและมีข้อจำกัดดังต่อไปนี้:

คุณสามารถอ่านและอัปเดตวัตถุ Script, LocalScript และ ModuleScript เท่านั้น
คุณไม่สามารถอัปเดตสคริปต์ที่เปิดอยู่ใน Roblox Studio
คุณไม่สามารถอัปเดตสคริปต์ที่เป็นส่วนหนึ่งของ แพ็คเกจ
คุณสามารถใช้การตรวจสอบสิทธิ์ด้วยคีย์ API เท่านั้น สร้าง API key โดยเพิ่ม universe-place-instances เข้าไปในระบบ API

คุณต้องระบุประสบการณ์ที่คุณต้องการให้คีย์เข้าถึง รวมถึงช่วงสิทธิการอ่านและเขียนที่ต้องการ
คุณต้องมีเซสชัน การทำงานร่วมกัน ที่เปิดใช้งานสำหรับประสบการณ์ที่คุณต้องการเข้าถึง
เนื้อหาของคำขอ เช่น ในการ อัปเดตอินสแตนซ์ จะถูกจำกัดไว้ที่ 200 KB

รายการลูก

รายการลูกทั้งหมดของอินสแตนซ์เฉพาะโดยระบุ ID ของอินสแตนซ์และเรียกใช้วิธี รายการเด็กของอินสแตนซ์

ครั้งแรกที่คุณใช้วิธีเหล่านี้ ให้ระบุ root สำหรับ ID ของอินสแตนซ์ หลังจากที่คุณได้รับรายการเด็กระดับสูงสุดและ ID ของพวกเขา คุณสามารถทำการเรียกเพิ่มเติมเพื่อตรวจสอบอินสแตนซ์ที่อยู่ลึกลงไปในลำดับชั้นของอินสแตนซ์ในสถานที่ของคุณ


import requests

# สร้างที่ https://create.roblox.com/dashboard/credentials
apiKey = "<API_KEY>"
# ค้นหาที่ https://create.roblox.com/dashboard/creations ในเมนูเพิ่มเติมของไพ่ประสบการณ์
universeId = "<UNIVERSE_ID>"
# ค้นหา Start Place ID ที่ https://create.roblox.com/dashboard/creations ในเมนูเพิ่มเติมของไพ่ประสบการณ์
placeId = "<PLACE_ID>"
# ID เริ่มต้นสำหรับรากของโมเดลข้อมูลใดๆ
instanceId = "root"

# ค่าหัวข้อคำขอ
apiKeyHeaderKey = "x-api-key"
# URL จุดสิ้นสุดสำหรับวิธีการแสดงรายการเด็ก
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("ผลลัพธ์จากการดำเนินการ:", response.status_code, response.text)

# วิเคราะห์เส้นทางของวัตถุการดำเนินการเพื่อที่จะได้รับทรัพยากร Instance ต่อไป ดูหัวข้อการ polling เพื่อดูข้อมูลเพิ่มเติม
operationPath = response.json()['path']

แทนที่จะทำการแสดงรายการเด็กเพียงอย่างเดียว การตอบสนองจะรวมถึงวัตถุ Operation ที่มีจุดสิ้นสุดที่แตกต่างกัน Poll จุดสิ้นสุดนี้ เพื่อดึงดูดรายการเด็กที่แท้จริงแบบซิงค์ การซอฟต์โค้ดตัวอย่างที่สมบูรณ์กว่านี้มีลักษณะดังนี้:


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("ผลลัพธ์จากการดำเนินการ:", response.status_code, response.text)
# วิเคราะห์เส้นทางของวัตถุทางการดำเนินการที่จะใช้ในการ polling สำหรับทรัพยากรอินสแตนซ์
operationPath = response.json()['path']
response = PollForResults(operationPath)
print("การตอบสนอง:", response.status_code, response.text)

การตอบสนองสุดท้ายอาจมีหน้าตาประมาณนี้:


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

      ...

    ]
  }
}

คุณสามารถวนซ้ำผ่าน JSON เพื่อค้นหา ID ของอินสแตนซ์เฉพาะ:


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

if replicatedStorageId:
  # ตอนนี้คุณมี ID ของอินสแตนซ์และสามารถดึงข้อมูลหรือปรับปรุงได้
else:
  # ไม่พบชื่อดังกล่าว

สคริปต์มีข้อมูลเพิ่มเติมในวัตถุ Details เช่น ประเภทสคริปต์ แหล่งที่มา และว่าได้ถูกเปิดใช้งานหรือไม่

ดึงอินสแตนซ์

วิธีนี้จะส่งกลับ Instance เพียงหนึ่งรายการ


import requests

# สร้างที่ https://create.roblox.com/dashboard/credentials
apiKey = "<API_KEY>"
# ค้นหาที่ https://create.roblox.com/dashboard/creations ในเมนูเพิ่มเติมของไพ่ประสบการณ์
universeId = "<UNIVERSE_ID>"
# ค้นหา Start Place ID ที่ https://create.roblox.com/dashboard/creations ในเมนูเพิ่มเติมของไพ่ประสบการณ์
placeId = "<PLACE_ID>"
# ID เริ่มต้นสำหรับรากของโมเดลข้อมูลใดๆ
instanceId = "<INSTANCE_ID>"

# ค่าหัวข้อคำขอ
apiKeyHeaderKey = "x-api-key"
# URL จุดสิ้นสุดสำหรับวิธีการดึงอินสแตนซ์
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.status_code, response.text)

# วิเคราะห์เส้นทางของวัตถุทางการดำเนินการจากการตอบสนอง ดูหัวข้อการ polling เพื่อดูข้อมูลเพิ่มเติม
operationPath = response.json()['path']

เช่นเดียวกับวิธีการแสดงรายการเด็กของอินสแตนซ์ การตอบสนองรวมถึงวัตถุ Operation ที่คุณต้องทำPolling เพื่อดึงข้อมูลอินสแตนซ์ที่แท้จริง ดู Polling สำหรับผลลัพธ์ เพื่อดูข้อมูลเพิ่มเติม

อัปเดตอินสแตนซ์

หลังจากที่คุณได้รับ ID ของอินสแตนซ์ที่เหมาะสมแล้ว คุณสามารถอัปเดตได้ ตัวอย่างเช่น Polling สำหรับผลลัพธ์ หลังจากทำการร้องขอการอัปเดตเบื้องต้น


import json
import requests

# สร้างที่ https://create.roblox.com/dashboard/credentials
apiKey = "<API_KEY>"
# ค้นหาที่ https://create.roblox.com/dashboard/creations ในเมนูเพิ่มเติมของไพ่ประสบการณ์
universeId = "<UNIVERSE_ID>"
# ค้นหา Start Place ID ที่ https://create.roblox.com/dashboard/creations ในเมนูเพิ่มเติมของไพ่ประสบการณ์
placeId = "<PLACE_ID>"
instanceId = "<INSTANCE_ID>"
instanceType = ""
propertyName = ""
propertyValue = ""

# ค่าหัวข้อคำขอ
apiKeyHeaderKey = "x-api-key"
contentTypeHeaderKey = "Content-type"
contentTypeHeaderValue = "application/json"
# URL จุดสิ้นสุดสำหรับวิธีการอัปเดตอินสแตนซ์
updateInstanceUrl = "https://apis.roblox.com/cloud/v2/universes/%s/places/%s/instances/%s"
# คีย์ 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.status_code, response.text)

# วิเคราะห์เส้นทางของวัตถุทางการดำเนินการจากการตอบสนอง ดำเนินการPolling สำหรับผลลัพธ์เพื่อตรวจสอบ
operationPath = response.json()['path']

ถ้าคุณได้รับ TypeError ขณะพยายามอัปเดตสคริปต์ ให้ตรวจสอบว่าสคริปต์ไม่ได้เปิดอยู่ใน Roblox Studio หากเปิดอยู่ ให้ปิดแท็บ Script Editor มันจะช่วยให้คุณตรวจสอบผลลัพธ์เพิ่มเติมใน Studio สําหรับข้อผิดพลาด เช่น Engine_OC_API: Processing Error - Live scripting session is active

Poll สำหรับผลลัพธ์

วิธีการ Instance ทุกวิธีการปัจจุบันจะส่งคืนวัตถุ Operation แทนทรัพยากรที่คุณร้องขอ วัตถุนี้ช่วยให้คุณสามารถดำเนินการต้นฉบับแบบอะซิงโครนัส ใช้เส้นทางของวัตถุ Operation (ที่รวมอยู่ในการตอบสนองเริ่มต้น) เพื่อทำPoll สำหรับเมื่อทรัพยากรพร้อม

คุณสามารถใช้กลยุทธ์การ polling ที่หลากหลาย เช่น การใช้การลดลงเชิงอัตราทวี หรือการรอแบบคงที่ระหว่างคำขอ ตัวอย่างต่อไปนี้จะทำPollทุกๆห้าคุณวินาทีสูงสุด 10 ครั้ง


import requests
import time

# สร้างที่ https://create.roblox.com/dashboard/credentials
apiKey = "<API_KEY>"
# ใช้เส้นทางของการดำเนินการจากคำขอเริ่มต้นของคุณ
# มีรูปแบบเป็น "universes/<UNIVERSE_ID>/places/<PLACE_ID>/instances/<INSTANCE_ID>/operations/<OPERATION_ID>"
operationPath = "<OPERATION_PATH>"

# ค่าคงที่การ polling
numberOfRetries = 10
retryPollingCadence = 5

# ค่าหัวข้อคำขอ
apiKeyHeaderKey = "x-api-key"
# URL จุดสิ้นสุดสำหรับการทำPolling ของการดำเนินการที่ใช้เวลานาน
getOperationUrl = "https://apis.roblox.com/cloud/v2/%s"
# คีย์ 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.status_code, response.text)

เดโมร้านขายยา

เดโมของ Google Sheets ร้านขายยาแสดงให้คุณเห็นวิธีการอัปเดตสคริปต์ของประสบการณ์จากเว็บ เดโมประกอบไปด้วยสิ่งต่อไปนี้:

สถานที่ที่ไม่ถูกล็อคซึ่งมี UI ตัวอย่างที่แสดงให้เห็นถึงยาและราคา
ไฟล์ .ods ที่คุณนำเข้าสู่ Google Sheets สเปรดชีตนี้ช่วยให้คุณสามารถระบุและอัปเดตค่าต่างๆ สำหรับคุณสมัติในประสบการณ์
โค้ดสำหรับ Google Apps Script ที่อ่านข้อมูลจาก Google Sheet และอัปเดต ReplicatedStorage > ItemList สคริปต์ในประสบการณ์ร้านขายยา

ตั้งค่าเดโม

ไปที่ เดโมร้านขายยา หน้า Discover คลิกที่เมนูเพิ่มเติม จากนั้น แก้ไขใน Studio Studio จะเปิดด้วยสำเนาของสถานที่
คลิก ไฟล์ → บันทึกไปยัง Roblox และกรอกข้อมูลที่จำเป็นเพื่อ บันทึกเดโมร้านขายยาเป็นสถานที่เริ่มต้นสำหรับประสบการณ์ของคุณ ทดสอบ ประสบการณ์ คุณควรเห็น UI ของเดโมร้านขายยา บันทึกชื่อ ราคา และสีของยา คุณจะเปลี่ยนพวกเขาในภายหลังด้วย Open Cloud!

ตั้งค่าแผ่นงาน

ดาวน์โหลด ไฟล์สเปรดชีตร้านขายยา
ไปที่ Google Sheets และคลิก แผ่นงานเปล่า
ในแผ่นงานที่ปรากฏ คลิก ไฟล์ > นำเข้า และคลิกแท็บ อัปโหลด
ลากไฟล์สเปรดชีต ร้านขายยาเข้าไปในหน้าต่างอัปโหลด
เลือก แทนที่สเปรดชีต และแล้ว นำเข้าข้อมูล
ในแท็บ AppScript ของแผ่นงาน คัดลอกโค้ดในเซลล์ A1
คลิกเมนู ส่วนขยาย > Apps Script และวางโค้ดลงใน ไฟล์ Code.gs จากนั้นบันทึกโปรเจ็กต์
กลับไปที่สเปรดชีต เลือกแท็บ อัปเดตร้านขายยา คลิกปุ่ม อัปเดตสคริปต์ คลิกเมนูเพิ่มเติม และเลือก กำหนดสคริปต์
ในหน้าต่าง กำหนดสคริปต์ ให้ป้อน UpdateScript และคลิก ตกลง

สร้างคีย์ API

ไปที่หน้า Creator Hub Open Cloud API Keys และคลิก สร้างคีย์ API
กรอกแบบฟอร์มด้วยข้อมูลดังต่อไปนี้
- ชื่อ: PotionShop
- ระบบ API: เพิ่มระบบ API universe-place-instances เพิ่มประสบการณ์ร้านขายยาของคุณในระบบ สำหรับ ประสบการณ์การดำเนินการ ให้เพิ่มการเข้าถึงการอ่านและเขียน
- ที่อยู่ IP ที่ยอมรับได้: เพิ่ม 0.0.0.0/0 เป็นที่อยู่ IP
- วันหมดอายุ: ไม่มีวันหมดอายุ
- คลิก บันทึก & สร้างคีย์ และจากนั้น คัดลอกคีย์ไปยังคลิปบอร์ด
วางคีย์ API ลงในเซลล์คีย์ API (D2) บนแท็บ Intro ของ Google Sheet ของคุณ

รับ ID ของจักรวาลและสถานที่

ไปที่หน้า Creator Hub Creations วางเมาส์เหนือไพ่ของประสบการณ์ร้านขายยา และคลิกที่เมนูเพิ่มเติม
เลือก คัดลอก ID จักรวาล และวางลงในเซลล์ ID จักรวาล (E2) บนแท็บ Intro ของ Google Sheet ของคุณ
เลือก คัดลอก ID สถานที่เริ่มต้น และวางลงในเซลล์ ID สถานที่ (F2) บนแท็บ Intro ของ Google Sheet ของคุณ

อัปเดตค่าของสคริปต์

ในแท็บ อัปเดตร้านขายยา ของแผ่นงาน ปรับเปลี่ยนค่าต่างๆ ที่คุณต้องการและคลิกปุ่ม อัปเดตสคริปต์
หาก Google Sheets ขอให้คุณอนุญาต ให้คลิก ตกลง และอนุญาตให้บัญชีของคุณเริ่มรันสคริปต์
ใน Studio ทดลองเล่นร้านขายยาเพื่อดูการเปลี่ยนแปลงที่สะท้อนอยู่ จากหน้าต่าง Explorer คุณยังสามารถเปิดสคริปต์ ReplicatedStorage > ItemList เพื่อสำรวจการเปลี่ยนแปลงได้

ในหน้านี้