Các ví dụ động cơ

Các API Mở đám mây Động cơ cho phép bạn quản lý Instance đối tượng trong trải nghiệm Roblox của bạn từ web.

Hạn chế beta

Các API này hiện đang ở trong giai đoạn thử nghiệm và có các hạn chế sau:

Bạn chỉ có thể đọc và cập nhật Script , LocalScript , và ModuleScript đối tượng.
Bạn không thể cập nhật các kịch bản hiện đang mở trong Roblox Studio.
Bạn không thể cập nhật các kịch bản làm phần của một gói hàng.
Bạn chỉ có thể sử dụng xác minh chìa khóa API. Tạo một chìa khóa API với univers-place-instances được thêm làm hệ thống API.

Bạn phải xác định các trải nghiệm bạn muốn chìa khóa có quyền truy cập cũng như phạm vi đọc và ghi mong muốn.
Bạn phải có một phiên hợp tác được bật cho trải nghiệm mà bạn muốn truy cập.
Các thân yêu cầu, chẳng hạn như để Cập nhật Instances, được giới hạn ở 200 KB.

Danh sách con cái

Liệt kê tất cả các con của một ví dụ cụ thể bằng cách xác định một ID ví dụ và gọi phương pháp Danh sách con của ví dụ.

Lần đầu tiên bạn sử dụng các phương pháp này, hãy đặt root cho ID của instance.Sau khi nhận được danh sách các con trên cấp cao và ID của chúng, bạn có thể thực hiện thêm các cuộc gọi để tìm các ví dụ sâu hơn trong hệ thống phân cấp của địa điểmcủa bạn.


import requests

# Tạo tại https://create.roblox.com/ashboard/credentials
apiKey = "<API_KEY>"
# Tìm tại https://create.roblox.com/ashboard/creations trong menu tràn của một ô trải nghiệm
universeId = "<UNIVERSE_ID>"
# Tìm ID địa điểm bắt đầu tại https://create.roblox.com/ashboard/creations trong menu tràn ngập của một ô trải nghiệm
placeId = "<PLACE_ID>"
# ID mặc định cho gốc của bất kỳ mô hình dữ liệu nào của địa điểmnào
instanceId = "root"

# Yêu cầu tiêu đề
apiKeyHeaderKey = "x-api-key"
# URL cuối cùng cho phương pháp 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)

# Phân tích con đường của đối tượng Operation để sau đó có được tài nguyên Instances. Xem phần Phát hiện kết quả để biết thêm thông tin.
operationPath = response.json()['path']

Thay vì chỉ liệt kê các con, phản hồi bao gồm một đối tượng Operation với một điểm cuối khác. Khảo sát điểm cuối này để lấy lại danh sách con thực sự một cách không đồng bộMột ví dụ mã hoàn chỉnh hơn trông như thế này:


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)
# Phân tích con đường của đối tượng hoạt động để sử dụng trong khảo sát cho tài nguyên của instance.
operationPath = response.json()['path']
response = PollForResults(operationPath)
print("Response:", response.status_code, response.text)

Phản hồi cuối cùng có thể trông giống như thế này:


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

      ...

    ]
  }
}

Sau đó, bạn có thể lặp lại trên JSON để tìm một ID thùng đặc biệt:


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

if replicatedStorageId:
  # Bây giờ bạn có một ID thời gian và có thể nhận hoặc cập nhật nó.
else:
  # The name wasn't found.

Các tập lệnh chứa một số thông tin bổ sung trong đối tượng Details, chẳng hạn như loại tập đánh máy, nguồn và xem chúng có được bật hay không.

Nhận một ví ví dụ / trường hợp

Phương pháp này trả về một Instances duy nhất.


import requests

# Tạo tại https://create.roblox.com/ashboard/credentials
apiKey = "<API_KEY>"
# Tìm tại https://create.roblox.com/ashboard/creations trong menu tràn của một ô trải nghiệm
universeId = "<UNIVERSE_ID>"
# Tìm ID địa điểm bắt đầu tại https://create.roblox.com/ashboard/creations trong menu tràn ngập của một ô trải nghiệm
placeId = "<PLACE_ID>"
# ID mặc định cho gốc của bất kỳ mô hình dữ liệu nào của địa điểmnào
instanceId = "<INSTANCE_ID>"

