PlayFab Party 物件及其關聯

若要成功運用 PlayFab Party API 的強大功能和彈性，首先要了解其範圍中定義的下列重要物件：

• 裝置 - 在實體裝置上執行之遊戲的個別執行個體。只要正在使用 API，就會存在本機裝置。
• 使用者 - 個別已登入的玩家，更精確地說，是遊戲為了驗證和識別目的而提供給 PlayFab Party 的 PlayFab title_player_account 實體。一或多位使用者會與指定的裝置相關聯。
• 網路 - 遊戲為交換聊天或資料通訊而建立的安全集合，包含一或多個裝置及其授權的使用者。網路通常對應遊戲的多人遊戲工作階段或聊天隊伍概念。
• 端點 - 在網路中傳送和接收資料的抽象概念。端點可以代表裝置、使用者或任何所需的遊戲專屬概念。
• 聊天控制項 - 使用者的表示形式，專門用於在一或多個網路中設定、發出和指定語音及文字聊天的目標。

​

物件關聯

以簡化的概念階層而言，網路包含裝置，而裝置又包含使用者、選用的端點和選用的聊天控制項。例如： 雖然上述關聯圖很容易理解，但它其實並未完整描繪 PlayFab Party 的功能，單獨看待可能會造成誤解。實際上，Party API 支援裝置同時連線到多個網路。例如，您可能希望與一群好友長期保持通訊，而這群好友同時也會加入和離開與陌生人一起的其他較大型遊戲工作階段。考量這個更廣泛的案例，可以讓我們更清楚地掌握這些物件之間的關聯。 將裝置概念化為屬於網路可能感覺很直覺，但事實並非如此。更正確的理解是，裝置參與網路。因此，Party 程式庫在遇到特定執行個體時，無論是遠端或本機，都只會建立單一裝置 API 物件，不論它與您的本機裝置共用多少個網路。 例如，下圖顯示兩個網路，以及三個具有使用者、聊天控制項和端點的裝置。裝置 A 及其兩個聊天控制項 (含相關聯的使用者) 參與網路 1，而裝置 B 和 C 則各自以單一聊天控制項 (及相關聯的使用者) 同時連線到網路 1 和 網路 2。所有裝置都在其所連線的每個網路中建立了一或兩個端點： 在圖中，每個裝置都會看到這三個裝置及其聊天控制項各一個執行個體，因為它們彼此至少有一個共同的網路。裝置 A 只知道網路 1 中的端點 1-4，但裝置 B 和 C 也能看到它們在網路 2 中建立的端點 5-7。 如果裝置 C 改為只參與網路 2，而非兩個網路，則：

• 裝置 C 顯然無法在網路 1 中建立端點 4，也看不到端點 1-3。
• 裝置 C 不會知道只在網路 1 中的裝置 A 或其兩個聊天控制項。
• 裝置 A 同樣看不到只在網路 2 中的裝置 C 或其聊天控制項。

不過，裝置 B 仍然會看到所有裝置及其聊天控制項，因為它仍在兩個網路中。 因此，儘管裝置和聊天控制項位於與網路之間嚴格階層樹狀關聯的「外部」，但請務必注意，遊戲執行個體永遠不會在沒有隨附網路的情況下遇到遠端裝置或聊天控制項。如果本機和遠端裝置或聊天控制項至少有一個共同網路，遠端物件就可能是可見的。但如果沒有共同網路，就永遠不會建立遠端物件。

​

通用物件屬性

所有物件都有明確定義的存留期。本機遊戲執行個體會直接建立和終結每個物件，或使用只在遊戲選擇的時間範圍內發出訊號的標準化通知機制。後續主題將更詳細地說明如何使用通知。 所有 PlayFab Party API 物件也都支援自訂內容的概念，這只是一種在物件上儲存選用、僅限本機之「捷徑」指標或值的方式。自訂內容可讓您輕鬆地從 PlayFab Party 物件回到記憶體中對應的私人遊戲物件 (如果有的話)，而不需要執行沒有效率的查閱。這些值不會傳輸到遠端，因為指標值只對本機遊戲執行個體有意義。 最後，除了網路之外，上述所有物件都有一個特殊化的「Local」子物件，其中包含只有擁有該物件的本機裝置才能使用的方法和屬性。 例如，有一個基底 PartyEndpoint 物件用來代表任何本機或遠端端點，以及一個更具體的 PartyLocalEndpoint 物件，只有在該端點確實是由本機裝置建立時，才能透過 PartyEndpoint::GetLocal() 擷取。用於傳輸遊戲資料的 PartyLocalEndpoint::SendMessage() 方法就是在此公開，因為讓一個裝置能夠以某種方式從不同遠端裝置的來源端點傳輸資料是不合理的。 使用 C++ PlayFab Party 介面 (建議) 時，物件會以 C++ 類別執行個體的形式公開。使用一般 C 介面時，物件會以控制代碼值表示。

