引擎實例 | 文件 - Roblox 創作者中心

引擎開放雲端 API 讓你可以從網頁管理你的 Roblox 遊戲中的 Instance 物件。

Beta 限制

這些 API 目前處於測試階段，並具有以下限制：

你只能讀取和更新 Script、LocalScript 和 ModuleScript 物件。
你無法更新當前在 Roblox Studio 中打開的腳本。
你無法更新屬於套件的腳本。
你只能使用 API 金鑰身份驗證。創建一個 API 金鑰，並將 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>"
# 在遊戲磁磚的溢出選單中尋找的起始場地 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)

# 解析操作物件的路徑以便稍後獲得實例資源。請參閱輪詢結果部分以獲取更多信息。
operationPath = response.json()['path']

回應中不僅僅列出子項目，還包括一個 Operation 物件，並提供不同的端點。對該端點進行輪詢以非同步地檢索實際的子項目列表。一個更完整的代碼範例看起來像這樣：


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)
# 解析操作物件的路徑以便用於輪詢實例資源。
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": "工作區",
          "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 物件中包含一些額外的信息，例如腳本類型、源碼和是否啟用。

獲取實例

此方法返回單個實例。


import requests

# 生成於 https://create.roblox.com/dashboard/credentials
apiKey = "<API_KEY>"
# 在遊戲磁磚的溢出選單中尋找 https://create.roblox.com/dashboard/creations
universeId = "<UNIVERSE_ID>"
# 在遊戲磁磚的溢出選單中尋找的起始場地 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)

# 從回應中解析操作物件的路徑。請參閱輪詢結果部分以獲取更多信息。
operationPath = response.json()['path']

與列出實例子項目方法一樣，回應中包含一個 Operation 物件，並對其進行輪詢以檢索實際的實例。請參閱輪詢結果獲取更多信息。

更新實例

在獲得適當的實例 ID 後，你可以對其進行更新。在進行初步更新請求後，請輪詢結果。


import json
import requests

# 生成於 https://create.roblox.com/dashboard/credentials
apiKey = "<API_KEY>"
# 在遊戲磁磚的溢出選單中尋找 https://create.roblox.com/dashboard/creations
universeId = "<UNIVERSE_ID>"
# 在遊戲磁磚的溢出選單中尋找的起始場地 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)

# 從回應中解析操作物件的路徑。請輪詢結果以執行
# 更新。
operationPath = response.json()['path']

如果在嘗試更新腳本時收到 TypeError，請確認腳本未在 Roblox Studio 中打開。如果已打開，請關閉其腳本編輯器標籤。你還可以檢查 Studio 輸出以獲得額外的錯誤，例如 Engine_OC_API: Processing Error - Live scripting session is active。

輪詢結果

所有當前的實例方法返回一個 Operation 物件，而不是你請求的資源。該物件允許你以非同步方式執行原始操作。使用 Operation 物件的路徑（包含在初始回應中）來輪詢資源何時準備好。

你可以使用多種輪詢策略，例如使用指數退避或在請求之間的固定延遲。以下示例每五秒進行一次輪詢，最多 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>"

# 輪詢常數
numberOfRetries = 10
retryPollingCadence = 5

# 請求標頭
apiKeyHeaderKey = "x-api-key"
# 長時間運行的操作輪詢的端點 URL
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 表格中讀取數據並更新藥水商店遊戲中的 ReplicatedStorage > ItemList 腳本。

設置示範

前往藥水商店示範發現頁面。單擊溢出選單，然後選擇在 Studio 中編輯。Studio 將以該地方的副本打開。
單擊檔案 → 保存到 Roblox，並填寫必要的信息以將藥水商店示範保存為你的遊戲的默認地點。測試該遊戲。你應該看到藥水商店示範的 UI。記下藥水的名稱、成本和顏色。稍後你將使用開放雲端進行更改！

設置表格

下載藥水商店電子表格文件。
前往 Google Sheets，然後單擊空白電子表格。
在出現的表格中，單擊文件 > 匯入，然後單擊上傳標籤。
將藥水商店電子表格文件拖入上傳窗口。
選擇替換電子表格，然後匯入數據。
在表格的 AppScript 標籤中，複製 A1 單元格中的代碼。
單擊擴展 > 應用程式腳本菜單，將代碼粘貼到 Code.gs 文件中。然後保存該項目。
返回電子表格，選擇更新藥水商店標籤。單擊更新腳本按鈕，單擊溢出選單，然後選擇指派腳本。
在指派腳本窗口中，輸入 UpdateScript 並單擊確定。

創建 API 金鑰

前往 Creator Hub 開放雲端 API 金鑰頁面並單擊創建 API 金鑰。
填寫以下信息的表單。
- 名稱: PotionShop
- API 系統: 添加 universe-place-instances API 系統。將你的藥水商店遊戲添加到系統中。在體驗操作中，添加讀取和寫入訪問權限。
- 接受的 IP 地址: 添加 0.0.0.0/0 作為 IP 地址
- 過期: 無過期
- 單擊保存並生成金鑰，然後將金鑰複製到剪貼板。
將 API 金鑰粘貼到你的 Google 表格的 Intro 標籤中的 API 金鑰單元格 (D2) 中。

獲取宇宙和場地 ID

前往 Creator Hub 創作頁面，將鼠標懸停在藥水商店的遊戲磁磚上，並單擊溢出選單。
選擇複製宇宙 ID，並將其粘貼到你的 Google 表格的 Intro 標籤中的宇宙 ID 單元格 (E2) 中。
選擇複製開始場地 ID，並將其粘貼到你的 Google 表格的 Intro 標籤中的場地 ID 單元格 (F2) 中。

更新腳本值

在表格的更新藥水商店標籤中，修改任何你想要的值，然後單擊更新腳本按鈕。
如果 Google Sheets 提示你進行授權，單擊確定並允許你的帳戶運行腳本。
在 Studio 中，玩測試藥水商店以查看任何反映的更改。在探索者窗口中，你也可以打開 ReplicatedStorage > ItemList 腳本以檢查更改。