引擎实例 | 文档 - Roblox 创作者中心

引擎打开云 API 让您从网站管理 Instance 对象在您的 Roblox 体验。

测试版限制

这些 API 目前在测试中，并且具有以下限制：

您只能读取和更新 Script ， LocalScript 和 ModuleScript 对象。
您无法在 Roblox Studio 中更新已打开的脚本。
您无法更新包裹中的脚本。
您只能使用 API 钥匙验证。创建一个 API 钥匙用宇宙-place-instances 作为 API 系统的添加。

您必须指定您想要拥有钥匙访问权限的体验以及您希望拥有的阅读和写入权限范围。
您必须有一个协作会话启用才能1) 使用权 2）通行证 3）访问权限问您想要的体验。
请求身体，例如要更新实例，是限于 200 KB 的。

列出孩子

使用特定实例的实例ID并调用列出实例子女方法来列出特定实例的所有子女。

第一次使用这些方法时，为实例 ID 指定 root。在您收到列表顶级子供及其ID之后，您可以通过调用额外的调用来查找您场景方的实例层级深度。


import requests

# 在 https://创建.roblox.com/ashboard/credentials 生成
apiKey = "<API_KEY>"
# 在体验地瓦片的剩余菜单中找到在 https://create.roblox.com/dashboards/creations
universeId = "<UNIVERSE_ID>"
# 在体验地砖的剩余菜单中找到 Start Place ID 在创作菜单瓦片
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://创建.roblox.com/ashboard/credentials 生成
apiKey = "<API_KEY>"
# 在体验地瓦片的剩余菜单中找到在 https://create.roblox.com/dashboards/creations
universeId = "<UNIVERSE_ID>"
# 在体验地砖的剩余菜单中找到 Start Place ID 在创作菜单瓦片
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://创建.roblox.com/ashboard/credentials 生成
apiKey = "<API_KEY>"
# 在体验地瓦片的剩余菜单中找到在 https://create.roblox.com/dashboards/creations
universeId = "<UNIVERSE_ID>"
# 在体验地砖的剩余菜单中找到 Start Place ID 在创作菜单瓦片
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 中未打开。如果它打开，请关闭其脚本编辑器标签。您还可以检查 Studio 输出以获取额外错误，例如 Engine_OC_API: Processing Error - Live scripting session is active。

结果投票

所有当前实例方法都会返回一个 Operation 对象，而不是您请求的资源。此对象允许您异步执行原始操作。使用 Operation 对象的路径 (包含在初始回应中) 来调查资源准备好时。

您可以使用各种不同的投票策略，例如使用叠加式后退或在请求之间的固定延迟。以下示例每五秒钟，最多 10 次。


import requests
import time

# 在 https://创建.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"
# 远程操作调度的终点 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 Sheets示例向您展示了从网站更新体验脚本。该示例包括以关注中/正在关注内容：

一个未复制的地方，带有模拟 UI 显示各种药水和其价格。
您导入到Google Sheets的一个 .ods 文件。此拖动表让您指定并更新体验中的属性。
代码为Google Sheet的脚本，从Google Sheet中读取数据并更新Potion Shop的 ReplicatedStorage 脚本。

设置示例

前往药水商店示例页面。单击溢出菜单，然后编辑在Studio 。 Studio 会弹出一个场景方的副本。
单击文件 → 保存到 Roblox 并填写必要信息以保存药水商店示例为您的体验的默认位置。测试体验。您应该看到 Potion Shop Demo 的 UI 。记住名称、成本和颜色。你将在稍后使用 Open Cloud 进行更改！

设置 Sheet

下载药水商店的 Excel 文件。
前往Google Sheets，然后单击空白 spreadsheets 。
在出现的表单中，单击文件>导入导入，然后单击上传选项卡。
将药水商店的树叶文件拖放到上传窗口。
选择替换 Excel 表，然后导入数据。
在页面的 AppScript 选项卡中，复制代码在 A1 个细胞。
单击 Extensions > Apps Script 菜单，然后将代码复制到Code.gs文件。然后保存项目。
回到 Excel 表中，选择更新药水商店选项卡。单击更新脚本按钮，单击过度菜单，然后选择分配脚本。
在分配脚本窗口中，输入UpdateScript并单击好的。

创建 API 钥匙

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

获取宇宙和地点ID

前往创作者中心创作页瓦片，将鼠标悬停在药水商店的经验区域上，然后单击剩余菜单。
选择复制宇宙 ID 并将其粘贴到 Google Sheet 的宇宙 ID 中的 E2 标签上。
选择复制开始位置 ID 并将其粘贴到 Google Sheet 的位置 ID cell (F2) 上。

更新脚本值

在更新药水商店选项卡的页面上，修改您想要的任何值，然后单击更新脚本按钮。
如果Google Sheets向您要求授权，请单击好的并允许您的帐户运行脚本。
在 Studio 中，玩测试药水商店以反映任何反射的更改。从 Explorer 窗口，您还可以打开 ReplicatedStorage > ItemList脚本来检查更改。