> ## 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 相同的實體，只是它們不一定是明確的。例如，在用戶端 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 的稱呼，這些 API 遵循下列設計目標 (有一些例外)。

* 可搭配任意類型的實體使用。
* 具有實體 Type 和 Id 的明確參數。
* 對實體設定檔中的特定資源執行特定作業。
* 可在多種安全性內容中呼叫，例如從遊戲用戶端、遊戲伺服器、Cloud Script 和後端伺服器呼叫，其權限由原則定義，並根據呼叫 API 的實體來選取。

我們相信遵循這些原則，可以用更少的 API 完成更多工作，維護和操作更有效率，開發人員也更容易學習。基本上，如果我們重新開始，並運用過去五年來對開發人員如何使用 PlayFab 所學到的一切，這就是我們設計所有 PlayFab API 的方式。當然，PlayFab 最重要的原則之一是盡可能絕不破壞上線中的遊戲，這表示我們必須維持與所有已發行 API 的回溯相容性。

## 傳統 API 使用者的考量

為了在維持相容性的同時實現設計目標，我們通常會將這些實體 API 作為獨立的集合推出，與傳統 API 並存。雖然實體 API 可以搭配與傳統 API 相同的實體使用，但在大多數情況下，它們會操作這些實體所擁有的另一組資源/資料。例如，`SetObjects` 實體 API 和 `UpdateUserData` 傳統 API 都可以將資料儲存在 `title_player_account` 實體下，但兩個 API「看到」的資料是分開的。以下是一些實際影響：

### 缺點

* 如果您的遊戲已經針對玩家資料、庫存和其他資源 (也稱為 `title_player_account`) 使用傳統 API，這些現有資料不會自動出現在對等的實體 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)
* [事件](/zh-TW/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` 實體代表跨遊戲的玩家身分和共用資料範圍。根據預設，它涵蓋工作室中的每個遊戲。命名空間與工作室不同，工作室是一種管理分組。如需詳細資訊，請參閱 [PlayFab 概念](/zh-TW/services/playfab/get-started/concepts#studios-namespaces-and-titles)。

某些 API 使用較舊的用語 **publisher** 來表示此範圍。發行者識別碼 (Publisher ID) 用於識別命名空間。

<Note>
  此實體的變更不會即時反映。
</Note>

將 `ID` 欄位設定為您的 `GamePublisherId`。若要擷取您的 `GamePublisherId`：

* 登入 [Game Manager](https://developer.playfab.com)。
* 從 **My Studios and Titles** 頁面，選取適當的遊戲。
* 選取遊戲頁面左上角的齒輪圖示，然後選取 **Title Settings**。
* 選取 **API Features** 索引標籤。

**API Features** 頁面上的 **Publisher ID** 就是您的 `GamePublisherId` 和命名空間識別碼。

### title

`title` 實體代表限定於單一遊戲範圍的全域資訊。遊戲是針對某款遊戲或遊戲環境的獨立 PlayFab 資源。

<Note>
  此實體的變更不會即時反映。
</Note>

將 `ID` 欄位設定為您遊戲的 `TitleId`。若要擷取您的 `TitleId`：

* 登入 [Game Manager](https://developer.playfab.com)。
* 在 **My Studios and Titles** 頁面上，找到您的遊戲。

遊戲識別碼會顯示在您的遊戲名稱下方。

### master\_player\_account

`master_player_account` 是由命名空間中所有遊戲共用的玩家實體。

將 ID 欄位設定為傳統 API 中的 `PlayFabId`，此值由任何 `LoginResult.PlayFabId` 傳回。

### title\_player\_account

對大多數開發人員而言，`title_player_account` 以最傳統的方式代表玩家。

在用戶端 API 中將 `ID` 欄位設定為 `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` 實體是遊戲伺服器使用的唯一實體，主要用於 Matchmaking 和 Lobby 功能。未來可能會新增其他情境以支援其他 PlayFab 功能。

此實體為遊戲伺服器提供專屬的身分，有助於唯一識別遊戲伺服器，以便訂閱 Matchmaking 和 Lobby 的即時更新，並支援大廳擁有者移轉等特定功能。

若要以 `game_server` 實體進行驗證，請以 title 實體身分呼叫 API [AuthenticateGameServerWithCustomId](xref:titleid.playfabapi.com.authentication.authentication.authenticategameserverwithcustomid)，並擷取 `game_server` 實體索引鍵和權杖組。透過 [PFMultiplayerSetEntityToken](/zh-TW/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pfmultiplayer/functions/pfmultiplayersetentitytoken) 使用 PlayFab Multiplayer SDK 時，請使用此實體索引鍵。


## Related topics

- [PlayFab 即時服務管理文件](/zh-TW/services/playfab/live-service-management/index.md)
- [遊戲伺服器設定概觀](/zh-TW/services/playfab/live-service-management/game-configuration/index.md)
- [實體群組](/zh-TW/services/playfab/community/associations/groups/quickstart.md)
- [群組排行榜](/zh-TW/services/playfab/community/leaderboards/group-leaderboards.md)
- [適用於 Postman 的 PlayFab REST API 集合快速入門](/zh-TW/services/playfab/sdks/postman/postman-quickstart.md)