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

引擎开放云 API 使您能够从网络管理 Roblox 游戏中的 Instance 对象。

测试限制

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

您只能读取和更新 Script、LocalScript 和 ModuleScript 对象。
您无法更新当前在 Roblox Studio 中打开的脚本。
您无法更新属于包的脚本。
您只能使用 API 密钥身份验证。创建一个 API 密钥，并将 universe-place-instances 添加为 API 系统。

您必须指定希望该密钥访问的游戏以及所需的读写权限范围。
您必须为要访问的游戏启用协作会话。
请求主体，例如更新实例，限制为 200 KB。

列出子项

通过指定实例 ID 并调用列出实例子项方法来列出特定实例的所有子项。

第一次使用这些方法时，请为实例 ID 指定 root。在收到顶级子项及其 ID 列表后，您可以进行其他调用，以在您的地方实例层次结构中查找更深的实例。


import requests

# 在 https://create.roblox.com/dashboard/credentials 生成
apiKey = "<API_KEY>"
# 在 https://create.roblox.com/dashboard/creations 的游戏图块溢出菜单中查找
universeId = "<UNIVERSE_ID>"
# 在 https://create.roblox.com/dashboard/creations 的游戏图块溢出菜单中查找起始地点 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("操作结果:", 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 对象中包含一些额外的信息，例如脚本类型、源和是否已启用。

获取实例

该方法返回单个 Instance。


import requests

# 在 https://create.roblox.com/dashboard/credentials 生成
apiKey = "<API_KEY>"
# 在 https://create.roblox.com/dashboard/creations 的游戏图块溢出菜单中查找
universeId = "<UNIVERSE_ID>"
# 在 https://create.roblox.com/dashboard/creations 的游戏图块溢出菜单中查找起始地点 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.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>"
# 在 https://create.roblox.com/dashboard/creations 的游戏图块溢出菜单中查找起始地点 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.status_code, response.text)

# 从响应中解析操作对象的路径。轮询结果以进行更新。
operationPath = response.json()['path']

如果您在尝试更新脚本时收到 TypeError，请确认该脚本未在 Roblox Studio 中打开。如果它打开，关闭其脚本编辑器选项卡。您还可以检查 Studio 输出，以获取额外的错误，例如 Engine_OC_API: Processing Error - Live scripting session is active。

轮询结果

所有当前 Instance 方法返回一个 Operation 对象，而不是您请求的资源。该对象允许您异步执行原始操作。使用 Operation 对象的路径（在初始响应中包含）来轮询资源何时准备就绪。

您可以使用多种轮询策略，例如使用指数退避或固定延迟进行请求。以下示例每五秒轮询一次，最多十次。


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 表格演示展示了如何从网络更新游戏脚本。演示包括以下内容：

一个没有复制锁的地点，具有显示各种药水和价格的模拟 UI。
一个 .ods 文件，您可以将其导入 Google 表格。该电子表格允许您在游戏中指定和更新属性的值。
Google Apps 脚本的代码，用于读取 Google 表格中的数据并更新药水商店游戏中的 ReplicatedStorage > ItemList 脚本。

设置演示

转到药水商店演示发现页面。单击溢出菜单，然后选择在 Studio 中编辑。 Studio 将打开并包含该地点的副本。
单击文件 → 保存到 Roblox，并填写必要的信息以将药水商店演示保存为您游戏的默认地点。测试该游戏。您应该看到药水商店演示的 UI。请注意药水的名称、费用和颜色。稍后您将使用开放云进行更改！

设置表格

下载药水商店电子表格文件。
转到 Google Sheets，然后单击空白电子表格。
在出现的表格中，单击文件 > 导入，然后单击上传选项卡。
将药水商店电子表格文件拖入上传窗口。
选择替换电子表格，然后导入数据。
在表格的 AppScript 选项卡中，复制 A1 单元格中的代码。
单击扩展 > 应用脚本菜单，并将代码粘贴到 Code.gs 文件中。然后保存项目。
返回电子表格，选择更新药水商店选项卡。单击更新脚本按钮，单击溢出菜单，然后选择分配脚本。
在分配脚本窗口中，输入 UpdateScript，然后单击确定。

创建 API 密钥

转到创建者中心开放云 API 密钥页面，单击创建 API 密钥。
填写以下信息的表单。
- 名称：PotionShop
- API 系统：添加 universe-place-instances API 系统。将您的药水商店游戏添加到系统中。对于经验操作，添加读写访问。
- 接受的 IP 地址：添加 0.0.0.0/0 作为 IP 地址
- 到期：不随到期
- 单击保存并生成密钥，然后复制密钥到剪贴板。
将 API 密钥粘贴到 Google 表格的 Intro 选项卡的 API 密钥单元格 (D2) 中。

获取宇宙和地点 ID

转到创建者中心创建页面，悬停在药水商店的游戏图块上，然后单击溢出菜单。
选择复制宇宙 ID，并将其粘贴到 Google 表格 Intro 选项卡的宇宙 ID 单元格 (E2) 中。
选择复制起始地点 ID，并将其粘贴到 Google 表格 Intro 选项卡的地点 ID 单元格 (F2) 中。

更新脚本值

在该表的更新药水商店选项卡中，修改任何您想要的值，然后单击更新脚本按钮。
如果 Google 表格提示您进行授权，单击确定并允许您的帐户运行该脚本。
在 Studio 中，测试药水商店以查看任何反映的更改。在资源管理器窗口中，您还可以打开 ReplicatedStorage > ItemList 脚本以检查更改。