# Yêu cầu tiêu đề
apiKeyHeaderKey = "x-api-key"
# URL cuối cùng cho phương thức Get Instance
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)

# Phân tích con đường của đối tượng hoạt động từ phản hồi. Xem phần Phát hiện kết quả để biết thêm thông tin.
operationPath = response.json()['path']

Tương tự như phương thức List Instance Children, phản hồi bao gồm một đối tượng Operation mà bạn thu thập để lấy lại ví dụ / trường hợpthực sự.Xem Khảo sát kết quả để biết thêm thông tin.

Cập nhật các ví dụ

Sau khi bạn có được ID thích hợp của ví dụ, bạn có thể cập nhật nó. Thăm dò kết quả sau khi thực hiện yêu cầu cập nhật ban đầu.


import json
import requests

# Tạo tại https://create.roblox.com/ashboard/credentials
apiKey = "<API_KEY>"
# Tìm tại https://create.roblox.com/ashboard/creations trong menu tràn của một ô trải nghiệm
universeId = "<UNIVERSE_ID>"
# Tìm ID địa điểm bắt đầu tại https://create.roblox.com/ashboard/creations trong menu tràn ngập của một ô trải nghiệm
placeId = "<PLACE_ID>"
instanceId = "<INSTANCE_ID>"
instanceType = ""
propertyName = ""
propertyValue = ""

# Yêu cầu tiêu đề
apiKeyHeaderKey = "x-api-key"
contentTypeHeaderKey = "Content-type"
contentTypeHeaderValue = "application/json"
# URL cuối cùng cho phương thức Cập nhật Instances
updateInstanceUrl = "https://apis.roblox.com/cloud/v2/universes/%s/places/%s/instances/%s"
# Khóa 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)

# Phân tích con đường của đối tượng hoạt động từ phản hồi. Bỏ phiếu cho kết quả để thực hiện
# cập nhật.
operationPath = response.json()['path']

Nếu bạn nhận được một TypeError khi cố gắng cập nhật một kịch bản, hãy xác minh rằng kịch bản không được mở trong Roblox Studio.Nếu có, hãy đóng trang tab Trình soạn thảo Scrip của nó.Bạn cũng có thể kiểm tra sản phẩm Studio cho các lỗi bổ sung, chẳng hạn như Engine_OC_API: Processing Error - Live scripting session is active .

Khảo sát kết quả

Tất cả các phương pháp hiện tại Cơ sở dữ liệu đều trả về một đối tượng Operation thay vì tài nguyên bạn yêu cầu.Vật này cho phép bạn thực hiện hoạt động gốc một cách không đồng bộ.Sử dụng con đường của đối tượng Operation (được bao gồm trong phản hồi ban đầu) để thăm dò khi nào tài nguyên sẵn sàng.

Bạn có thể sử dụng một loạt các chiến lược khảo sát, chẳng hạn như sử dụng sự trì hoãn exponential hoặc một thời gian cố định giữa các yêu cầu.Các cuộc khảo sát sau đây thăm dò mỗi 5 giây, lên đến 10 lần.


import requests
import time

# Tạo tại https://create.roblox.com/ashboard/credentials
apiKey = "<API_KEY>"
# Sử dụng con đường hoạt động từ yêu cầu ban đầu của bạn
# Mang dạng "universes/<UNIVERSE_ID>/places/<PLACE_ID>/instances/<INSTANCE_ID>/operations/<OPERATION_ID>"
operationPath = "<OPERATION_PATH>"

# Biến số khảo sát
numberOfRetries = 10
retryPollingCadence = 5

# Yêu cầu tiêu đề
apiKeyHeaderKey = "x-api-key"
# URL điểm cuối cho cuộc khảo sát hoạt động dài chạy
getOperationUrl = "https://apis.roblox.com/cloud/v2/%s"
# Khóa 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)

Thử nghiệm cửa hàng thuốc

Bản trình bày Google Sheets của Cửa hàng thuốc cho thấy bạn cập nhật kịch bản của trải nghiệm từ web. Bản trình bày bao gồm các thành phần theo dõi:

