Các Open Cloud APIs của Engine cho phép bạn quản lý các đối tượng Instance trong các trò chơi Roblox của bạn từ web.
Những hạn chế beta
Các APIs này hiện đang trong giai đoạn beta và có những hạn chế sau:
Bạn chỉ có thể đọc và cập nhật các đối tượng Script, LocalScript và ModuleScript.
Bạn không thể cập nhật các script hiện đang mở trong Roblox Studio.
Bạn không thể cập nhật các script là một phần của một gói.
Bạn chỉ có thể sử dụng xác thực API key. Tạo một API key với universe-place-instances được thêm vào như một hệ thống API.
Bạn phải chỉ định các trò chơi mà bạn muốn key có quyền truy cập cũng như các phạm vi quyền đọc và ghi mong muốn.

Bạn phải có một phiên hợp tác được bật cho trò chơi 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 Đối tượng, bị giới hạn ở 200 KB.
Liệt kê các đối tượng con
Liệt kê tất cả các đối tượng con của một đối tượng cụ thể bằng cách chỉ định một ID đối tượng và gọi phương thức Liệt kê các Đối tượng Con.
import requests
# Tạo tại https://create.roblox.com/dashboard/credentials
apiKey = "<API_KEY>"
# Tìm tại https://create.roblox.com/dashboard/creations trong menu tràn của một ô trò chơi
universeId = "<UNIVERSE_ID>"
# Tìm ID Nơi Bắt Đầu tại https://create.roblox.com/dashboard/creations trong menu tràn của một ô trò chơi
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 nơi
instanceId = "root"
# Tiêu đề yêu cầu
apiKeyHeaderKey = "x-api-key"
# URL điểm cuối cho phương thức Liệt kê Các Đối tượng Con
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("Kết quả Hoạt động:", response.status_code, response.text)
# Phân tích đường dẫn đối tượng Hoạt động để sau này lấy tài nguyên Instance. Xem phần Polling for Results để biết thêm thông tin.
operationPath = response.json()['path']
Thay vì chỉ liệt kê các đối tượng con, phản hồi bao gồm một đối tượng Operation với một điểm cuối khác. Poll điểm cuối này để nhận danh sách thực tế các đối tượng con. Một mẫu 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("Kết quả Hoạt động:", response.status_code, response.text)
# Phân tích đường dẫn đối tượng Hoạt động để sử dụng trong việc polling tài nguyên đối tượng.
operationPath = response.json()['path']
response = PollForResults(operationPath)
print("Phản hồi:", 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 qua JSON để tìm một ID đối tượng cụ thể:
instances = response.json()['response']['instances']replicatedStorageId = ""for i in instances:if i['engineInstance']['Name'] == "ReplicatedStorage":replicatedStorageId = i['engineInstance']['Id']if replicatedStorageId:# Bạn giờ có một ID đối tượng và có thể lấy hoặc cập nhật nó.else:# Tên không được tìm thấy.
Các script chứa một số thông tin bổ sung trong đối tượng Details, chẳng hạn như loại script, nguồn gốc và liệu chúng có được kích hoạt hay không.
Lấy một đối tượng
Phương thức này trả về một Instance.
import requests
# Tạo tại https://create.roblox.com/dashboard/credentials
apiKey = "<API_KEY>"
# Tìm tại https://create.roblox.com/dashboard/creations trong menu tràn của một ô trò chơi
universeId = "<UNIVERSE_ID>"
# Tìm ID Nơi Bắt Đầu tại https://create.roblox.com/dashboard/creations trong menu tràn của một ô trò chơi
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 nơi
instanceId = "<INSTANCE_ID>"
# Tiêu đề yêu cầu
apiKeyHeaderKey = "x-api-key"
# URL điểm cuối cho phương thức Lấy Đối tượng
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("Phản hồi:", response.status_code, response.text)
# Phân tích đường dẫn đối tượng Hoạt động từ phản hồi. Xem phần Polling for Results để biết thêm thông tin.
operationPath = response.json()['path']
Cũng giống như phương thức Liệt kê Các Đối tượng Con, phản hồi bao gồm một đối tượng Operation mà bạn polling để lấy lại đối tượng thực tế. Xem Poll for results để biết thêm thông tin.
Cập nhật các đối tượng
Sau khi bạn có ID đối tượng thích hợp, bạn có thể cập nhật nó. Poll for results 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/dashboard/credentials
apiKey = "<API_KEY>"
# Tìm tại https://create.roblox.com/dashboard/creations trong menu tràn của một ô trò chơi
universeId = "<UNIVERSE_ID>"
# Tìm ID Nơi Bắt Đầu tại https://create.roblox.com/dashboard/creations trong menu tràn của một ô trò chơi
placeId = "<PLACE_ID>"
instanceId = "<INSTANCE_ID>"
instanceType = ""
propertyName = ""
propertyValue = ""
# Tiêu đề yêu cầu
apiKeyHeaderKey = "x-api-key"
contentTypeHeaderKey = "Content-type"
contentTypeHeaderValue = "application/json"
# URL điểm cuối cho phương thức Cập nhật Đối tượng
updateInstanceUrl = "https://apis.roblox.com/cloud/v2/universes/%s/places/%s/instances/%s"
# Các 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("Phản hồi:", response.status_code, response.text)
# Phân tích đường dẫn đối tượng Hoạt động từ phản hồi. Poll for results để thực hiện
# cập nhật.
operationPath = response.json()['path']
Poll for results
Tất cả các phương thức Instance hiện tại trả về một đối tượng Operation thay vì tài nguyên bạn đã yêu cầu. Đối tượng này cho phép bạn thực hiện bất đồng bộ hoạt động ban đầu. Sử dụng đường dẫn của đối tượng Operation (bao gồm trong phản hồi ban đầu) để polling khi tài nguyên đã sẵn sàng.
Bạn có thể sử dụng nhiều chiến lược polling khác nhau, chẳng hạn như sử dụng phương pháp lùi cấp số nhân hoặc một khoảng thời gian cố định giữa các yêu cầu. Ví dụ sau polls mỗi năm giây, lên đến 10 lần.
import requests
import time
# Tạo tại https://create.roblox.com/dashboard/credentials
apiKey = "<API_KEY>"
# Sử dụng đường dẫn Operation từ yêu cầu ban đầu của bạn
# Có định dạng là "universes/<UNIVERSE_ID>/places/<PLACE_ID>/instances/<INSTANCE_ID>/operations/<OPERATION_ID>"
operationPath = "<OPERATION_PATH>"
# Hằng số polling
numberOfRetries = 10
retryPollingCadence = 5
# Tiêu đề yêu cầu
apiKeyHeaderKey = "x-api-key"
# URL điểm cuối cho việc polling hoạt động lâu dài
getOperationUrl = "https://apis.roblox.com/cloud/v2/%s"
# Các 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("Phản hồi:", response.status_code, response.text)
Demo Cửa Hàng Thuốc
Demo Cửa Hàng Thuốc Google Sheets cho bạn thấy cách cập nhật một script trò chơi từ web. Demo bao gồm các phần sau:
- Một nơi không bị khóa với một UI giả hiển thị các loại thuốc khác nhau và giá của chúng.
- Một tệp .ods mà bạn nhập vào Google Sheets. Bảng tính này cho phép bạn chỉ định và cập nhật giá trị cho các thuộc tính trong trò chơi.
- Mã cho một Google Apps Script đọc dữ liệu từ Bảng tính Google và cập nhật script ReplicatedStorage > ItemList trong trò chơi Cửa Hàng Thuốc.
Thiết lập demo
Đi đến Demo Cửa Hàng Thuốc Trang Discover. Nhấp vào menu tràn, và sau đó Chỉnh sửa trong Studio. Studio mở ra với một bản sao của nơi.
Nhấp Tệp → Lưu vào Roblox và điền vào thông tin cần thiết để lưu demo Cửa Hàng Thuốc như nơi mặc định cho trò chơi của bạn. Kiểm tra trò chơi. Bạn nên thấy UI của Demo Cửa Hàng Thuốc. Hãy ghi chú 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 bằng cách sử dụng Open Cloud!
Thiết lập bảng tính
- 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 bảng tính xuất hiện, nhấp Tệp > 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 bảng tính, sao chép mã trong ô A1.
- Nhấp vào menu Mở rộng > Apps Script và dán mã vào tệp Code.gs. Sau đó lưu dự án.
- Quay lại bảng tính, chọn tab Cập nhật Cửa Hàng Thuốc. Nhấp vào nút Cập nhật Script, nhấp vào menu tràn, và chọn Gán script.
- Trong cửa sổ Gán script, nhập UpdateScript và nhấp OK.
Tạo một API key
Đi đến trang API Keys Open Cloud của Creator Hub và nhấp Tạo API Key.
Điền vào biểu mẫu với thông tin sau.
- Tên: PotionShop
- Hệ thống API: Thêm hệ thống API universe-place-instances. Thêm trò chơi Cửa Hàng Thuốc của bạn vào hệ thống. Đối với Experience Operations, thêm quyền truy cập đọc và ghi.
- Địa chỉ IP Được Chấp Nhận: Thêm 0.0.0.0/0 như một Địa chỉ IP
- Thời gian hết hạn: Không có thời gian hết hạn
- Nhấp Lưu & Tạo Khóa và sau đó Sao chép Khóa vào Clipboard.
Dán API key vào ô API Key (D2) trên tab Giới thiệu của Bảng tính Google của bạn.
Lấy ID vũ trụ và nơi
- Đi đến trang Tạo Hình Đại Diện của Creator Hub, di chuột qua ô trò chơi Cửa Hàng Thuốc, và nhấp vào menu tràn.
- Chọn Sao chép ID Vũ Trụ và dán vào ô ID Vũ Trụ (E2) trên tab Giới thiệu của Bảng tính Google của bạn.
- Chọn Sao chép ID Nơi Bắt Đầu và dán vào ô ID Nơi (F2) trên tab Giới thiệu của Bảng tính Google của bạn.
Cập nhật các giá trị của script
- Trong tab Cập nhật Cửa Hàng Thuốc của bảng tính, 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 Script.
- Nếu Google Sheets yêu cầu bạn để ủy quyền, nhấp OK và cho phép tài khoản của bạn chạy script.
- Trong Studio, thử nghiệm Cửa Hàng Thuốc để thấy bất kỳ thay đổi nào được phản ánh. Từ cửa sổ Explorer, bạn cũng có thể mở script ReplicatedStorage > ItemList để kiểm tra các thay đổi.