引擎實例

引擎開放雲端 API 讓您從網頁管理 Instance 在 Roblox 體驗中的物件。

測試版限制

這些 API 目前處於測試版並有以下限制：

您只能閱讀和更新 Script、LocalScript 和 ModuleScript 對象。
你無法更新目前在 Roblox Studio 中開啟的腳本。
你不能更新包含在包裝中的腳本。
您只能使用 API 鑰匙認證。創建一個 API 鑰匙並將宇宙位置實例添加為 API 系統。

您必須指定想要鑰匙存取的體驗以及所需的閱讀和寫入權限範圍。
您必須啟用協作會話以存取您想要存使用權通行權存取的體驗。
要求體，例如要更新實例，限於 200 KB。

列出子女

指定一個實例 ID 並呼叫列出實例兒童方法來列出特定實例的所有子實例。

第一次使用這些方法時，指定 root 為實例 ID。收到頂層兒童和其ID列表之後，您可以進行額外呼叫，以查找位空間的實例層級深處的實例。


import requests

# 在 https://create.roblox.com/ashboard/credentials 生成
apiKey = "<API_KEY>"
# 在體驗磚塊的滿溢選單中找到 https://create.roblox.com/dashboard/creations 的創作
universeId = "<UNIVERSE_ID>"
# 在體驗磚塊的滿足菜單中找到開始位置ID https://create.roblox.com/dashboard/creations 在體驗磚塊的滿足菜單中找到開始位置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("Operation Results:", 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("Operation Results:", response.status_code, response.text)
# 解析操作對物件的路徑，用於抓取實例資源的檢查。
operationPath = response.json()['path']
response = PollForResults(operationPath)
print("Response:", 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:
  # The name wasn't found.

腳本包含一些額外資訊在 Details 對物件中，例如腳本輸入、來原始碼和是否已啟用。

取得一個實個體、實例

此方法返回單個實例。


import requests

# 在 https://create.roblox.com/ashboard/credentials 生成
apiKey = "<API_KEY>"
# 在體驗磚塊的滿溢選單中找到 https://create.roblox.com/dashboard/creations 的創作
universeId = "<UNIVERSE_ID>"
# 在體驗磚塊的滿足菜單中找到開始位置ID https://create.roblox.com/dashboard/creations 在體驗磚塊的滿足菜單中找到開始位置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:", response.status_code, response.text)

# 從回應中解析操作對物件的路徑。請參閱「結果檢查」部分獲得更多資訊。
operationPath = response.json()['path']

和列式兒童方法一樣，回應包含一個 Operation 對象，你可以檢索以取得實際實個體、實例。查看檢查結果以獲得更多信息。

更新實例

獲得適當的實例 ID 之後，您可以更新它。對結果進行投票在初始更新請邀請後進行。


import json
import requests

# 在 https://create.roblox.com/ashboard/credentials 生成
apiKey = "<API_KEY>"
# 在體驗磚塊的滿溢選單中找到 https://create.roblox.com/dashboard/creations 的創作
universeId = "<UNIVERSE_ID>"
# 在體驗磚塊的滿足菜單中找到開始位置ID https://create.roblox.com/dashboard/creations 在體驗磚塊的滿足菜單中找到開始位置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:", response.status_code, response.text)

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

如果您在嘗試更新腳指令碼時收到 TypeError，請確認腳本未在 Roblox Studio 中打開。如果是，關閉其腳本編輯器標籤。您也可以檢查工作室輸出的額外錯誤，例如 Engine_OC_API: Processing Error - Live scripting session is active 。

為結果投票

所有現有實例方法都會返回一個 Operation 對象，而不是你請求的資源。這個對象讓你能夠異步執行原本操作。使用 Operation 對物件的路徑 (包含在初始回應中) 來檢查資源何時準備好。

您可以使用各種投票策略，例如使用指數退出或在請求之間使用固定延遲。以下示例每五秒進行一次投票，最多 10 次。


import requests
import time

# 在 https://create.roblox.com/ashboard/credentials 生成
apiKey = "<API_KEY>"
# 使用從初始請邀請中獲得的操作路徑
# 以「宇宙/<UNIVERSE_ID>/地點/<PLACE_ID>/實體/<INSTANCE_ID>/操作/<OPERATION_ID>」的形式取得
operationPath = "<OPERATION_PATH>"

# 投票常數
numberOfRetries = 10
retryPollingCadence = 5

# 請求頭部
apiKeyHeaderKey = "x-api-key"
# 長時間運作檢查的終端網址
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:", response.status_code, response.text)

藥水商店示範

藥水商店 Google 表單示範向您展示如何從網站更新體驗的腳本。示範包括以追蹤中內容：

一個未被複製的地方，具有模擬用戶介面顯示各種藥水和價格。
一個你匯入 Google 表格的 .ods，這個表格讓你能夠指定並更新體驗內的屬性值。
閱讀 Google 表單資料的 Google Apps 腳本代碼，並在 Potion Shop 體驗中更新 ReplicatedStorage > ItemList 腳本。

設置示範

前往藥水商店演示發現頁面。點擊滿足菜單，然後在 Studio 編輯。工作室以複製該空間開啟。
點擊檔案 → 儲存到 Roblox ，填寫必要的信息來保存藥水商店演示作為體驗的預設地點。測試體驗。你應該看到藥水商店示範的使用者介面。記下藥水的名稱、費用和顏色。您將使用開放雲端稍後更改它們！

設置表格

下載藥水商店擴散表文件。
前往 Google 表格並點擊空白工作表。
在出現的表中，點擊檔案 > 匯入，然後點擊上傳標籤。
將藥水商店擴散表文件拖到上傳窗口。
選擇替換表格然後匯入資料。
在表的 AppScript 標籤中，複製 A1 細胞中的代碼。
點擊擴展>應用腳本菜單，並將代碼貼到 Code.gs 中。然後儲存項目。
回到工作表中，選擇更新藥水商店標籤。點擊更新腳本按鈕，點擊溢出選單，然後選擇指派腳本。
在指派腳本窗口中，輸入 UpdateScript 並點擊好。

創建 API 鑰鍵

前往創作者中心開放雲端API鑰匙頁面，然後點擊創建API鑰匙。
填寫以下資訊的表格。
- 名稱 : PotionShop
- API 系統 : 添加宇宙位置實例 API 系統。將您的藥水商店體驗添加到系統。對於經驗操作，添加閱讀和寫入使用權通行權存取。
- 已接受的 IP 地址 : 添加 0.0.0.0/0 作為 IP 地址
- 過期 : 無過期
- 點擊儲存並生成鑰匙，然後將鑰匙複製到剪貼簿。
將 API 鑰匙貼到 Google 表的「介紹」標籤上的 API 鑰匙欄位 (D2)。

獲得宇宙和位置ID

前往創作者中心創作頁磚塊，將鼠標懸停在藥水商店的經驗標籤上，然後點擊滿足菜單。
選擇複製宇宙ID 並將其貼到你Google表單的「介紹」標籤的宇宙ID 欄位(E2)上。
選擇複製開始位置 ID 並將其貼到介紹標籤的 Google 表單中的位置 ID 欄位 (F2)。

更新腳本值

在表單的更新藥水商店標籤中，修改任何你想要的值，然後點擊更新腳本按鈕。
如果 Google 表單提示您進行授權，請點擊確定並允許您的帳戶執行腳指令碼。
在工作室中，測試藥水商店以查看任何反映的變更。從導航器窗口，您也可以開啟 ReplicatedStorage > 項目列表腳本進行檢查變更。

此頁面