文档

支持

Cloud Code

Open Unity Dashboard

Cloud Code

脚本结构

Understand the structure of a Cloud Code script and how the main function acts as the entry point.
阅读时间5 分钟最后更新于 3 天前
Cloud Code 脚本中用作运行时入口点的主函数采用 CommonJS 包装器的形式。 以下代码片段显示了可能最简单的脚本： JavaScript 
module.exports = async ({ params, context, logger }) => {  // this script does nothing};
虽然此脚本实际上不执行任何操作，但显示了脚本函数的上下文对象和异步性质。

上下文对象

上下文对象包含以下有用的对象： 
  • Params
    ：此对象是调用脚本时使用的输入参数的名称/值对数组。     
  • Context
    ：此对象提供在脚本中很有用的其他上下文：     
    • projectId
      ：调用方通过身份验证的 Project ID。
    • playerId
      ：经过身份验证的玩家 ID。
    • accessToken
      ：这是可用于以经过身份验证的玩家身份调用其他 Unity 游戏服务 SDK 的 JWT。
    • environmentName
      ：当前使用的 Unity 环境的名称。
    • environmentId
      ：当前使用的 Unity 环境的 ID。
    • serviceToken
      ：这是用于以经过身份验证的 Cloud Code 用户身份调用其他 Unity 游戏服务 SDK 的 JWT。
    • unityInstallationId
      ：用于标识客户端设备上的安装的唯一标识符。如果同一玩家在不同的设备上安装了游戏，则会拥有不同的 
      installationId
      。此信息可供与 Services SDK Core 包集成的所有 Unity 包使用。
    • analyticsUserId
      ：这是一个标识玩家身份并具有唯一性的字符串，在玩家后续游戏会话中保持不变，用于分析用途。此标识符是主要用户标识符，来自 Core 包。
    • correlationId
      ：用于关联请求的唯一标识符。
  • Logger
    ：此对象可以让脚本记录信息、警告和错误。

JavaScript

module.exports = async ({logger}) => {  logger.info('This message confirms that the logging client is functional!');  logger.warning('This is a serious warning that the cheese is about to run out.');  logger.error('Out of cheese :(');}
请参阅 Logging 文档了解更多信息。

令牌身份验证

accessToken
和 
serviceToken
是作为 
context
对象的属性提供的 JWT。 这些令牌对 Cloud Code 的其他 Unity Gaming Services（Unity 游戏服务）调用进行身份验证。

令牌类型

来源

数据访问

用途

accessToken
由 Authentication 服务生成仅限经过身份验证的玩家
accessToken
是用于对 Cloud Code 调用进行验证的 JWT。此令牌可以传递给其他 UGS 服务来访问经过身份验证的玩家的数据。
serviceToken
由 Cloud Code 生成允许访问跨玩家数据
serviceToken
是 Cloud Code 生成的令牌，可用于调用其他 UGS 服务并处理跨玩家数据。
配置的访问控制规则会影响 
accessToken
。 以下示例说明了如何使用 
accessToken
调用 Economy SDK 来获取玩家背包。

JavaScript

// Player inventoryconst { InventoryApi } = require("@unity-services/economy-2.4");module.exports = async ({params, context, logger}) => { const { projectId, playerId, accessToken } = context; const inventory = new InventoryApi({accessToken}); const result = await inventory.getPlayerInventory({projectId, playerId}); return result.data;}
如果要使用 
serviceToken
，同样的脚本将如下所示：

JavaScript

// Player inventoryconst { InventoryApi } = require("@unity-services/economy-2.4");module.exports = async ({params, context, logger}) => {const { projectId, playerId } = context;const inventory = new InventoryApi(context);const result = await inventory.getPlayerInventory({projectId, playerId});return result.data;}
如需了解这两个令牌之间差异的深入说明，请参阅服务和访问令牌。

脚本参数

脚本参数可以在脚本正文外部或内部定义。

脚本内参数

添加脚本内参数的方法是导出 
params
对象，此对象中包含每个参数名称作为键，参数类型作为值。 例如：

JavaScript

module.exports.params = { "echo" : "Boolean" }
或者，如果要指定某个参数为必需参数，可以指定一个同时包含 
type
和 
required
属性的对象。

JavaScript

module.exports = async ({ params, context, logger }) => {    return {        "value": params["aParam"]    };};module.exports.params = { "aParam" : { "type": "String", "required": true } }
默认情况下，参数不是必需参数。 两种格式可以根据需要组合使用：

JavaScript

module.exports = async ({ params, context, logger }) => {    var value = params["echo"] ? params["aParam"] : "default";    return {        "value": value    };};module.exports.params = {  "echo" : "Boolean",  "aParam" : { "type": "String", "required": true } }

async/await

主脚本函数可以是异步函数。这意味着函数可以等待承诺，从而允许在脚本中使用其他 Unity 游戏服务 SDK。请查看 Mozilla 文档中对承诺的描述。 一个简单的示例如下所示：

JavaScript

// Player inventoryconst { InventoryApi } = require("@unity-services/economy-2.4");module.exports = async ({params, context, logger}) => { const { projectId, playerId } = context; const inventory = new InventoryApi(context); const result = await inventory.getPlayerInventory({projectId, playerId}); return result.data;}

其他包

脚本可以导入带有 
import
或 
require
关键字的本地脚本或外部包。 如需查看可导入内容的完整列表，请参阅可用包。

JavaScript

const _ = require("lodash-4.17");module.exports = async () => {  return _.random(1, 6);};

捆绑

脚本捆绑是在 Unity 编辑器中使用 Deployment 包启用的一项功能，可帮助在本地管理脚本、解锁其他工作流程，以及允许在多个脚本之间共享通用功能。如需详细了解如何生成捆绑的脚本，请参阅 JS 捆绑包文档。

JavaScript

const lib = require("./lib");module.exports = async () => {  return lib.helloWorld();};module.exports.bundled = true;

输出

脚本输出可以包含以下类型：

JavaScript

  • string
    module.exports = async () => {  return "hello world";};
  • boolean
    module.exports = async () => {  return true;};
  • number
    module.exports = async () => {  return 3.14;};
  • object
    module.exports = async () => {  return {    message: "hello world",    success: true  };};
成功响应以 JSON 格式从 API 返回，结构如下： 
{  "output": <SCRIPT OUTPUT>}

错误输出

当某些原因（例如，服务请求失败）导致调用失败时，脚本可能会抛出错误。 在脚本中捕获错误可以确定应如何处理失败。

JavaScript

module.exports = async ({logger}) => {  try {    let result = service.call("example");    return result;  } catch (err) {    logger.error("Something went wrong!", {"error.message": err.message});    throw err;  }};
错误响应以 JSON 格式从 API 返回，并提供错误详细信息，包括错误类型、错误消息以及旨在帮助确定错误原因的堆栈跟踪。 
{  "type": "problems/invocation",  "title": "Unprocessable Entity",  "status": 422,  "detail": "Invocation Error",  "instance": null,  "code": 9009,  "details": [      {          "name": "ReferenceError",          "message": "service is not defined",          "stackTrace": [              "at module.exports (example-test.js:1:26)"          ]      }  ]}