引擎实例

引擎开放云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": "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:
  # 没有找到名称。

脚本在Details对象中包含一些额外信息，例如脚本类型、源代码以及是否启用。

获取实例

此方法返回单个实例。


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。

轮询结果

所有当前的实例方法返回一个Operation对象，而不是您请求的资源。此对象让您可以异步执行原始操作。使用Operation对象的路径（包含在初次响应中）来轮询资源是否准备好。

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


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 Sheets演示展示了如何从网络更新体验的脚本。演示包括以下内容：

一个不可复制的地点，有一个模拟UI，显示各种药水及其价格。
一个.ods文件，您可以将其导入到Google Sheets中。此电子表格允许您指定并更新体验中属性的值。
用于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 Sheets提示您授权，请点击确定并允许您的帐户运行脚本。
在Studio中测试魔法药水商店以查看任何反映的更改。在资源管理器窗口中，您还可以打开ReplicatedStorage > ItemList脚本以检查更改。

在此页面