本页尚未翻译,当前显示英文版本。
Cloud Function 与 RPC
把关键规则留在服务器上:游戏只发出请求,由服务器代码做决定。 服务端逻辑是一个 Cloud Function 或一个 Game server,各自独立部署。游戏用 PlayServCode.CallAsync 调用 Cloud Function 并得到强类型结果;用 PlayServRpc.InvokeAsync 调用正在运行的 Game server。
using Playserv.Wrapper;
using UnityEngine;
var result = await PlayServCode.CallAsync<ClaimReward, RewardGranted>(
"claim-match-reward", new ClaimReward { MatchId = matchId });
if (result.IsSuccess)
Debug.Log($"+{result.Value.Coins} coins");
else
Debug.LogWarning(result.Error.SourceCode);
选择调用方式
PlayServCode.CallAsync | PlayServRpc.InvokeAsync | |
|---|---|---|
| 调用目标 | 已部署的 Cloud Function | 按名称指定的 Cloud Function 或 Game server |
| 传输方式 | 单独的请求 | SDK 保持的长连接 |
| 适用场景 | 请求-响应:领取奖励、购买物品、校验操作 | 调用正在运行的 Game server |
| 版本 | 可以调用带标签的版本 | 不能选择版本 |
如果只是读写自己的数据,两者都不需要:请使用 Record。
调用 Cloud Function
部署 Function
编写 Function 并用 CLI 部署,参见使用 CLI 部署。它的 slug,例如 claim-match-reward,就是游戏调用时使用的名称。
允许游戏调用
Function manifest 中的 execute 设置必须允许来自客户端的调用。如果它的认证要求 Player,游戏必须已登录。参见 Functions → Settings。
调用
CallAsync<TRequest, TResponse>(slug, body) 把 body 以 JSON 发送,并把响应读取为 TResponse。CallAsync<TResponse>(slug) 则不带请求体调用。
选项(PlayServFunctionCallOptions) | 作用 |
|---|---|
Version | 调用某个带标签的版本,而不是最新版本。标 签不存在时以 function_version_not_found 失败,不会回退到最新版本。 |
TimeoutSeconds | 游戏等待的时长。平台最多等待 Function 60 秒,因此设置更长的超时没有意义。 |
Query · Headers | 查询参数和自定义请求头。 |
StrictResponseTypes | 响应与 TResponse 不匹配时直接失败,而不是尽量填充能填的字段。 |
CallAsync 总是发送 POST 请求。如需其他方法或原始请求体,请使用 PlayServCode.InvokeAsync(new PlayServFunctionRequest { … })。InvokeBytesAsync 和 DownloadToFileAsync 返回二进制响应;WebGL 中不支持下载到文件。
识别调用者
SDK 每次调用都会附带已登录 Player 的会话。平台校验会话后把 Player 传给你的 Function,因此 Function 知道是谁在调用。在 C# Function 中,它是 Caller.PlayerId,另有 Caller.IsPlayer 和 Caller.IsAnonymous。
永远不要信任请求体中的 Player ID
任何人都可以在请求体中放入任意 ID。请以平台传入的调用者为准确定 Player,并按你的规则校验游戏发来的每个值。
调用 Game server(RPC)
using Playserv.RPC;
using Playserv.Wrapper;
PlayServRpcResult<RoundPreview> preview = await PlayServRpc.InvokeAsync<PreviewRequest, RoundPreview>(
"arena", "round.preview", new PreviewRequest { Round = 3 }); // sent as "Round": names must match the handler's parameters, case included
InvokeAsync(service, method, request) 通过游戏的连接发送调用。服务名是某个已部署的 Function 或 Game server 的名称:PlayServ 会把它转换为 kebab-case,并去掉末尾的 Service,因此 "Arena" 和 "ArenaService" 都会到达 arena。方法名会原样传给目标。
| 细节 | 取值 |
|---|---|
| 超时 | 默认 30 秒;可通过 PlayServRpcInvokeOptions.Timeout 另行设置。通过 RPC 调用的 Cloud Function 必须在 20 秒内响应。 |
| 结果 | IsSuccess、Value 和 Error。超时和失败都在结果中返回,而不是作为异常抛出:Error.Code 为 Timeout、ServerError 等,UnifiedError.SourceCode 给出平台的具体原因。 |
| 不等待响应 | PlayServRpc.Invoke(service, method, payload) 发送调用后不等待响应。 |
| 带 Room 的 Game server | 只有参与其某个进行中 Room 的 Player 才能调用它。 |
Unity Game server 通过注册在 PlayServServerRpcRegistry 中的处理器响应 RPC,参见 Game server 托管。
Function 调用的错误与限制
对于 CallAsync,错误在 result.Error 中返回;Error.SourceCode 说明发生了什么,Error.Retryable 表示重试是否有用。只有参数错误、缺少客户端密钥和取消操作会抛出异常。
SourceCode | 何时出现 |
|---|---|
not_found | 当前 Project 和 Environment 中没有该 slug 的 Function。 |
function_version_not_found | Version 标签不存在。 |
function_execute_forbidden | 该 Function 不接受来自游戏的调用。 |
player_auth_required | 该 Function 需要已登录的 Player。 |
function_unreachable | Function 没有在 60 秒内响应,或已停止运行。 |
function_response_too_large | 响应超过 16 MiB。 |
function_transport_failed | 网络故障。可重试。 |
其他任何状态都来自你的 Function 本身,响应体在 result.Response 中。
让发放奖励的调用可以安全重复
超时并不代表 Function 没有执行:它可能在游戏停止等待之后才完成。对于发放东西的调用,请传入这次操作的 ID,例如比赛 ID,让 Function 忽略带有相同 ID 的第二次调用。
后续步骤
更新于 2026年10月22日