跳到主要内容
Data 与 Schema

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

读取 Record

游戏通过 PlayServData.Records<T>() 以强类型 C# Record 的形式读取数据。 Schema 中的每个 Entity 都对应一个 C# 类;你可以按 ID 加载单个 Record,也可以用过滤、排序和分页查询多个 Record。示例使用 Sky Arena 的 Schema:Ships、Pilots、MatchResults 和单例 ArenaConfig。

using Playserv.Data;
using Playserv.Wrapper;
using UnityEngine;

var ships = PlayServData.Records<Ships>();

// One record by ID
PlayServRecord<Ships> ship = await ships.LoadAsync(shipId);
Debug.Log(ship.Value.Name);

// Ships up to 500, cheapest first, 20 per page
var page = await ships.QueryAsync(
    new PlayServRecordQuery<Ships>()
        .Where(s => s.Price <= 500)
        .OrderBy(s => s.Price),
    new PlayServPagination(limit: 20));

Entity 对应的 C# 类型

每个 Entity 都需要一个名称和字段都与之一致的 C# 类。 这些类可以从 Schema 生成,也可以自己编写。

方式做法
从 Schema 生成在 Tools ▸ PlayServ ▸ Settings 的 Schema Workflows 下选择 Import JSON & Generate。类文件写入 Assets/Shared/Generated/Models,每次生成都会覆盖。
自己编写普通 C# 类,无需基类。配合本地 Schema 工具,同样的类还可以用来定义 Schema,参见访问控制。
public class Ships
{
    public string Name;
    public ShipClass Class;
    public Stats Stats;      // an included part
    public int Price;
}

public class Stats { public double Speed; public int Armor; public int Damage; }

public class Pilots
{
    public string Callsign;
    public int Level;
    public PlayServRecordRef<Ships> Ship;   // a relation
    public Loadout Loadout;
}
规则原因
类名与 Entity 名完全一致。Records<Ships>() 按类名查找 Entity。如果两者不同,请用 Records<T>("ent_…") 并传入 Entity 的 ID。
字段名与 Schema 完全一致,包括大小写。字段以 C# 名称发送。[PlayServField("name")] 可映射为其他名称,[PlayServIgnore] 可排除某个成员。
包含的 Part 是嵌套类或列表。它们存储在 Record 内部。
关联使用 PlayServRecordRef<T>(SDK 0.6.4 及以上),或像生成的类那样,用字符串保存目标的 ID。Record 只存储 ID;参见关联。

加载得到的 Record 类型为 PlayServRecord<T>:字段在 Value 中,Record 还带有 Id、Owner、CreatedAt 和 UpdatedAt。ID 永远不需要你自己设置,由 PlayServ 生成。


加载单个 Record

调用返回
LoadAsync(id)具有该 ID 的 Record。如果不存在,抛出 PlayServRecordNotFoundException。
LoadByNaturalKeyAsync(PlayServNaturalKey<T>.For(x => x.Name, "Falcon"))唯一字段为该值的 Record。该字段必须在 Schema 中标记为 Unique。
LoadManyAsync(ids)按 ID 加载多个 Record,顺序与请求一致,每个 ID 对应一个结果。
var falcon = await ships.LoadByNaturalKeyAsync(PlayServNaturalKey<Ships>.For(s => s.Name, "Falcon"));

查询

QueryAsync(query, pagination) 返回一页与 PlayServRecordQuery<T> 匹配的 Record。

方法作用
Where(x => …) · And(x => …)用 C# 条件过滤:==、!=、>、>=、<、<=、空值检查、&&,以及 list.Contains(x.Field)。
Where(x => x.Field, PlayServQueryOperator.…, value)用运算符过滤:Eq、Neq、Gt、Gte、Lt、Lte、In、Nin、Between、Contains、StartsWith、EndsWith、IsNull、IsNotNull、IsEmpty、IsNotEmpty,以及用于列表长度的 Count…。
OrderBy(x => …) · OrderByDescending(x => …)排序。
Search("text")对 Entity 做全文搜索。
SelectFields(...) · Hide(...)只加载部分字段,参见下文。
分页作用
new PlayServPagination(limit: 20)每页 Record 数:默认 50,最多 200。
page.Records · page.HasMore · page.NextCursor本页 Record、是否还有更多,以及下一页的游标:以 new PlayServPagination(page.NextCursor, 20) 的形式传入。
LoadAllAsync(query)自动逐页读取,默认最多 1000 条 Record;IsTruncated 表示是否还有剩余。

按名称过滤 Enum 字段

要按 Enum 字段过滤,请与取值的名称比较:Where("Class", PlayServQueryOperator.Eq, "Fighter")。对 Enum 使用 C# 条件,例如 x.Class == ShipClass.Fighter,可能匹配不到结果。


关联与 Part

Part 是 Record 的一部分:它们随 Record 一起加载,你可以用嵌套路径按其字段过滤,例如 .Where(s => s.Stats.Speed > 10)。

关联只存储目标的 ID。要获取目标 Record:

调用作用
await pilot.Value.Ship.LoadAsync()加载关联的飞船。如果它已不存在,返回 null,不会抛出异常。
在查询上使用 .Include(p => p.Ship)把关联的 Record 与本页一起加载:飞船的字段随后就在 pilot.Value.Ship.Value 中,无需额外调用。查询只能包含直接关联;实时 Record 可以包含嵌套关联。

只加载部分字段

SelectFields 只加载你列出的字段,Hide 则加载除这些之外的所有字段;两者只能选其一。这样加载的 Record 是部分 Record:IsPartial 为 true,在调用 ReloadAsync() 之前无法保存。

部分 Record 无法保存

SDK 会拒绝保存,并抛出 InvalidOperationException。请先重新加载 Record,或者不使用 SelectFields 加载。


单例

单例 Entity 只有一个 Record,用 GetSingletonAsync<T>() 读取:

PlayServSingleton<ArenaConfig> config = await PlayServData.GetSingletonAsync<ArenaConfig>();
int maxPlayers = config.Value.MaxPlayers;

单例没有 ID,不能删除,也不能订阅。


错误

异常何时出现
PlayServRecordNotFoundException没有具有该 ID 或自然键的 Record。
PlayServDataAccessDeniedException游戏无权读取该 Entity,参见访问控制。
PlayServQueryCapabilityException查询用到了该调用不支持的功能,参见实时 Record。
PlayServDataException其他所有情况:StatusCode、BackendCode 和 IsNetworkError 说明发生了什么。

Player 只能看到自己在 Player 所有的 Entity 中的 Record

对于归 Player 所有、读取权限为 Owner 的 Entity,查询只返回当前登录 Player 的 Record。参见 Player 所有的 Entity。


后续步骤

更新于 2026年10月21日