跳到主要内容
Data 与 Schema

本页尚未翻译,当前显示英文版本。

写入 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 中完成修改。
PlayServRecordConflictExceptionStaleVersion:有人先保存了该 Record。否则就是某个 Unique 字段已存在该值,此时 Kind 为 Unknown。重新加载后再保存;或者换一个值。
PlayServRecordNotFoundExceptionRecord 已被删除,或属于另一个 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日