Một nơi không bị khóa với một giao diện người dùng giả mạo hiển thị các loại thuốc và giá của chúng.
Một tập tin .ods mà bạn nhập vào Google Sheets. Bảng tính này cho phép bạn xác định và cập nhật các giá trị cho các thuộc tính trong trải nghiệm.
Mã cho một Tập lệnh Google Apps đọc dữ liệu từ Google Sheet và cập nhật kịch bản ReplicatedStorage > ItemList trong trải nghiệm Cửa hàng Potion.

Thiết lập demo

Đi đến trang Demo Cửa hàng Thuốc Khám phá.Nhấp vào menu tràn, sau đó Chỉnh sửa trong Studio .Studio mở với một bản sao của địa điểm.
Nhấp vào Tập tin → Lưu vào Roblox và hoàn thành các thông tin cần thiết để lưu Cửa hàng Thử nghiệm Thuốc là nơi mặc định cho trải nghiệm của bạn.Thử nghiệm trải nghiệm.Bạn nên thấy giao diện người dùng cho Demo Cửa hàng Thuốc.Ghi lại tên, chi phí và màu sắc của các loại thuốc.Bạn sẽ thay đổi chúng sau này bằng cách sử dụng Open Cloud!

Thiết lập trang tời

Tải xuống tệp bảng tính Cửa Hàng Thuốc.
Đi đến Google Sheets và nhấp vào Bảng tính trống .
Trong trang tờ xuất hiện, nhấp vào Tập tin > Nhập , và nhấp vào tab Tải lên .
Kéo tệp bảng tính Cửa hàng Thuốc vào cửa sổ tải lên.
Chọn Thay thế bảng tính và sau đó Nhập dữ liệu .
Trong tab AppScript của tờ, sao chép mã trong ô A1.
Nhấp vào menu Mở rộng > Tập lệnh ứng dụng và dán mã vào tập tin Code.gs. Sau đó lưu dự án.
Trở lại trang tính, chọn tab Cửa hàng Thuốc cập nhật .Nhấp vào nút Cập nhật kịch bản , nhấp vào menu tràn, và chọn Gán kịch bản .
Trong cửa sổ Gán kịch bản , nhập UpdateScript và nhấp vào Được chấp nhận .

Tạo một chìa khóa API

Đi đến trang Tạo Trung tâm Mở API Cloud API và nhấp vào Tạo Chìa khóa API .
Hoàn thành biểu mẫu với thông tin sau.
- Tên : Cửa hàng Potion
- Hệ thống API : Thêm hệ thống API univers-place-instances .Thêm trải nghiệm Cửa hàng Thuốc của bạn vào hệ thống.Đối với Hoạt động kinh nghiệm , thêm quyền truy cập đọc và viết.
- Địa chỉ IP được chấp nhận : Thêm 0.0.0.0/0 như một địa chỉ IP
- Hết hạn : Không có hạn hạn
- Nhấp vào Lưu và tạo chìa khóa và sau đó Sao chép chìa khóa vào khay nhớ .
Sao chép chìa khóa API vào ô Chìa khóa API (D2) trên tab Intro của Google Sheet của bạn.

Nhận được vũ trụ và ID nơi

Đi đến trang Sáng tạo Trung tâm Nhà sáng lập, di chuột qua tiếp trải nghiệm của Cửa hàng Thuốc, và nhấp vào menu bị tràn.
Chọn Sao chép ID Vũ trụ và dán vào ô ID Vũ trụ (E2) trên tab Intro của Google Sheet của bạn.
Chọn Sao chép ID điểm bắt đầu và dán vào ô ID địa điểm (F2) trong tab Intro của Google Sheet của bạn.

Cập nhật các giá trị kịch bản

Trong tab Cửa hàng Thuốc cập nhật của trang tờ, chỉnh sửa bất kỳ giá trị nào bạn muốn và nhấp vào nút Cập nhật Tập lệnh .
Nếu Google Sheets yêu cầu bạn xác nhận, hãy nhấp vào OK và cho phép tài khoản của bạn chạy lệnh.
Trong Studio, kiểm tra cửa hàng thuốc để xem bất kỳ thay đổi nào phản ánh.Từ cửa sổ Explorer , bạn cũng có thể mở Tập lệnh ReplicatedStorage > ItemList để kiểm tra các thay đổi.

Trên trang này