使用 Azure Functions 的 CloudScript 在原本使 CloudScript 出色的基础上进一步改进,支持更多语言并提供更好的调试工作流。
本教程演示 Unity 代码示例,但 CloudScript 在所有 SDK 中的工作方式类似。
- 已使用 PlayFab Unity SDK 设置好的 Unity 环境
- 已在
PlayFabSharedSettings对象中设置游戏 ID。 - 项目可以成功登录一个用户。
- 已在
入门:helloWorld
我们的helloWorld 示例适用于全新的游戏,无需在 Game Manager 中进行任何修改。新游戏的默认 CloudScript 文件包含一个名为 helloWorld 的处理程序。它使用了一些基本功能:输入参数、日志记录、currentPlayerId 和返回参数。
以下示例展示了默认的 helloWorld 函数代码(不含注释)。
剖析代码
handler 对象在 PlayFab CloudScript 环境中已预先定义。你应将任何 CloudScript 函数添加到此对象。-
helloWorld是可供你的游戏和 SDK 使用的函数,因为它是在 handler 对象中定义的。 -
args是来自调用方的一个任意对象。它由 JSON 解析而来,可以以任何格式包含任意数据。
-
Context是一个高级参数。在此示例中,它为 null。此参数由服务器控制,是安全的。 -
currentPlayerId是一个全局变量,被设置为发起此调用的玩家的 PlayFabId。此参数由服务器控制,是安全的。注意: 使用 ExecuteEntityCloudScript API 时,除非该实体的实体链中包含 MasterPlayerID,否则此参数为 null。 -
log.info:log是一个全局对象。它主要用于调试你的 CloudScript。log对象暴露以下方法:info、debug和error。本教程稍后有更多细节。 -
return:你返回的任何对象都会被序列化为 JSON 并返回给调用方。你可以返回任何可 JSON 序列化的对象,以及你希望的任何数据。
从 Unity 游戏客户端执行 CloudScript 函数
从客户端调用 CloudScript 函数很简单。你首先需要创建一个ExecuteCloudScriptRequest,并将 ActionId 属性设置为要执行的 CloudScript 函数的名称(在此为 helloWorld),然后通过我们的 API 将该对象发送到 PlayFab。
你只能调用附加到 handlers JavaScript 对象上的 CloudScript 方法。
剖析代码
ExecuteCloudScriptRequest 是任何对 PlayFabClientAPI.ExecuteCloudScript 调用的请求类型。-
ExecuteCloudScriptRequest.FunctionName是一个字符串。该值应与 CloudScript 中定义的函数名称匹配。在此为helloWorld。 -
ExecuteCloudScriptRequest.FunctionParameter可以是能够序列化为 JSON 的任何对象。它会成为helloWorld函数中的第一个 args 参数(参考上一节中的 args)。 -
ExecuteCloudScriptRequest.GeneratePlayStreamEvent是可选的。如果为 true,则会向 PlayStream 发布一个事件,你可以在 Game Manager 中查看,或用于其他 PlayStream 触发器。
ExecuteCloudScript 行的最后一部分涉及向 PlayFab CloudScript 服务器发出请求,以及处理特定于该语言的 Result 和 Error。
例如,在 Unity、JavaScript 或 AS3 中,错误和结果处理通过回调函数提供。
以下是错误处理方法的示例。
中级概览:全局对象和高级参数
CloudScript 是一组使用 V8 编译并托管在 PlayFab 服务器上的 JavaScript 函数。它可以访问在 PlayFab API 参考文档中列出的任何服务器 API,以及一个记录器、发起 CloudScript 请求的玩家 PlayFab ID,以及请求中包含的任何信息,所有这些都以预设对象的形式提供。 CloudScript 函数本身是全局 handlers 对象的属性。下表列出了这些预定义变量的完整列表。
此外,所有处理程序函数都会传入两个参数,详见下文。
可以通过
ExecuteCloudScript API 或通过预设的 PlayStream 事件操作调用 CloudScript 函数。
有关 ExecuteCloudScript 响应的完整详细信息,请参阅 ExecuteCloudScriptResult。
中级:FunctionParameter 与 args
在上一节中,我们描述了如何填充request.FunctionParameter,并在 args 参数中查看这些信息。CloudScript 快速入门演示了如何上传新的 CloudScript。
将这两者结合,我们可以再举一个从客户端向 CloudScript 传递参数的示例。以前面的示例为例,并按以下方式修改 CloudScript 代码和客户端代码。
需要指出,来自客户端的任何数据都容易受到黑客攻击和滥用。
中级:调用服务器 API
如前所述,在 CloudScript 方法中,你可以访问完整的一组服务器 API 调用。这使你的云代码可以充当专用服务器。 常见的服务器任务:- 更新玩家统计和数据。
- 授予物品和货币。
- 随机生成游戏数据。
- 安全地计算战斗结果等等…
高级:PlayStream 事件操作
可以配置 CloudScript 函数以响应 PlayStream 事件运行。- 在任意浏览器中:
- 访问 PlayFab Game Manager。
- 找到你的游戏。
- 在侧边栏的 Build 下,转到 Automation 选项卡。
- 转到 Rules 选项卡。
-
使用 New Rule 按钮创建一个新规则。
- 为新的规则指定名称。
- 选择将用作条件或操作触发器的 Event type。
- 若要使规则触发 CloudScript 函数,请在该部分中通过按钮添加一个 Action。
- 然后在 Type 下拉菜单中选择相应选项。
- 在 Cloud Script Function 下拉菜单中选择 helloWorld 函数。
- 选择 Save action 按钮。
-
现在此规则已设置为在你所选类型的任何事件上触发。若要对其进行测试:
- 勾选 Publish results as PlayStream Event 复选框。
- 保存该 Action。
- 然后触发一个事件。
- 在 PlayStream Monitor 中应显示一个对应于 CloudScript 执行的新事件,其中包含相应信息。
- 有关在调试器中检查 PlayStream 事件的更多信息,请参阅高级:调试 CloudScript一节。
事件操作在调用 CloudScript 函数时只能使用生产版本(live revision)。如果你在下拉菜单中找不到 helloWorld 函数,这可能是最有可能的原因。
高级:调试 CloudScript
使用使用 Azure Functions 的 CloudScript 进行调试要容易得多。详细了解如何使用 Azure Functions 的 CloudScript 进行本地调试。
日志记录
调试代码最重要的工具之一是日志记录。我们的 CloudScript 提供了执行该功能的工具。 它以log 对象的形式提供,可以使用 Info、Debug 和 Error 方法记录任何期望的消息。
此外,如果将 logRequestAndResponse 参数设置为 true,HTTP 对象将记录它在发起请求过程中遇到的任何错误。虽然设置这些日志很简单,但访问它们需要一点技巧。
以下是使用全部 4 种日志类型的 CloudScript 函数示例。
ExecuteCloudScript 调用 logTest 函数。
GeneratePlayStreamEvent 后,CloudScript 函数调用会生成一个 PlayStream 事件,其中包含响应的内容。若要查找 PlayStream 事件的内容:
- 转到你游戏的 Game Manager 主页,或其 PlayStream 选项卡。
- PlayStream Debugger 会在事件到达时进行显示。
- 事件到达时,选择事件右上角的蓝色小 Info 图标,如下图所示。
-
如果我们将
LogScriptMonoBehavior 添加到场景中,运行游戏将在 PlayStream 中产生以下结果。
ExecuteCloudScript 调用的结果包含一个名为 Logs 的字段,它是 CloudScript 函数生成的日志对象列表。
你可以看到这三个日志调用,以及来自无效 HTTP 请求的日志。与 log 调用不同,HTTP 请求日志还使用了 Data 字段。
此字段是一个 JavaScript 对象,可以由与日志语句相关的任何信息填充。log 的调用也可以通过第二个参数使用此字段,如下所示。
Data 字段。
由于日志包含在结果中,客户端代码可以根据日志语句做出响应。logTest 函数中的错误是被强制触发的,但客户端代码可以进行调整以对其做出响应。
高级:错误
在开发中,CloudScript 错误通常不会像log.error 那样手动触发。
幸运的是,ExecuteCloudScript 的响应包含一个 ExecuteCloudScriptResult,其中包括一个 ScriptExecutionError 字段。将日志记录部分中的最后一个示例进行调整,我们可以按如下方式使用它。
