實體程式設計模型

實體是 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 新一代資料和遊戲服務的基礎。

• 驗證
• 設定檔
• 群組
• 資料 - 檔案
• 資料 - 物件
• 事件
• CloudScript
• 多人遊戲

​

支援的實體類型

下列清單說明可用來建構 EntityKey 的可用實體類型。在大部分較新的 API 方法中，實體索引鍵用於識別實體。 這些值用於 EntityKey.Type 欄位。

​

namespace

namespace 實體代表跨遊戲的玩家身分和共用資料範圍。根據預設，它涵蓋工作室中的每個遊戲。命名空間與工作室不同，工作室是一種管理分組。如需詳細資訊，請參閱 PlayFab 概念。 某些 API 使用較舊的用語 publisher 來表示此範圍。發行者識別碼 (Publisher ID) 用於識別命名空間。 將 ID 欄位設定為您的 GamePublisherId。若要擷取您的 GamePublisherId：

• 登入 Game Manager。
• 從 My Studios and Titles 頁面，選取適當的遊戲。
• 選取遊戲頁面左上角的齒輪圖示，然後選取 Title Settings。
• 選取 API Features 索引標籤。

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

​

title

title 實體代表限定於單一遊戲範圍的全域資訊。遊戲是針對某款遊戲或遊戲環境的獨立 PlayFab 資源。 將 ID 欄位設定為您遊戲的 TitleId。若要擷取您的 TitleId：

• 登入 Game Manager。
• 在 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 中的角色。 將 ID 欄位設定為 result.Characters[i].CharacterId 中的任何 characterId。

​

group

group 是包含其他實體的實體。目前僅限於玩家和角色。 如果您正在建立群組，請將 ID 欄位設定為 result.Group.Id；在列出您的成員資格時，則設定為 result.Groups[i].Group.Id。

​

game_server

game_server 實體是遊戲伺服器使用的唯一實體，主要用於 Matchmaking 和 Lobby 功能。未來可能會新增其他情境以支援其他 PlayFab 功能。 此實體為遊戲伺服器提供專屬的身分，有助於唯一識別遊戲伺服器，以便訂閱 Matchmaking 和 Lobby 的即時更新，並支援大廳擁有者移轉等特定功能。 若要以 game_server 實體進行驗證，請以 title 實體身分呼叫 API AuthenticateGameServerWithCustomId，並擷取 game_server 實體索引鍵和權杖組。透過 PFMultiplayerSetEntityToken 使用 PlayFab Multiplayer SDK 時，請使用此實體索引鍵。