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

開放雲端 API 讓您管理 Instance 對象在 Roblox 體驗。

Beta 限制

這些 API 目前在測試中，並且有以下限制：

您只能閱取並更新 Script 、 LocalScript 和 ModuleScript 對象。
您無法在 Roblox Studio 中更新目前開啟的指令碼。
您不能更新包裹中的指令碼。
您只能使用 API 鑰匙認證。建立 API 鑰匙與 universe-place-instances 作為 API 系統的添加。

您必須指定您想要鑰匙有權使用的體驗，以及您想要的閱取和寫入權限範圍。
您必須啟用協作會話室，才能存取您想要存使用權通行權存取的體驗。
要求身體，例如要更新實例，是以 200 KB 的限制。

列出兒童

使用特定實例的子列表列出實例子女，並指定子列表 ID 來列出所有子女。

第一次使用這些方法時，為實例 ID 指定 root。在您收到子孫清單和子孫 ID 清單後，您可以進行額外的呼叫，以在您的空間置的子孫階層中找到更深層的實例。


import requests

# 在 https://create.roblox.com/dash/credentials 生成
apiKey = "<API_KEY>"
# 在體驗磚塊的暫時菜單中查找在 https://create.roblox.com/dashboards/creations 在體驗磚塊的暫時菜單中
universeId = "<UNIVERSE_ID>"
# 在體驗磚塊的暫時菜單中，在https://create.roblox.com/dash/creations尋找開始位置 ID
placeId = "<PLACE_ID>"
# 任何空間方資料模型的根的預設 ID
instanceId = "root"

# 請求頭銜
apiKeyHeaderKey = "x-api-key"
# 列兒童方法的終端網址
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/dash/credentials 生成
apiKey = "<API_KEY>"
# 在體驗磚塊的暫時菜單中查找在 https://create.roblox.com/dashboards/creations 在體驗磚塊的暫時菜單中
universeId = "<UNIVERSE_ID>"
# 在體驗磚塊的暫時菜單中，在https://create.roblox.com/dash/creations尋找開始位置 ID
placeId = "<PLACE_ID>"
# 任何空間方資料模型的根的預設 ID
instanceId = "<INSTANCE_ID>"

# 請求頭銜
apiKeyHeaderKey = "x-api-key"
# 取得實例方法的終端網址
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 方法相同，回應包含一個 Operation 對象，你可以調用它來取回實際個體、實例子。請參閱調用結果以取得更多資訊。

更新實例

獲得適當的實例 ID 後，您可以更新它。投票以取得結果之後，作出初始更新請邀請後。


import json
import requests

# 在 https://create.roblox.com/dash/credentials 生成
apiKey = "<API_KEY>"
# 在體驗磚塊的暫時菜單中查找在 https://create.roblox.com/dashboards/creations 在體驗磚塊的暫時菜單中
universeId = "<UNIVERSE_ID>"
# 在體驗磚塊的暫時菜單中，在https://create.roblox.com/dash/creations尋找開始位置 ID
placeId = "<PLACE_ID>"
instanceId = "<INSTANCE_ID>"
instanceType = ""
propertyName = ""
propertyValue = ""

# 請求頭銜
apiKeyHeaderKey = "x-api-key"
contentTypeHeaderKey = "Content-type"
contentTypeHeaderValue = "application/json"
# 更新實例方法的終端網址
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 中開啟。如果是，請關閉其 Script Editor 標籤。您也可以檢查 Studio 輸出的其他錯誤，例如 Engine_OC_API: Processing Error - Live scripting session is active。

結果投票

所有目前的實例方法都會返回資源，而不是您要求的資源。這個對象讓您可以在資源準備好時立即執行原始操作。使用 Operation 對物件的路徑 (包含在初始回應中) 來偵測資源準備好時。

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


import requests
import time

# 在 https://create.roblox.com/dash/credentials 生成
apiKey = "<API_KEY>"
# 從您的初始請邀請使用運作路徑
# 以「<UNIVERSE_ID>」的形式代表「<UNIVERSE_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 表示從網頁更新體驗的指令碼。此示範包含以追蹤中內容：

一個沒有鎖定的地方，具有模擬 UI 顯示各種藥水和價格。
您匯入到Google Sheets的 .ods 檔案。這個匯總表讓您指定並更新體驗中的屬性值。
一個 Google 的 Apps 指令，讀取資料從 Google 表閱取並在 Potion Shop 體驗中更新 ReplicatedStorage > ItemList 指令。

設置演示

前往Potion Shop Demo頁面。點擊溢出菜單，然後編輯在 Studio 。 Studio 會以地空間的副本開啟。
點擊文件 →儲存到Roblox→填寫必要信息以儲存藥水商店示範為預設位置。測試體驗。你應該看到UI藥水商店示範的UI。記錄名稱、價格和顏色。你將在之後使用OpenCloud來變更它們！

設置紙張

下載藥水商店擴展表。
前往 Google Sheets 並按一下空白檢查表。
在出現的頁面上，按一下檔案 > 匯入，然後按一下上傳標籤。
將魔法商店擴展表格檔案拖入上傳視窗。
選擇替換懸賞表然後匯入資料。
在紙張的 AppScript 標籤中，複製代碼在 A1 個牢房。
點擊擴展機構選單並將代碼貼入Code.gs檔案。然後儲存項目。
回到檢查表中，選擇更新藥水商店標籤。點擊更新腳本按鈕，點擊滿滿菜單，然後選擇1>分配腳本1>。
在指定指令碼窗口中，輸入 UpdateScript 並按一下好的。

創建 API 鑰API 金鑰

前往創作者中心開放雲 API 鑰匙頁面，然後按一下創建 API 鑰匙。
填寫以下資料。
- 名稱 : 藥水商店
- API 系統 : 添加宇宙位置實例 API 系統。添加您的藥水商店體驗到系統。對於體驗操作，添加閱取和寫入使用權通行權存取。
- 接受的 IP 地址 : 增加 0.0.0.0/0 作為 IP 地址
- 過期 : 沒有過期
- 按一下儲存並生成鑰匙然後複製鑰匙到剪貼板。
將 API 鑰匙貼在 Google Sheet 的介紹標籤上的 API 鑰匙細胞 (D2)。

獲取宇宙和位置 ID

前往創作者中心創作頁面，將鼠標擺動在藥水商店的體驗磚塊上，然後單擊剩餘選單。
選擇複製宇宙 ID 並將它貼入 Google Sheet 的宇宙 ID 列(E2)。
選擇複製開始位置 ID 並將它貼入 Google Sheet 的位置 ID 元素 (F2) 在介紹標籤的第一個頁面。

更新指令值

在頁面的更新藥水商店標籤中，修改您想要的任何值，然後按一下更新腳本按鈕。
如果 Google 表格提示您要授權，請按一下好的並允許您的帳戶執行指令碼。
在 Studio 中，玩測試藥水商店，以反應任何反射的變更。從 Explorer 窗口，您也可以開啟 ReplicatedStorage 的 ItemList 指令，以檢查變更。