Skip to main content
本实体快速入门演示如何处理实体对象和实体文件。 有关从旧账户和数据系统迁移到 PlayFab 实体的信息,请参阅实体迁移信息

要求

  • PlayFab 开发者账户
  • 已安装的 Unity Editor 副本。有关安装 Unity Editor 的信息,请参阅 Unity 文档中的安装 Unity。你还可以使用 Visual Studio 功能安装程序安装 Unity 版本。
PlayFab Unity3D SDK 支持 Unity Editor 5.3 及更高版本。
  • 一个 Unity 项目。有关创建 Unity 项目的信息,请参阅快速入门指南
如果你不熟悉 Unity,最近的安装包为你提供了安装游戏创建演练的选项。你可以使用其中一个演练来创建一个用于以下快速入门的示例游戏。
  • PlayFab Unity3D SDK。
本文中的 C# 示例是为 Unity SDK 编写的。Unity SDK 使用事件驱动模型来处理非同步任务。要使用 C# SDK 运行示例代码,你必须修改代码以使用 async Task 模型。必须修改的方法在签名中的方法名称后附加 Async。例如,Unity SDK 中的 SetObject 在 C# SDK 中变为 SetObjectAsync。有关详细信息,请参阅使用 async 和 await 的异步编程

术语

实体是可以包含数据的任何 PlayFab 概念。内置的实体类型有:
  • title - title 包含对所有玩家可用的全局信息。这类似于 TitleData。它由游戏/应用程序的 title ID (TitleId) 标识。
  • master_player_account - 此实体 Type 允许你在命名空间内的多个游戏之间共享有关某位玩家的信息。它由玩家的 player ID (PlayFabId) 标识,该 ID 会作为任何登录或任何检索玩家账户信息的调用(例如 PlayFab Client API GetAccountInfo)的一部分返回。
  • title_player_account - 标识一个玩家账户,其中包含当前 title 的一些信息。这由 entity ID (EntityKey.Id) 标识,你可以在任何登录时在 EntityKey 对象上获得该 ID。
  • character - 标识玩家拥有的角色,其中包含你可以检索的信息。它由角色的 character ID (CharacterId) 标识。
有关内置实体类型的详细信息,请参阅可用的内置实体类型

实体初始化

要调用任何 Entity API,你必须获取实体 ID 和实体 Type。你使用 IDType 调用其他 Entity API 方法。这些是 EntityKey 对象的成员。 你通过调用任何登录方法(例如 LoginWithCustomID)来执行此操作。
你也可以通过调用 GetEntityToken 方法获取实体 ID 和实体 Type
从客户端调用时,这通常代表登录的玩家。从游戏服务器调用时,这代表你的 title。

实体对象

实体对象允许你读取和写入附加到实体的小型 JSON 可序列化对象。所有实体类型都支持 GetObjectsSetObjects 方法。 以下代码段显示了如何在 title_player_account 实体上设置和读取一个 Object 使用 SetObjects 方法在玩家或 title 上设置实体对象。
使用 GetObjects 方法检索玩家或 title 上的实体对象。

实体文件

实体文件允许你以任何格式读取和写入附加到实体的文件。 使用 GetFiles 方法检索实体文件。
使用 initiatefileuploads 方法启动向实体配置文件的文件上传。
使用 AbortFileUploads 方法中止向实体配置文件的挂起文件上传。
使用 FinalizeFileUploads 方法完成向实体配置文件的文件上传。实体系统不会将文件上传视为完成,也不会将任何更改反映给其他调用者,直到原子上传操作成功完成。
下面显示的示例演示了完整的实体文件循环,从登录、加载文件到上传新文件。 这些步骤如下:
  • 登录并检索实体 ID 和实体 Type
  • 初始化原子上传操作。
  • 上传所有文件。
  • 完成原子上传操作。
为简单起见,此示例一次保存一个文件,但可以以原子方式集合上传文件。 该示例假设你熟悉使用 Unity 3D 引擎。
每个文件操作需要许多步骤和多个 API 调用,因此不要尝试同时以多种方式访问同一文件。如果你非常小心,可能不需要锁定机制。如果你想做一些复杂的事情,你的锁定机制可能会复杂得多。

Game Manager 和实体

Game Manager 允许你为玩家操作对象和文件。玩家概览同时显示 title player 和 master player account 信息。 此外,文件和对象现在在 Players 选项卡中拥有自己的部分。

另请参阅

PlayFab 博客上的 Introducing Entities, Objects and Files
最后修改于 2026年8月13日