通過Open Cloud在Roblox地方中無頭運行Luau腳本，以進行自動化測試、遊戲配置和程序生成，並完全訪問DataModel和引擎Luau API。任務可持續運行最多5分鐘，每個地方限制10個並行任務。您可以使用[`SavePlaceAsync`](/reference/engine/classes/AssetService#SavePlaceAsync)保存更改，傳遞大型二進制負載，並使用[`SerializationService`](/reference/engine/classes/SerializationService)反序列化RBXM內容。參考實現請參見[Roblox/place-ci-cd-demo](https://github.com/Roblox/place-ci-cd-demo)。

工作流程：

1. [創建任務](#Cloud_CreateLuauExecutionSessionTask__Using_Universes)與您的universeId、placeId和要運行的Luau腳本。
2. 伺服器啟動，載入地方並執行您的代碼。
3. [輪詢以獲取完成情況](#Cloud_GetLuauExecutionSessionTask)，並獲取腳本的返回值和[日誌](#Cloud_ListLuauExecutionSessionTaskLogs)。

常見用例包括：

- 自動化測試：在CI/CD管道中對特定地方版本運行測試腳本。
- 遊戲配置：在Studio之外更新定價、統計和均衡變數。

表示可以是 null、數字、字符串、布爾值、遞歸結構值或值列表的動態類型值。

父集合中的LuauExecutionSessionTaskLogs列表。

指定LuauExecutionSessionTask的LuauExecutionSessionTaskLogs。

你可以作為`pageToken`參數發送的令牌，以檢索下一頁。如果此字段省略，則沒有後續頁。

一個 `LuauExecutionSessionTask`（簡稱「任務」）在特定版本的場所上下文中執行給定的 Luau 腳本。

在任務中，物理模擬不會運行。伺服器和本地腳本也不會自動運行。

該腳本可以訪問和更新場所的數據模型，包括調用任何模塊腳本。然而，數據模型的變更是局部的，無法持久化。

該腳本還可以調用讀取和/或修改存儲在雲中的數據的引擎 API，例如這些數據的 DataStores。在使用這些 API 時請謹慎。

腳本大小最多可達 4 MB，執行最多可持續 5 分鐘。超過時間限制的腳本將以錯誤終止。

腳本是原樣執行的，無需包裝在函數中。

腳本可以返回值（使用 Luau 的 `return` 關鍵字）。返回值會被序列化為 JSON，並可以在任務完成後通過 `Get
LuauExecutionSessionTask` API 檢索。JSON 序列化後的返回值總大小不得超過 4 MB。如果超過限制，任務將以錯誤終止。

如果腳本引發了未處理的錯誤，則任務將終止。可以使用 `GetLuauExecutionSessionTask` API 檢索錯誤信息。

標準輸出（由 Luau 的 `print` 函數生成）可以在任務完成後使用 `ListLuauExecutionSessionTaskLogs` 方法檢索。最多保留 450 KB 的日誌。如果日誌數量超過限制，較舊的日誌將被丟棄。

任務信息在任務完成後保留 24 小時。

每個場所最多允許十個未完成的任務。在第一批十個未完成任務的情況下嘗試創建更多任務將導致 HTTP 429 響應。

該任務的二進制輸入的資源路徑。請參閱`LuauExecutionSessionTaskBinaryInput`資源的文檔以獲取用法詳細信息。

該任務的二進制輸出的URI。請參閱`enableBinaryOutput`字段以獲取用法詳細信息。

如果設置為true，則允許該任務在標準返回值之外輸出大型二進制對象。

如果`enable_binary_output`設置為true，則任務腳本必須返回`LuauExecutionTaskOutput`（或等效表）而不返回其他值。

以下是這樣做的示例代碼：

```luau
local buf: buffer = buffer.create(10)
local result: LuauExecutionTaskOutput = {
  BinaryOutput = buf,
  ReturnValues = { "hello world", 123 }
}
return result
```

`BinaryOutput`緩衝區的大小不得超過256 MiB。

如果提供，`ReturnValues`數組將序列化為JSON，並將可用於`LuauExecutionSessionTask`資源的`output`字段，類似於不使用`enable_binary_output`時的常規返回值。

二進制輸出可以在任務完成後從`binaryOutputUri`字段的URI中獲取。`binaryOutputUri`在任務完成後的15分鐘內有效。

luau執行會話任務的資源路徑。

格式：
* `universes/{universe_id}/places/{place_id}/luau-execution-session-tasks/{luau_execution_session_task_id}`
* `universes/{universe_id}/places/{place_id}/versions/{place_version_id}/luau-execution-session-tasks/{luau_execution_session_task_id}`
* `universes/{universe_id}/places/{place_id}/luau-execution-sessions/{luau_execution_session_id}/tasks/{luau_execution_session_task_id}`
* `universes/{universe_id}/places/{place_id}/versions/{place_version_id}/luau-execution-sessions/{luau_execution_session_id}/tasks/{luau_execution_session_task_id}`

作為此任務的一部分運行的腳本。

例如：

```luau
local x = 3
local y = 4
return x + y
```

任務的狀態。請參閱State枚舉以獲取有關每個可能值的信息。

可能的值：

  | 值 | 描述 |
  | --- | --- |
  | STATE_UNSPECIFIED | 未指定 |
  | QUEUED | 此任務正在等待處理。 |
  | PROCESSING | 此任務已開始處理。 |
  | CANCELLED | 此任務已被用戶停止。 |
  | COMPLETE | 此任務已完成處理。輸出字段包含輸出。 |
  | FAILED | 此任務失敗。錯誤字段包含有關錯誤的詳細信息。 |

腳本運行的時間限制。

如果腳本未在指定的持續時間內完成，則該任務將失敗。

默認為5分鐘。

此任務的狀態上次更改的時間。

創建此任務所使用的API金鑰的用戶。

表示可以提供給 `LuauExecutionSessionTask` 的大型二進制輸入。

每個 `LuauExecutionSessionTaskBinaryInput` 都與一個預簽名的 URL 相關聯，該 URL 可用於上傳任意對象。上傳對象後，可以在創建 `LuauExecutionSessionTask` 時傳遞 `LuauExecutionSessionTaskBinaryInput` 的路徑，以便讓任務可以訪問該對象。

在任務內，對象的內容會在作為第一個參數傳遞到腳本的表中提供，鍵為 `BinaryInput`。以下示例演示了如何檢索該數據：

```
local taskInput: LuauExecutionTaskInput = ({...})[1]
local buf: buffer = taskInput.BinaryInput
```

每個 `LuauExecutionSessionTaskBinaryInput` 的有效期為創建時間起的 15 分鐘。在此期間，如有需要，可以用它為相同的宇宙創建多個任務。

上傳的二進制對象的大小不得超過 100 MiB。

luau 執行會話任務二進制輸入的資源路徑。

格式：
`universes/{universe_id}/luau-execution-session-task-binary-inputs/{luau_execution_session_task_binary_input_id}`

要上傳的二進制輸入對象的大小。

最大允許大小為 100 MiB。

使用此 URI 上傳二進制輸入對象。

表示由 `LuauExecutionSessionTask` 生成的一部分日誌消息。

保留的日誌數量是有限的。 有關詳細信息，請參見 `LuauExecutionSessionTask` 資源的文檔。

日誌的保留時間與父任務相同。

任務執行生成的日誌消息列表。
來自任務腳本代碼中的每次 Luau `print()` 調用在此處都會產生一個單一的列表項，即使消息本身包含換行。當視圖為 FLAT（默認值）時，此字段將被填充。

luau 執行會話任務日誌的資源路徑。

格式：
* `universes/{universe_id}/places/{place_id}/luau-execution-session-tasks/{luau_execution_session_task_id}/logs/{luau_execution_session_task_log_id}`
* `universes/{universe_id}/places/{place_id}/versions/{place_version_id}/luau-execution-session-tasks/{luau_execution_session_task_id}/logs/{luau_execution_session_task_log_id}`
* `universes/{universe_id}/places/{place_id}/luau-execution-sessions/{luau_execution_session_id}/tasks/{luau_execution_session_task_id}/logs/{luau_execution_session_task_log_id}`
* `universes/{universe_id}/places/{place_id}/versions/{place_version_id}/luau-execution-sessions/{luau_execution_session_id}/tasks/{luau_execution_session_task_id}/logs/{luau_execution_session_task_log_id}`

任務執行生成的日誌消息和相關元數據的列表。
來自任務腳本代碼中的每次 Luau `print()` 調用在此處都會產生一個單一的列表項，即使消息本身包含換行。當視圖為 STRUCTURED 時，此字段將被填充。

日誌消息的 `MessageType`。

可能的值：

  | 值 | 描述 |
  | --- | --- |
  | MESSAGE_TYPE_UNSPECIFIED | 未指定 |
  | OUTPUT | 對應於引擎 API 的 `MessageOutput` 枚舉值。 |
  | INFO | 對應於引擎 API 的 `MessageInfo` 枚舉值。 |
  | WARNING | 對應於引擎 API 的 `MessageWarning` 枚舉值。 |
  | ERROR | 對應於引擎 API 的 `MessageError` 枚舉值。 |

在執行失敗的情況下包含錯誤詳細信息。

表示錯誤類別的錯誤碼。

可能的值：

  | 值 | 描述 |
  | --- | --- |
  | ERROR_CODE_UNSPECIFIED | 未指定 |
  | SCRIPT_ERROR | 任務的腳本引發了未處理的錯誤。 |
  | DEADLINE_EXCEEDED | 任務超過了允許的最大執行時間。 |
  | OUTPUT_SIZE_LIMIT_EXCEEDED | 任務的輸出過大。 |
  | INTERNAL_ERROR | 任務因內部系統錯誤而失敗。 |

包含有關錯誤的更多詳細信息的錯誤消息。

運行的腳本返回的值。無法 JSON 序列化的返回值（例如數據模型實例）將返回為 null。

可配置的密鑰，允許對 Roblox 資源進行細粒度訪問。詳細信息請參見 https://create.roblox.com/docs/cloud/auth/api-keys。

x-api-key

表示 Roblox 用戶身份的瀏覽器 Cookie。請勿分享此物。分享此物會允許他人以您的身份登錄，並竊取您的 Robux 和物品。我們不建議使用 Cookie 來調用端點。在可能的情況下，請改用帶有 x-api-key 標頭的 API 密鑰或 OAuth 2.0 進行身份驗證。

.ROBLOSECURITY

構建或授權應用程序以訪問 Roblox 資源。詳細信息請參見 https://create.roblox.com/docs/cloud/auth/oauth2-overview。

Roblox API。詳情請參見 https://create.roblox.com/docs/cloud/open-cloud。

Roblox API

創建一個新的 `LuauExecutionSessionTaskBinaryInput`。

universe_id

創建 Luau 執行會話任務二進制輸入

LuauExecutionSessionTaskBinaryInput

universe.place.luau-execution-session:write

Creates a task but does not wait for the task to complete.

To check whether a task has
completed, call the `GetLuauExecutionSessionTask` method and inspect the
`state` field of the returned resource.

Quotas:
* 5 calls per minute per API key owner
* 45 calls per minute per IP address

place_id

LuauExecutionSessionTask

version_id

Gets information about a task.

Quotas:
* 45 calls per minute per API key owner or IP address

luau_execution_session_id

task_id

檢索 Luau 執行會議任務的視圖。

支持 BASIC 和 FULL。

默認為 BASIC。

可能的值：

  | 值 | 描述 |
  | --- | --- |
  | VIEW_UNSPECIFIED | Luau 執行會議任務視圖未指定；將使用默認值。 |
  | BASIC | 排除 `script` 欄位。 |
  | FULL | 包括所有欄位。 |

view

universe.place.luau-execution-session:read

列出由 `LuauExecutionSessionTask` 生成的日誌區塊。

配額：
* 每個 API 金鑰擁有者或 IP 地址每分鐘 45 次調用。

返回的 Luau 執行會議任務日誌的最大數量。服務可能返回少於此值的日誌。如果未指定，最多返回 10000 條日誌。最大值為 10000，超過的值將設置為 10000。

maxPageSize

從先前調用中接收的頁面令牌，用於檢索後續頁面。

當進行分頁時，所有提供給後續調用的其他參數必須與提供頁面令牌的調用相匹配。

pageToken

檢索 Luau 執行會議任務日誌的視圖。

支持 FLAT 和 STRUCTURED。

默認為 FLAT。

可能的值：

  | 值 | 描述 |
  | --- | --- |
  | VIEW_UNSPECIFIED | Luau 執行會議任務日誌視圖未指定；將使用默認值。 |
  | FLAT | 如果選擇此視圖，`messages` 欄位將會填充（並且 `structuredMessages` 欄位不會）。`messages` 陣列中的每一項僅包含日誌消息，而沒有其他元數據。這是默認情況。 |
  | STRUCTURED | 如果選擇此視圖，`structuredMessages` 欄位將會填充（並且 `messages` 欄位不會）。`structuredMessages` 陣列中的每一項包含日誌消息及其他元數據（詳細信息請參見 `LogMessage`）。 |

LuauExecutionSessionTaskLog

Luau Execution

体验

虚拟形象

素材

范例和项目

引擎 API

Open Cloud API

Studio

分析

平台

教程

创作者计划

教育

课程

学习

此方法是异步的，会返回一个`Operation`对象，该对象表示操作的当前状态。它包含一个端点路径，您可以轮询该路径以获取实际响应和相关的元数据。有关长时间运行操作的更多信息，请参阅[文档]({longRunningOperationsLink})。

以下部分描述了操作完成时提供的响应和元数据对象。

Beta 测试终点已准备好公开使用。可能出现导致功能无法正常运作的更改，但几率极低。

这些 Open Cloud 文档页面将于 2026 年 3 月 31 日移除。届时你将被自动重定向到新的 Open Cloud 文档。{linkStart}了解更多{linkEnd}

这些旧 Open Cloud 页面将于 2026 年 3 月 31 日移除并重定向。{linkStart}了解更多{linkEnd}

实验性终端节点已准备好供公众使用，但随着 API 协定的最终确定，可能偶尔会出现重大变更。

此终端节点可通过使用 API 密钥的 {httpServiceLinkStart}HttpService{httpServiceLinkEnd} 在体验中调用。

此字段可能在创建资源时被设置，但可能无法在后续请求中修改。

这些字段可能在创建资源时被设置，但可能无法在后续请求中修改。

此字段可以在请求中提供，但永远不会包括在答复中。

旧版验证方法。始终首选使用 API 密钥或 OAuth 2.0（如有）。

每个 API 密钥：每个 IP 地址每 {periodInSeconds} 秒有 {maxInPeriod} 次请求

无需身份验证即可调用。通常会显著降低速率限制。始终首选使用 API 密钥或 OAuth 2.0（如有）。

对于每个分组，只需提供架构中的以下字段之一，其余字段可以排除。

你可以随时重新选择加入。{linkStart}提供反馈。{linkEnd}

你正在查看旧版文档。{linkStart}提供反馈。{linkEnd}

你可以随时退出，并重定向回旧的引用页面。{linkStart}在这里提供反馈。{linkEnd}

你正在查看全新改版的文档。{linkStart}提供反馈。{linkEnd}

此字段可能被设置为响应，但在请求中将被忽略。

注意：在高流量期间，速率限制可能会更低。某些终端节点有额外的速率限制。[进一步了解速率限制]({link})。

用户或群组所有 API 密钥每天 {limit} 个请求

用户或群组所有 API 密钥每小时 {limit} 个请求

用户或群组所有 API 密钥每分钟 {limit} 个请求

用户或群组所有 API 密钥每秒 {limit} 个请求

每个 API 密钥所有者每分钟 {limit} 个请求

每个 App 用户每天 {limit} 个请求

每个 App 用户每小时 {limit} 个请求

每个 App 用户每分钟 {limit} 个请求

每个 App 用户每秒 {limit} 个请求

每个 API 密钥所有者每秒 {limit} 个请求

范围可以控制你的凭据拥有哪些权限。你的凭据只能访问你所选范围支持的终端节点。

稳定终端节点已准备好投入生产使用，在其生命周期内几乎不会发生重大变更。

此目标允许你将密钥的访问权限限制为选定的{requiredParts}

此目标允许你将密钥的访问权限限制为选定的{requiredParts}和{optionalParts}

目标类型用于限制你的凭据可操作的资源。即使你的帐户拥有其他资源的权限，也只能处理选定的资源。某些范围没有目标部件，在这种情况下，你的所有相关资源都可进行操作。

对于用户拥有的 API 密钥，无需选择宇宙顶级部件。在这种情况下，你的 API 密钥可以访问你拥有的所有个人体验，以及你在群组中拥有相应权限的群组体验。

尚不支持试用需要 API 密钥或 OAuth 2.0 验证的终端节点

为了安全起见，已停用高风险操作的 Cookie 验证。

关键风险终端节点非常敏感，为了安全起见，已停用“试用”

注意：此代码示例中不包含验证标头。你可能需要添加验证标头，以便此命令能够正常运作。

这是会修改或删除关键数据的高风险终端节点。测试时要格外小心。

此 API 终端节点已被归类为高风险，可能会影响实时数据或用户帐户。

对高风险 API 的已验证请求可能会进行无法撤销的更改。请在继续之前仔细查看你的请求参数。

这是会取回数据的低风险终端节点。通常可以安全测试。

这是会修改数据的中风险终端节点。请使用非关键帐户仔细测试，因为更改可能是永久性的。

为了确保你帐户的安全，请不要在此处粘贴来自其他来源的文本，或将此页面的信息发送给其他人。

你即将使用实际帐户凭据测试实时 API 终端节点。

只有在你了解即将进行的 API 调用的影响后才能继续。在测试之前，请仔细查看 API 文档。

将使用已验证的会话进行 API 调用

这些是可能影响你帐户或数据的真实 API 调用

某些操作可能会修改或删除数据

此终端节点已被以下推荐的替代终端节点取代：

调用此终端节点需要以下范围。如需
有关生成正确密钥的更多信息，请参阅 [管理 API 密钥]({apiKeyReferenceDocLink})。

如需有关生成密钥的更多信息，请参阅 [管理 API 密钥]({apiKeyReferenceDocLink})。

相对于基础 URL 的路径，下列端点是可用的。

此字符串格式为 [FieldMask](/cloud/reference/types#fieldmask)。

JSON 值可以是 “null”、“boolean”、“string”、“number”、“array” 或 “object”。

你的 OAuth 2.0 应用程序需要以下范围才能使用此终端节点。如需进一步了解如何注册 OAuth 2.0 应用程序，请参阅 [App 注册和审核]({oauth2ReferenceDocLink})。

如需进一步了解如何注册 OAuth 2.0 应用程序，请参阅 [App 注册和审核]({oauth2ReferenceDocLink})。

下列对象描述了接受或返回的有效载荷。请参阅每个单独的端点，以了解更多关于这些对象用途的信息。

调用此终端节点需要以下范围。

资源路径

若要使用此端点，你的 OAuth 2.0 应用程序需要以下范围。关于如何注册 OAuth 2.0 应用程序的更多信息，请查看【应用程序注册及评价】({oauth2ReferenceDocLink})。

不推荐

你正在查看更新后的 Open Cloud 引用。

你已退出新的 Open Cloud 引用。

创建、更新和管理你的广告活动。

这将允许查看关于你素材的信息。

这将允许在 Roblox 上传或更新素材。

允许查看你的帐户有权访问的主体（包括群组和体验）和素材。

这将允许向你帐户有权访问的任何主体（包括群组和体验）和素材授予素材权限。

允许代表你查看虚拟形象自动设置任务的状态和结果。

允许代表你创建和管理虚拟形象自动设置任务。

授予更新用户拥有的徽章的能力。

这将允许查看有关你商业项目的信息。

这将允许更改你的同步商业项目。

这将允许查看有关你商户联结平台的信息。

这将允许编辑你的商户联结平台。

这将允许你查看关于你创作者商店产品的信息。

这将允许你修改关于你创作者商店产品的信息。

这将允许你查看关于你创作者商店保存的信息。

这将允许你修改关于你创作者商店保存的信息。

授予代表你创建数据存储的权限。

授予代表你删除数据存储的权限。

授予读取数据存储列表的权限。

授予拍摄数据存储快照的权限。

授予在数据存储中创建条目的权限。

授予标记要删除的指定条目的权限。

授予列出数据存储条目的权限。

授予读取数据存储中指定条目的权限。

授予更新条目的值、属性和用户的权限。

授予删除数据存储条目修订的权限。

授予列出数据存储条目修订的权限。

授予读取数据存储条目修订的权限。

授予查看授权用户的开发者产品配置详细信息的权限。

授予编辑授权用户的开发者产品的权限。

这将允许查看有关你宇宙环境的信息。

授予查看授权用户的游戏通行证配置详细信息的权限。

授予编辑授权用户的游戏通行证的权限。

授予查看你的帐户社区论坛信息的权限。

授予访问权限，允许管理你的帐户对应的社区论坛信息。

这将允许查看有关你社区的信息。

这将允许你管理社区加入请求，并处理你帐户中低级别社区成员的角色更新。

允许你修改实例的属性数据（目前仅支持脚本）。

这将允许查看你的道具栏信息。

授予权限，以管理你的徽章并使用 Robux。

授予更新授权用户徽章的权限。

授予读取你已开启通知的体验信息的权限。

授予代表你开启或关闭体验通知的权限。

授予读取和写入本地化表格的权限

授予为你拥有的所有体验管理团队协作的权限。

授予管理体验和与体验相关的某些信息（例如本地化信息）的权限。

授予读取体验本地化信息的权限。

授予修改体验本地化偏好设置的权限。

授予修改用户本地化偏好设置的权限。

允许你查看关联场景的 Luau 执行任务的状态、日志和结果。

允许你为关联场景创建新的 Luau 执行任务。

授予异步清空宇宙中所有数据结构的权限。

授予从队列前端丢弃已读项目的权限。

授予读取队列前端项目的权限。

授予读取记忆存储项目的权限。

授予创建、更新和删除地图项目的权限。

授予代替用户发布信息的权力。

这将允许从你的体验向用户发送通知。

（已弃用）授予读取有序数据存储中条目列表的权限。

（已弃用）授予在有序数据存储中创建新条目的权限。

授予从有序数据存储中列出条目的权限。

授予在有序数据存储中创建条目的权限。

这将允许列出与你的作品相关联的密钥。

这将允许创作和更新与你的作品相关联的密钥。

此权限允许你提交评估工作并查看工作结果。

授予读取订阅产品信息的权限。

授予在 Roblox 上发布新版本体验的权限。

授予编辑授权用户体验的权限。

允许你查看体验中的用户限制。

允许你编辑体验中的用户限制。

允许查看发送至你帐户的通知。

授予读取用户 Premium 和验证状态的能力。

这将允许你查看授权用户的社交帐户。

这将授予读取你的个人资料信息的权限。

Luau Execution

Places