> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 实体编程模型

> PlayFab 实体编程模型简介、EntityKey 标识符、个人资料，以及实体 API 与经典 PlayFab API 的比较。

实体是 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 下一代数据和游戏服务的基础。

* [身份验证](xref:titleid.playfabapi.com.authentication.authentication)
* [个人资料](xref:titleid.playfabapi.com.profiles.accountmanagement)
* [组](xref:titleid.playfabapi.com.groups.groups)
* [数据 - 文件](xref:titleid.playfabapi.com.data.file)
* [数据 - 对象](xref:titleid.playfabapi.com.data.object)
* [事件](/services/playfab/api-references/events)
* [CloudScript](xref:titleid.playfabapi.com.cloudscript.server-sidecloudscript)
* [多人游戏](xref:titleid.playfabapi.com.multiplayer.multiplayerserver)

### 支持的实体类型

以下列表描述了可用的实体类型，可用于构造 `EntityKey`。实体键用于在大多数较新的 API 方法中标识实体。

这些值旨在用于 `EntityKey.Type` 字段。

<Note>
  这些是*区分大小写*的。其他/自定义值当前*不会*工作。
</Note>

#### namespace

`namespace` 是指工作室内每个游戏的*所有*全局信息的单个实体。此信息应是静态的。对此实体的更改*不会*实时反映。

将 `ID` 字段设置为你的 `GamePublisherId`。要检索你的 `GamePublisherId`：

* 登录 [Game Manager](https://developer.playfab.com)。
* 从 **My Studios and Titles** 页面中，选择相应的游戏。
* 选择游戏页面左角的齿轮图标，然后选择 **Title Settings**。
* 选择 **API Features** 选项卡。

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

#### title

`title` 是指该游戏所有全局信息的单个实体。此信息应是静态的。对此实体的更改*不会*实时反映。

将 `ID` 字段设置为你的游戏的 `TitleId`。要检索你的 `TitleId`：

* 登录 [Game Manager](https://developer.playfab.com)。
* 在 **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 中角色](xref:titleid.playfabapi.com.client.characters.getalluserscharacters)的直接镜像。

将 `ID` 字段设置为 `result.Characters[i].CharacterId` 中的任何 `characterId`。

#### group

`group` 是一个包含其他实体的实体。它目前仅限于玩家和角色。

如果你正在创建一个组，将 `ID` 字段设置为 `result.Group.Id`，或者在[列出你的成员资格](xref:titleid.playfabapi.com.groups.groups.listmembership)时设置为 `result.Groups[i].Group.Id`。

#### game\_server

`game_server` 实体是游戏服务器主要用于匹配和大厅功能的唯一实体。将来可能会添加其他 PlayFab 功能的支持场景。

此实体为游戏服务器提供了自己的身份，这有助于唯一地识别它们，以便订阅匹配和大厅的实时更新，以及支持特定功能，如大厅所有者迁移。

要作为 `game_server` 实体进行身份验证，请以游戏实体身份调用 API [AuthenticateGameServerWithCustomId](xref:titleid.playfabapi.com.authentication.authentication.authenticategameserverwithcustomid) 并检索 `game_server` 实体键和令牌对。将 PlayFab Multiplayer SDK 与 [PFMultiplayerSetEntityToken](/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pfmultiplayer/functions/pfmultiplayersetentitytoken) 一起使用时，请使用此实体键。


## Related topics

- [PlayFab 在线运营管理文档](/zh-CN/services/playfab/live-service-management/index.md)
- [游戏服务器配置概述](/zh-CN/services/playfab/live-service-management/game-configuration/index.md)
- [实体组](/zh-CN/services/playfab/community/associations/groups/quickstart.md)
- [组排行榜](/zh-CN/services/playfab/community/leaderboards/group-leaderboards.md)
- [适用于 Postman 的 PlayFab REST API 集合快速入门](/zh-CN/services/playfab/sdks/postman/postman-quickstart.md)