​

所有主要物件角色的詳細說明

1. 管理員 (PartyManager)
2. 網路 (PartyNetwork)
3. 裝置 (PartyDevice 和 PartyLocalDevice)
4. 使用者 (使用者實體識別碼和 PartyLocalUser)
5. 端點 (PartyEndpoint 和 PartyLocalEndpoint)
6. 聊天控制項 (PartyChatControl 和 PartyLocalChatControl)
7. 狀態變更 (PartyStateChange)

​

管理員

除了前面摘要說明的物件之外，PlayFab Party API 也公開了一個最上層的 PartyManager 單一物件。 此公用程式/組織物件主要用作開始使用其他物件的起點。例如，新的網路和本機使用者最初都是在管理員中建立。所有非同步作業完成和通知也都集中在此。最根本的是，PlayFab Party 程式庫本身是在管理員中於使用前初始化，並在不再需要時清除。

​

網路

PartyNetwork 物件代表由參與的裝置、其授權的使用者，以及任何隨附的端點或聊天控制項組成的安全集合。網路最初建立時是空的，但裝置會連線到網路，並將至少一位本機使用者驗證到網路中。沒有任何已驗證使用者的網路會在逾時後自動終結。 若要連線到網路，需要使用網路描述元來參考它們。網路描述元是大部分不透明的二進位結構，包含 PlayFab Party 在內部識別和找到網路所需的資訊。API 提供方法，可將結構序列化為適合 Web 服務的字串並加以還原，以便使用常見的社交平台邀請機制、PlayFab Matchmaking 或 PlayFab Party 本身範圍以外的其他外部會合機制，與其他裝置交換。 即使擁有網路描述元，對網路的存取也僅限於授權的使用者。此使用者授權是在建立網路期間，以及透過後續建立和撤銷邀請來完成，詳細資訊請參閱邀請與安全性模型主題。 遊戲可以選擇使用邀請，將進入權限制為只有使用者的好友，或防止惡意玩家加入網路。 裝置可以同時連線到多個網路。您可以在稍後的主題中深入了解是否以及如何使用多個網路。 可以對 PartyNetwork 物件執行的動作類型包括：將本機使用者驗證到其中、連線及列舉聊天控制項、建立及列舉端點，或取得整個網路的效能資訊。

​

裝置

PartyDevice 物件代表在實體裝置上執行之遊戲及其 PlayFab Party 程式庫程式碼的個別執行個體。大多數作業不會在 PartyDevice 物件本身上執行；它們是一種組織機制，用來定義哪些端點或聊天控制項屬於該遊戲執行個體，特別是對於同時支援多位本機使用者的平台和遊戲。例如，PlayFab Party 會使用這項關聯知識來最佳化遊戲資料和聊天的傳輸，即使裝置上有多個目標需要接收訊息，也只傳送一份訊息。 遠端 PartyDevice 物件是連線到網路並將使用者驗證到該網路的「副產品」。只有當與該裝置相關聯之有效且已驗證的遠端使用者，正參與本機裝置也已連線的網路時，才會建立這些物件。相對地，一旦不再符合此條件，這些物件也會被終結。 另一方面，只要 PlayFab Party 已初始化，本機遊戲執行個體就一律可以參考特殊化的 PartyLocalDevice 子物件。它永遠不會被明確建立或終結。

​

使用者

PlayFab Party 使用者是唯一的人類玩家，遊戲會為其執行 PlayFab 玩家登入，以取得 title_player_account 實體識別碼和權杖。 在 PlayFab Party API 中，遠端使用者僅以與聊天控制項相關聯 (並可選擇與端點相關聯) 的實體識別碼字串來識別。它們不會以專用物件表示。這是因為除了原始識別以及作為與其他物件相關聯的標籤之外，PlayFab Party 並沒有與任意使用者進行有意義互動的功能。 相反地，對於本機使用者則有明確的 PartyLocalUser 物件，因為遊戲負責管理其在 PlayFab Party 中的存留期。遊戲通常會在使用適用的登入方法成功登入該 PlayFab 玩家時建立 PartyLocalUser，並在該使用者登出時適當地終結 PartyLocalUser。對於支援多位本機玩家登入的平台和遊戲，應為每位玩家建立額外的 PartyLocalUser 物件。 PartyLocalUser 物件也很重要，因為它們是所有驗證的基礎。必須存在有效的本機使用者，才能建立新的網路或驗證進入網路。 授權使用者的詳細說明，請參閱涵蓋邀請與安全性模型的主題。 幾乎每項作業都需要提供或存在 PartyLocalUser，儘管在 PartyLocalUser 物件本身上執行的作業很少。 PartyLocalUser 物件是使用 PartyManager 物件建立的。只有其建立者可以明確終結它們。雖然它們在遠端裝置上沒有直接的物件表示形式，但如果擁有的裝置移除 PartyLocalUser 或與網路中斷連線 (無論是否正常中斷)，與其相關聯的聊天控制項和端點都將被終結。

