本页尚未翻译,当前显示英文版本。
写入 Record
要修改 Record,只需编辑它的值并保存:PlayServ 只发送你改动过的字段。 用 CreateAsync 创建 Record,用 SaveAsync 保存,删除时可以逐个删除,也可以按过滤条件删除。示例使用 Sky Arena 的 Schema;C# 类型的写法见读取 Record。
using Playserv.Data;
using Playserv.Wrapper;
using UnityEngine;
var pilots = PlayServData.Records<Pilots>();
var pilot = await pilots.LoadByNaturalKeyAsync(PlayServNaturalKey<Pilots>.For(p => p.Callsign, "Falcon"));
pilot.Value.Level++;
await pilot.SaveAsync();
只有为 Entity 打开了 Client Write,游戏才能写入它,参见访问控制。
创建 Record
填写值
创建 C# 对象,并设置你需要的每个字段。对象的所有字段都会被发送,包括你没有设置的:未赋值的数字会以 0 发送,字符串以 null 发送。Schema 中的默认值只对你的类里没有的字段生效,因此像 Level = 1 这样的值要自己设置。
创建
CreateAsync 返回新的 Record,其中带有 PlayServ 为它分配的 ID。
var pilot = await pilots.CreateAsync(new Pilots { Callsign = "Falcon", Level = 1 });
Debug.Log(pilot.Id);在归 Player 所有的 Entity 中,新 Record 属于当前登录的 Player,pilot.Owner 就是该 Player 的 ID。为此,游戏必须以某个 Player 的身份连接,参见 Player 所有的 Entity。
要设置关联,请使用目标的 ID:Ship = new PlayServRecordRef<Ships>(shipId)。
保存更改
SaveAsync() 发送自加载或上次保存以来你修改过的顶层字段。修改过的 Part 或列表会整体发送。你没动过的字段在平台上保持原样,即使在此期间有人修改过它们。
每次保存都会检查 Record 自你加载以来是否被改动过。如果另一个 Player 或某个 Function 先保存了它,SaveAsync 会抛出 PlayServRecordConflictException,其 Kind = StaleVersion,并且不会写入任何内容。
冲突意味着有人先保存了
调用 ReloadAsync() 获取当前 Record,重新应用你的修改,再保存。ReloadAsync() 会丢弃你未保存的编辑:以平台上的版本为准。
确保 Record 只创建一次
| 调用 | 作用 |
|---|---|
LoadOrCreateAsync(key, () => new Pilots { … }) | 加载具有该自然键的 Record;如果不存在,就用你的工厂方法创建。WasCreated 告诉你是哪种情况。如果另一个客户端恰好同时创建了同一个 Record,该调用可能抛出 PlayServRecordConflictException;再调用一次即可加载到它。 |
UpsertByNaturalKeyAsync(key, value, mode) | 创建 Record,如果已存在则更新。使用 PlayServUpsertMode.Seed 时,已有 Record 保持不变;使用 Managed 时,更新你传入的字段。 |
var key = PlayServNaturalKey<Pilots>.For(p => p.Callsign, "Falcon");
var result = await pilots.LoadOrCreateAsync(key, () => new Pilots { Callsign = "Falcon" });
if (result.WasCreated) Debug.Log("Welcome, new pilot");
键所用的字段必须在 Schema 中标记为 Unique。
删除
| 调用 | 作用 |
|---|---|
record.DeleteAsync() | 删除一个已加载的 Record,前提是它自你加载以来没有被改动过。 |
DeleteByIdAsync(id) | 按 ID 删除 Record,无需先加载。 |
DeleteMatchingAsync(query, confirmation) | 一次调用删除所有与查询匹配的 Record:要么全部删除,要么一个都不删。 |
DeleteMatchingAsync 只接受 Where 和 Search。带过滤条件时传入 PlayServDeleteAllConfirmation.MatchingRecords,要清空整个 Entity 则传入 AllRecords。如果每个过滤条件都是对顶层数字、布尔、文本或 Enum 字段的简单比较,一次最多可删除 100,000 条 Record;使用 Search 或其他过滤条件时,最多 200 条。平台无法以这种方式执行的过滤条件会被拒绝。如果匹配的数量超过上限,或者某个匹配的 Record 仍被匹配范围之外的 Record 引用,则不会删除任何内容,并返回错误。
await PlayServData.Records<MatchResults>().DeleteMatchingAsync(
new PlayServRecordQuery<MatchResults>().Where(m => m.Score == 0),
PlayServDeleteAllConfirmation.MatchingRecords);
批量写入
| 调用 | 行数 | 全部成功或全部失败? |
|---|---|---|
BulkCreateAsync(values) | 1–200 | 是:只要有一行失败,就一行都不创建。 |
BulkUpsertAsync(rows, mode) | 1–200 | 是。每一行都是一个带自然键的 PlayServBulkUpsertRow<T>。 |
BulkSaveAsync(records) · BulkDeleteAsync(records) | 不限 | 否:每个 Record 单独保存或删除。 |
DeleteAllAsync(query, confirmation) | 默认最多 10,000 | 否。建议改用 DeleteMatchingAsync。 |
非原子的调用会为每个 Record 返回一个结果:请检查 IsSuccess、FailedCount 和 Items。
没有自增操作,也没有事务
保存时发送的是客户端手上的值,因此两个 Player 同时给同一个计数器加值,可能会丢失一次更新。除了上面的批量调用之外,也没有跨多个 Record 的事务。必须精确的修改,例如比赛结果或货币,请放在 Cloud Function 中完成。
安全重试
CreateAsync、BulkCreateAsync 和各个 upsert 调用都接受幂等键:一个你为这次写入自行生成的字符串,最长 128 个字符。如果用同一个键重试调用,例如在连接中断之后,Record 不会被创建两次。不传键时,SDK 每次调用都会生成一个新键,所以你自己发起的重试会创建第二个 Record。同一个键只能配合同一个值使用。
await pilots.CreateAsync(new Pilots { Callsign = "Falcon" }, idempotencyKey: writeId);
单例
像普通 Record 一样,编辑单例的值并保存:
var config = await PlayServData.GetSingletonAsync<ArenaConfig>();
config.Value.MatchDuration = 240;
await config.SaveAsync();
单例无需创建:第一次读取时,PlayServ 会用默认值创建它。单例不能删除。和其他写入一样,从游戏中保存单例需要为该 Entity 打开 Client Write。
写入被拒绝时
| 异常 | 何时出现 | 怎么办 |
|---|---|---|
PlayServDataAccessDeniedException | 该 Entity 的 Client Write 处于关闭状态。 | 打开它,或者在 Function 中完成修改。 |
PlayServRecordConflictException | StaleVersion:有人先保存了该 Record。否则就是某个 Unique 字段已存在该值,此时 Kind 为 Unknown。 | 重新加载后再保存;或者换一个值。 |
PlayServRecordNotFoundException | Record 已被删除,或属于另一个 Player。 | — |
PlayServDataException,BackendCode 为 acting_player_required | 在没有已登录 Player 的情况下写入 Player 所有的 Entity。 | 先以某个 Player 的身份连接。 |
PlayServDataException,校验错误 | 值不符合 Schema:BackendCode 为 unknown_field、missing_required_field、invalid_field_type 或 validation_failed。 | 对照 Schema 检查字段名和类型,包括大小写。 |
InvalidOperationException | 保存了部分 Record。 | 先重新加载它。 |
后续步骤
更新于 2026年10月21日