实体编程模型

实体是 PlayFab API 操作的最基本的可寻址”事物”。每个实体都有一个 Type 和一个 Id，它们共同唯一地标识它。某些类型的实体是”标准”或”内置”的，因为 PlayFab 了解它们的含义和/或会自动创建它们，例如 namespace、title、group、master_player_account 和 title_player_account。其他类型可能对 PlayFab 没有固有含义，但在你的游戏中具有含义。 每个实体都有一个个人资料，其中包含该实体拥有的各种资源。例如，对象、文件、语言设置、策略和即将推出的其他资源。使用 GetProfile API 直接检索实体个人资料，许多其他 API 对个人资料内部的特定资源进行操作，例如 SetObjects。 最后，实体之间存在父/子关系，这些关系影响着允许其他实体访问某个实体资源的权限。可以在其个人资料的 Lineage 属性中找到给定实体的”祖先”。

​

与经典 API 的比较

有了这些基础，让我们看看”经典”API 和”实体”API 之间的差异。如果你正在使用经典 API，那么你已经在使用可以与实体 API 一起使用的相同实体，但它们并不总是显式的。例如，在 Client API 中，UpdateUserData 对 title_player_account 实体进行操作，GetUserPublisherData 对 master_player_account 进行操作，GetCharacterStatistics 对 character（是 title_player_account 的子级）进行操作，GetTitleData 对 title 进行操作，GetPublisherData 对 namespace 进行操作。 一般来说，每个经典 API 都对一种特定类型的实体进行操作，但实体类型通常是隐式的，不一定从 API 名称中体现出来。此外，两种类型实体的等效 API 在参数、限制和行为方面可能存在微妙差异（例如，UpdatePlayerStatistics 与 UpdateCharacterStatistics）。如果你对此感到困惑，你并不孤单。我们希望在不破坏与现有 API 集兼容性的情况下简化 PlayFab API，这将我们引向…… “实体 API” 就是我们对较新的 PlayFab API 的称呼，它们遵循以下设计目标（有一些例外）。

• 与任意类型的实体一起工作。
• 具有实体 Type 和 Id 的显式参数。
• 对实体个人资料中的特定资源执行特定操作。
• 可以在多种安全上下文中调用，例如从游戏客户端、游戏服务器、Cloud Script、后端服务器等，权限由策略定义并根据调用 API 的实体选择。

我们相信，遵循这些原则将带来更少但功能更多的 API，它们更易于维护和运行，也更容易让开发者学习。基本上，这就是我们在了解开发者过去五年如何使用 PlayFab 的所有知识后，从零开始设计 PlayFab API 时会采用的方式。当然，PlayFab 最重要的原则之一是尽可能地不破坏已上线的游戏，这意味着我们必须保持与所有已发布 API 的向后兼容性。

​

经典 API 用户的注意事项

为了在保持兼容性的同时实现我们的设计目标，我们通常将这些实体 API 作为一组单独的 API 引入，与经典 API 并存。虽然实体 API 可以与经典 API 处理相同的实体，但在大多数情况下，它们对这些实体拥有的一组独立的资源/数据进行操作。例如，SetObjects 实体 API 和 UpdateUserData 经典 API 都可以在 title_player_account 实体下存储数据，但两个 API”看到”的数据是分开的。以下是一些实际含义：

​

不利的一面

• 如果你的游戏已经将经典 API 用于玩家（也称为 title_player_account）的数据、库存等，那么现有数据不会自动出现在等效的实体 API 中。
• 实体 API 达到与经典 API 功能对等需要一些时间。数据在大多数情况下是分开存储的，需要许多后端更改来支持它们。可能有一些经典功能永远不会进入实体 API。

​

有利的一面

• 你无需执行任何操作。如果你的游戏已经在 PlayFab 经典 API 上运行良好，它将继续正常工作。
• 你可以开始使用实体 API，同时继续在同一组实体上使用经典 API。在某些情况下，这样做有明显的好处，成本很低，例如，为游戏添加一项新功能，除了存储在经典”玩家数据”中的现有设置外，还将大量数据保存在文件中。

​

功能概述

实体编程模型是 PlayFab 下一代数据和游戏服务的基础。

• 身份验证
• 个人资料
• 组
• 数据 - 文件
• 数据 - 对象
• 事件
• CloudScript
• 多人游戏

​

支持的实体类型

以下列表描述了可用的实体类型，可用于构造 EntityKey。实体键用于在大多数较新的 API 方法中标识实体。 这些值旨在用于 EntityKey.Type 字段。

​

namespace

namespace 是指工作室内每个游戏的所有全局信息的单个实体。此信息应是静态的。对此实体的更改不会实时反映。 将 ID 字段设置为你的 GamePublisherId。要检索你的 GamePublisherId：

• 登录 Game Manager。
• 从 My Studios and Titles 页面中，选择相应的游戏。
• 选择游戏页面左角的齿轮图标，然后选择 Title Settings。
• 选择 API Features 选项卡。

API Features 页面上的 Publisher ID 就是你的 GamePublisherId。

​

title

title 是指该游戏所有全局信息的单个实体。此信息应是静态的。对此实体的更改不会实时反映。 将 ID 字段设置为你的游戏的 TitleId。要检索你的 TitleId：

• 登录 Game Manager。
• 在 My Studios and Titles 页面上找到你的游戏。

游戏 ID 位于游戏名称正下方。

​

master_player_account

master_player_account 是在工作室内所有游戏之间共享的玩家实体。 将 ID 字段设置为经典 API 中的 PlayFabId，由任何 LoginResult.PlayFabId 返回。

​

title_player_account

对于大多数开发者来说，title_player_account 以最传统的方式表示玩家。 将 ID 字段设置为 Client API 中的 LoginResult.EntityToken.Id 或身份验证 API 中的 GetEntityTokenResponse.Entity.Id。

​

character

character 是 title_player_account 的子实体，是经典 API 中角色的直接镜像。 将 ID 字段设置为 result.Characters[i].CharacterId 中的任何 characterId。

​

group

group 是一个包含其他实体的实体。它目前仅限于玩家和角色。 如果你正在创建一个组，将 ID 字段设置为 result.Group.Id，或者在列出你的成员资格时设置为 result.Groups[i].Group.Id。

​

game_server

game_server 实体是游戏服务器主要用于匹配和大厅功能的唯一实体。将来可能会添加其他 PlayFab 功能的支持场景。 此实体为游戏服务器提供了自己的身份，这有助于唯一地识别它们，以便订阅匹配和大厅的实时更新，以及支持特定功能，如大厅所有者迁移。 要作为 game_server 实体进行身份验证，请以游戏实体身份调用 API AuthenticateGameServerWithCustomId 并检索 game_server 实体键和令牌对。将 PlayFab Multiplayer SDK 与 PFMultiplayerSetEntityToken 一起使用时，请使用此实体键。