引擎实例

引擎打开云 API 让你从网页管理 Roblox 体验中的 Instance 对象。

测试版限制

这些 API 目前处于测试版，并有以下限制：

您只能阅读和更新 Script、LocalScript 和 ModuleScript 对象。
你无法更新在 Roblox Studio 中打开的脚本。
你不能更新包含在包装中的脚本的脚本。
您只能使用 API 钥匙验证。创建一个 API 钥匙与宇宙位置实例添加的 API 系统。

您必须指定您希望钥匙访问的体验以及所需的读写权限范围。
您必须为想要1) 使用权 2）通行证 3）访问权限问的体验启用协作会话协作会话。
请求体，例如要更新实例，限制为 200KB。

列出子女

通过指定一个实例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 在 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/dashboard/credentials 生成
apiKey = "<API_KEY>"
# 在体验地砖的溢出菜单中找到 https://create.roblox.com/dashboard/creations 的创瓦片
universeId = "<UNIVERSE_ID>"
# 在体验地砖的溢出菜单中找到始终位置 ID https://create.roblox.com/dashboard/creations 在 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/dashboard/credentials 生成
apiKey = "<API_KEY>"
# 在体验地砖的溢出菜单中找到 https://create.roblox.com/dashboard/creations 的创瓦片
universeId = "<UNIVERSE_ID>"
# 在体验地砖的溢出菜单中找到始终位置 ID https://create.roblox.com/dashboard/creations 在 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/dashboard/credentials 生成
apiKey = "<API_KEY>"
# 使用从初始请求中获取的操作路径
# 以“宇宙/<UNIVERSE_ID>/地点/<PLACE_ID>/实例/<INSTANCE_ID>/操作/<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:", response.status_code, response.text)

药水商店示范

药水店 Google 表演示向您展示如何从网页更新体验脚本。该示例由以关注中/正在关注内容组成：

一个未锁定的地方，具有模拟用户界面显示各种药水和价格。
你导入到 Google 表中的一个 .ods 文件。这张表可让你为体验中的属性指定和更新值。
从 Google 表中读取数据并在药水商店体验中更新 ReplicatedStorage > ItemList 脚本的 Google Apps 脚本代码。

设置演示

前往药水商店演示发现页。点击溢出菜单，然后在工作室编辑。工作室打开时打开一个场景方的副本。
点击文件 → 保存到 Roblox 并填写必要的信息，将药水商店演示保存为体验的默认地点。测试体验。你应该看到药水商店演示的用户界面。记录药水的名称、成本和颜色。您将使用开放云更改它们！

设置表格

下载药水商店的Excel文件。
前往 Google 表格并单击空白工作表。
在出现的表中，单击文件>导入，然后单击上传选项卡。
将药水商店的 Excel 文件拖到上传窗口。
选择替换表格然后导入数据。
在表的 AppScript 选项卡中，复制 A1 细胞中的代码。
点击扩展>应用脚本菜单，并将代码粘贴到Code.gs中。然后保存项目。
回到工作表中，选择更新药水商店标签。点击更新脚本按钮，点击溢出菜单，然后选择分配脚本。
在分配脚本窗口中，输入 UpdateScript 并单击好的。

创建 API 钥键

前往创作者中心开放云API钥匙页面，然后单击创建API钥匙。
填写以下信息的表格。
- 名称 : 药水商店
- API 系统 : 添加宇宙位置实例 API 系统。将您的药水商店体验添加到系统。对于经验操作，添加阅读和写入1) 使用权 2）通行证 3）访问权限。
- 接受的 IP 地址 : 添加 0.0.0.0/0 作为 IP 地址
- 过期 : 无过期
- 点击保存并生成密钥，然后将密钥复制到剪贴板。
将 API 钥匙粘贴到 Google 表的导入选项卡的 API 钥匙细胞（D2）。

获取宇宙和地点ID

前往创作者中心创作页瓦片，将鼠标悬停在药水商店的经验地砖上，然后单击溢出菜单。
选择复制宇宙ID并将其粘贴到你Google表的“宇宙ID”栏(E2)上
选择复制起始位置ID 并将其粘贴到介绍选项卡的 Google 表中的位置ID 细胞（F2）上。

更新脚本值

在表的更新药剂商店选项卡中，修改任何你想要的值，然后单击更新脚本按钮。
如果 Google 表单提示您进行授权，请单击好的并允许您的帐户运行脚本。
在工作室中，测试药水商店以查看任何反映的更改。从 Explorer 窗口，您还可以打开 ReplicatedStorage > ItemList 脚本进行检查更改。

在此页面