​

端點

PartyEndpoint 物件是選用的，但對於使用它們的遊戲而言，它們是 PlayFab Party 資料通訊的核心。如同一般的網路通訊端，端點是一種抽象的定址機制，用於在網路中發出資料訊息或指定其目標。它們可以代表裝置、個別使用者，或任何您想要唯一識別以傳送和接收訊息的任意遊戲定義概念 (例如坦克單位)。 特殊化的 PartyLocalEndpoint 子物件適用於本機遊戲執行個體在網路中建立的端點。大部分的端點功能都位於此處。其 PartyLocalEndpoint::SendMessage() 會將遊戲資料承載從 PartyLocalEndpoint 傳輸至同一網路中的一或多個其他 PartyEndpoint 物件。它提供各種選項，用於選擇如何最妥善地處理網際網路封包遺失 (例如保證傳遞和/或順序)、控制低延遲與合併來自相同或其他本機端點之多則訊息以降低頻寬使用量之間的取捨，以及在連線品質不足以支援遊戲的傳送速率時做出反應。 除了本身作為資料訊息的來源或目的地之外，PlayFab Party 也會為每個 PartyEndpoint 物件指派一個 16 位元的端點唯一識別碼，讓您可以在傳送至網路中不同 PartyEndpoint 物件或從其傳送的訊息承載中參考特定的端點。例如，這提供了一種方便的方式，可避免傳送完整且較大的使用者實體識別碼字串或其可能代表之其他識別碼的額外負荷，而不必自行建立對等身分識別協議交涉。 PartyLocalEndpoint 物件是使用其所屬的 PartyNetwork 物件建立的。這樣做會在遠端裝置上建立對應的 PartyEndpoint 物件。端點可以由其建立者明確終結，或在擁有的裝置與網路中斷連線，或相關聯的 PartyLocalUser 物件 (如果有指定) 從網路中移除時被隱含終結。

​

聊天控制項

PartyChatControl 物件是使用 PlayFab Party 選用聊天通訊功能的機制。它們代表特定使用者相關聯的音訊輸入/輸出裝置、喜好設定和通訊原則。 本機遊戲執行個體建立的聊天控制項也可以使用特殊化的 PartyLocalChatControl 子物件。您可以在此設定允許與遠端 PartyChatControl 物件進行聊天通訊的權限，例如選擇整個網路聊天或僅限隊伍聊天，或套用平台原則限制。本機聊天控制項用於傳送聊天文字、將文字合成為語音、要求語音串流的轉譯和翻譯、靜音等功能。 PartyLocalChatControl 物件必須先連線到網路，才會在同一網路中的遠端裝置上建立為 PartyChatControl 物件。即使裝置和聊天控制項已連線到多個共同網路，裝置也一律只會看到建立的單一代表性 PartyChatControl 物件。這有助於避免音訊和文字聊天訊息不必要的重複或中斷。 PartyLocalChatControl 物件是使用其所屬的 PartyLocalDevice 物件建立的。聊天控制項可以由其建立者明確終結，或在擁有的裝置與網路中斷連線，或相關聯的 PartyLocalUser 物件從網路中移除時被隱含終結。

​

狀態變更

PartyStateChange 結構用來通知遊戲所有非同步作業完成、傳入訊息、更新通知和其他 API 相關事件。 為了簡化在時間無法預測的網際網路上處理複雜的多機器互動，PlayFab Party 保證除非是遊戲明確呼叫所致，否則不會修改其從 API 回報的任何狀態。但由於您仍然需要一種方式來了解遠端起始的作業或會修改本機狀態的非預期事件，PlayFab Party 和遊戲會透過一對特殊的方法 PartyManager::StartProcessingStateChanges() 和 PartyManager::FinishProcessingStateChanges() 進行合作。這些方法會在遊戲工作迴圈中方便處理此類更新的時間點呼叫。新事件會從 PartyManager::StartProcessingStateChanges() 以零個或多個 PartyStateChange 結構的陣列形式回報。遊戲處理完狀態變更後，會使用 PartyManager::FinishProcessingStateChanges() 傳回該陣列。 PartyStateChange 結構本身並不是完整的物件。它是一個基底標頭，需轉型為更詳細的結構，其中包含特定完成或通知類型的資訊、相關物件的指標，以及任何錯誤資訊。 後續主題將完整詳細地說明如何使用狀態變更。

​

後續步驟

• 了解 PlayFab Party 邀請與安全性模型
• 了解 PlayFab Party 如何與您的探索流程互動
• 深入了解 PlayFab Party 聊天通訊
• 了解如何在 PlayFab Party 中使用非同步作業和通知