> ## 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 Party 物件及其關聯

> 了解網路、裝置、端點和聊天控制項等核心 PlayFab Party 物件，以及它們在即時聊天和資料通訊中的關聯方式。

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

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

## 物件關聯

以簡化的概念階層而言，[網路](#network)包含[裝置](#device)，而裝置又包含[使用者](#user)、選用的[端點](#endpoint)和選用的[聊天控制項](#chat-control)。例如：

<img src="https://mintcdn.com/microsoft-4404708b/U1LR64ZWxo45eXwl/images/playfab/multiplayer/networking/simplified-party-object-hierarchy.png?fit=max&auto=format&n=U1LR64ZWxo45eXwl&q=85&s=89ce170ff66049c4f7569d3f1acb3460" alt="簡化的 PlayFab Party 物件階層" width="479" height="422" data-path="images/playfab/multiplayer/networking/simplified-party-object-hierarchy.png" />

雖然上述關聯圖很容易理解，但它其實並未完整描繪 PlayFab Party 的功能，單獨看待可能會造成誤解。實際上，Party API 支援裝置同時連線到*多個*網路。例如，您可能希望與一群好友長期保持通訊，而這群好友同時也會加入和離開與陌生人一起的其他較大型遊戲工作階段。考量這個更廣泛的案例，可以讓我們更清楚地掌握這些物件之間的關聯。

將裝置概念化為*屬於*網路可能感覺很直覺，但事實並非如此。更正確的理解是，裝置*參與*網路。因此，Party 程式庫在遇到特定執行個體時，無論是遠端或本機，都只會建立單一裝置 API 物件，不論它與您的本機裝置共用多少個網路。

例如，下圖顯示兩個網路，以及三個具有使用者、聊天控制項和端點的裝置。*裝置 A* 及其兩個聊天控制項 (含相關聯的使用者) 參與*網路 1*，而*裝置 B* 和 *C* 則各自以單一聊天控制項 (及相關聯的使用者) 同時連線到*網路 1* *和* *網路 2*。所有裝置都在其所連線的每個網路中建立了一或兩個端點：

<img src="https://mintcdn.com/microsoft-4404708b/dqv53299jA1M-fNi/images/playfab/multiplayer/networking/party-objects-in-multiple-networks.png?fit=max&auto=format&n=dqv53299jA1M-fNi&q=85&s=e714ccc5a71d813a17fd1e15985773a8" alt="多個網路中的 PlayFab Party 物件" width="440" height="318" data-path="images/playfab/multiplayer/networking/party-objects-in-multiple-networks.png" />

在圖中，每個裝置都會看到這三個裝置及其聊天控制項各一個執行個體，因為它們彼此至少有一個共同的網路。*裝置 A* 只知道*網路 1* 中的*端點 1-4*，但*裝置 B* 和 *C* 也能看到它們在*網路 2* 中建立的*端點 5-7*。

如果*裝置 C* 改為只參與*網路 2*，而非兩個網路，則：

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

不過，*裝置 B* **仍然會**看到所有裝置及其聊天控制項，因為它仍在兩個網路中。

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

<Note>
  遊戲不需要同時連線到多個網路，也能成功使用 PlayFab Party。您可以在[後續的進階主題](/zh-TW/services/playfab/multiplayer/networking/concepts-multiple-networks)中深入了解是否以及如何使用多個網路。
</Note>

## 通用物件屬性

所有物件都有明確定義的存留期。本機遊戲執行個體會直接建立和終結每個物件，或使用只在遊戲選擇的時間範圍內發出訊號的標準化通知機制。後續主題將更詳細地說明如何使用通知。

所有 PlayFab Party API 物件也都支援*自訂內容*的概念，這只是一種在物件上儲存選用、僅限本機之「捷徑」指標或值的方式。自訂內容可讓您輕鬆地從 PlayFab Party 物件回到記憶體中對應的私人遊戲物件 (如果有的話)，而不需要執行沒有效率的查閱。這些值不會傳輸到遠端，因為指標值只對本機遊戲執行個體有意義。

最後，除了[網路](#network)之外，上述所有物件都有一個特殊化的「Local」子物件，其中包含只有擁有該物件的本機[裝置](#device)才能使用的方法和屬性。

例如，有一個基底 `PartyEndpoint` 物件用來代表任何本機或遠端[端點](#endpoint)，以及一個更具體的 `PartyLocalEndpoint` 物件，只有在該端點確實是由本機裝置建立時，才能透過 `PartyEndpoint::GetLocal()` 擷取。用於傳輸遊戲資料的 `PartyLocalEndpoint::SendMessage()` 方法就是在此公開，因為讓一個裝置能夠以某種方式從不同遠端裝置的來源端點傳輸資料是不合理的。

使用 C++ PlayFab Party 介面 (建議) 時，物件會以 C++ 類別執行個體的形式公開。使用一般 C 介面時，物件會以控制代碼值表示。

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

1. [管理員](#manager) (`PartyManager`)
2. [網路](#network) (`PartyNetwork`)
3. [裝置](#device) (`PartyDevice` 和 `PartyLocalDevice`)
4. [使用者](#user) (使用者實體識別碼和 `PartyLocalUser`)
5. [端點](#endpoint) (`PartyEndpoint` 和 `PartyLocalEndpoint`)
6. [聊天控制項](#chat-control) (`PartyChatControl` 和 `PartyLocalChatControl`)
7. [狀態變更](#state-change) (`PartyStateChange`)

<a id="manager" />

### 管理員

除了前面摘要說明的物件之外，PlayFab Party API 也公開了一個最上層的 `PartyManager` 單一物件。

此公用程式/組織物件主要用作開始使用其他物件的起點。例如，新的[網路](#network)和本機[使用者](#user)最初都是在管理員中建立。所有非同步作業完成和通知也都集中在此。最根本的是，PlayFab Party 程式庫本身是在管理員中於使用前初始化，並在不再需要時清除。

<a id="network" />

### 網路

`PartyNetwork` 物件代表由參與的[裝置](#device)、其授權的[使用者](#user)，以及任何隨附的[端點](#endpoint)或[聊天控制項](#chat-control)組成的安全集合。*網路*最初建立時是空的，但裝置會連線到網路，並將至少一位本機使用者驗證到*網路*中。沒有任何已驗證使用者的*網路*會在逾時後自動終結。

若要連線到*網路*，需要使用*網路描述元*來參考它們。*網路描述元*是大部分不透明的二進位結構，包含 PlayFab Party 在內部識別和找到*網路*所需的資訊。API 提供方法，可將結構序列化為適合 Web 服務的字串並加以還原，以便使用常見的社交平台邀請機制、[PlayFab Matchmaking](/zh-TW/services/playfab/multiplayer/matchmaking) 或 PlayFab Party 本身範圍以外的其他外部會合機制，與其他裝置交換。

<Note>
  在極少數的情況下，*網路*的*網路描述元*可能會變更。遊戲應為此類變更的通知做好準備，並為現有*網路*更新或重新公告新的*網路描述元*，以避免其他裝置連線時發生問題。
</Note>

即使擁有*網路描述元*，對*網路*的存取也僅限於授權的使用者。此使用者授權是在建立*網路*期間，以及透過後續建立和撤銷邀請來完成，詳細資訊請參閱[邀請與安全性模型](/zh-TW/services/playfab/multiplayer/networking/concepts-invitations-security-model)主題。

遊戲可以選擇使用邀請，將進入權限制為只有使用者的好友，或防止惡意玩家加入*網路*。

裝置可以同時連線到多個*網路*。您可以在[稍後的主題](/zh-TW/services/playfab/multiplayer/networking/concepts-multiple-networks)中深入了解是否以及如何使用多個*網路*。

可以對 `PartyNetwork` 物件執行的動作類型包括：將本機使用者驗證到其中、連線及列舉聊天控制項、建立及列舉端點，或取得整個*網路*的效能資訊。

<a id="device" />

### 裝置

`PartyDevice` 物件代表在實體裝置上執行之遊戲及其 PlayFab Party 程式庫程式碼的個別執行個體。大多數作業不會在 `PartyDevice` 物件本身上執行；它們是一種組織機制，用來定義哪些[端點](#endpoint)或[聊天控制項](#chat-control)屬於該遊戲執行個體，特別是對於同時支援多位本機[使用者](#user)的平台和遊戲。例如，PlayFab Party 會使用這項關聯知識來最佳化遊戲資料和聊天的傳輸，即使裝置上有多個目標需要接收訊息，也只傳送一份訊息。

遠端 `PartyDevice` 物件是連線到[網路](#network)並將使用者驗證到該網路的「副產品」。只有當與該*裝置*相關聯之有效且已驗證的遠端使用者，正參與本機*裝置*也已連線的網路時，才會建立這些物件。相對地，一旦不再符合此條件，這些物件也會被終結。

另一方面，只要 PlayFab Party 已初始化，本機遊戲執行個體就一律可以參考特殊化的 `PartyLocalDevice` 子物件。它永遠不會被明確建立或終結。

<a id="user" />

### 使用者

PlayFab Party *使用者*是唯一的人類玩家，遊戲會為其執行 [PlayFab 玩家登入](/zh-TW/services/playfab/identity/player-identity/login)，以取得 `title_player_account` [實體識別碼](/zh-TW/services/playfab/live-service-management/game-configuration/entities)和權杖。

在 PlayFab Party API 中，遠端使用者僅以與[聊天控制項](#chat-control)相關聯 (並可選擇與[端點](#endpoint)相關聯) 的實體識別碼字串來識別。它們不會以專用物件表示。這是因為除了原始識別以及作為與其他物件相關聯的標籤之外，PlayFab Party 並沒有與任意使用者進行有意義互動的功能。

相反地，對於本機*使用者*則有明確的 `PartyLocalUser` 物件，因為遊戲負責管理其在 PlayFab Party 中的存留期。遊戲通常會在使用適用的[登入](/zh-TW/services/playfab/identity/player-identity/login)方法成功登入該 PlayFab 玩家時建立 `PartyLocalUser`，並在該使用者登出時適當地終結 `PartyLocalUser`。對於支援多位本機玩家登入的平台和遊戲，應為每位玩家建立額外的 `PartyLocalUser` 物件。

`PartyLocalUser` 物件也很重要，因為它們是所有驗證的基礎。必須存在有效的本機*使用者*，才能建立新的[網路](#network)或驗證進入網路。

授權使用者的詳細說明，請參閱涵蓋[邀請與安全性模型](/zh-TW/services/playfab/multiplayer/networking/concepts-invitations-security-model)的主題。

幾乎每項作業都需要提供或存在 `PartyLocalUser`，儘管在 `PartyLocalUser` 物件本身上執行的作業很少。

`PartyLocalUser` 物件是使用 `PartyManager` 物件建立的。只有其建立者可以明確終結它們。雖然它們在遠端[裝置](#device)上沒有直接的物件表示形式，但如果擁有的裝置移除 `PartyLocalUser` 或與網路中斷連線 (無論是否正常中斷)，與其相關聯的聊天控制項和端點都將被終結。

<a id="endpoint" />

### 端點

`PartyEndpoint` 物件是選用的，但對於使用它們的遊戲而言，它們是 PlayFab Party 資料通訊的核心。如同一般的網路通訊端，*端點*是一種抽象的定址機制，用於在[網路](#network)中發出資料訊息或指定其目標。它們可以代表[裝置](#device)、個別[使用者](#user)，或任何您想要唯一識別以傳送和接收訊息的任意遊戲定義概念 (例如坦克單位)。

特殊化的 `PartyLocalEndpoint` 子物件適用於本機遊戲執行個體在網路中建立的*端點*。大部分的*端點*功能都位於此處。其 `PartyLocalEndpoint::SendMessage()` 會將遊戲資料承載從 `PartyLocalEndpoint` 傳輸至同一網路中的一或多個其他 `PartyEndpoint` 物件。它提供各種選項，用於選擇如何最妥善地處理網際網路封包遺失 (例如保證傳遞和/或順序)、控制低延遲與合併來自相同或其他本機端點之多則訊息以降低頻寬使用量之間的取捨，以及在連線品質不足以支援遊戲的傳送速率時做出反應。

除了本身作為資料訊息的來源或目的地之外，PlayFab Party 也會為每個 `PartyEndpoint` 物件指派一個 16 位元的*端點唯一識別碼*，讓您可以在傳送至網路中不同 `PartyEndpoint` 物件或從其傳送的訊息承載中參考特定的*端點*。例如，這提供了一種方便的方式，可避免傳送完整且較大的使用者[實體識別碼](/zh-TW/services/playfab/live-service-management/game-configuration/entities)字串或其可能代表之其他識別碼的額外負荷，而不必自行建立對等身分識別協議交涉。

`PartyLocalEndpoint` 物件是使用其所屬的 `PartyNetwork` 物件建立的。這樣做會在遠端裝置上建立對應的 `PartyEndpoint` 物件。*端點*可以由其建立者明確終結，或在擁有的裝置與網路中斷連線，或相關聯的 `PartyLocalUser` 物件 (如果有指定) 從網路中移除時被隱含終結。

<a id="chat-control" />

### 聊天控制項

`PartyChatControl` 物件是使用 PlayFab Party 選用聊天通訊功能的機制。它們代表特定[使用者](#user)相關聯的音訊輸入/輸出裝置、喜好設定和通訊原則。

本機遊戲執行個體建立的*聊天控制項*也可以使用特殊化的 `PartyLocalChatControl` 子物件。您可以在此設定允許與遠端 `PartyChatControl` 物件進行聊天通訊的權限，例如選擇整個網路聊天或僅限隊伍聊天，或套用平台原則限制。本機*聊天控制項*用於傳送聊天文字、將文字合成為語音、要求語音串流的轉譯和翻譯、靜音等功能。

`PartyLocalChatControl` 物件必須先連線到[網路](#network)，才會在同一網路中的遠端[裝置](#device)上建立為 `PartyChatControl` 物件。即使裝置和*聊天控制項*已連線到多個共同網路，裝置也一律只會看到建立的單一代表性 `PartyChatControl` 物件。這有助於避免音訊和文字聊天訊息不必要的重複或中斷。

`PartyLocalChatControl` 物件是使用其所屬的 `PartyLocalDevice` 物件建立的。*聊天控制項*可以由其建立者明確終結，或在擁有的裝置與網路中斷連線，或相關聯的 `PartyLocalUser` 物件從網路中移除時被隱含終結。

<a id="state-change" />

### 狀態變更

`PartyStateChange` 結構用來通知遊戲所有非同步作業完成、傳入訊息、更新通知和其他 API 相關事件。

為了簡化在時間無法預測的網際網路上處理複雜的多機器互動，PlayFab Party 保證除非是遊戲明確呼叫所致，否則不會修改其從 API 回報的任何狀態。但由於您仍然需要一種方式來了解遠端起始的作業或會修改本機狀態的非預期事件，PlayFab Party 和遊戲會透過一對特殊的方法 `PartyManager::StartProcessingStateChanges()` 和 `PartyManager::FinishProcessingStateChanges()` 進行合作。這些方法會在遊戲工作迴圈中方便處理此類更新的時間點呼叫。新事件會從 `PartyManager::StartProcessingStateChanges()` 以零個或多個 `PartyStateChange` 結構的陣列形式回報。遊戲處理完*狀態變更*後，會使用 `PartyManager::FinishProcessingStateChanges()` 傳回該陣列。

`PartyStateChange` 結構本身並不是完整的物件。它是一個基底標頭，需轉型為更詳細的結構，其中包含特定完成或通知類型的資訊、相關物件的指標，以及任何錯誤資訊。

後續主題將完整詳細地說明如何使用*狀態變更*。

## 後續步驟

* [了解 PlayFab Party 邀請與安全性模型](/zh-TW/services/playfab/multiplayer/networking/concepts-invitations-security-model)
* [了解 PlayFab Party 如何與您的探索流程互動](/zh-TW/services/playfab/multiplayer/networking/concepts-discovery)
* [深入了解 PlayFab Party 聊天通訊](/zh-TW/services/playfab/community/voice-communications/concepts-chat)
* 了解如何在 PlayFab Party 中使用非同步作業和通知


## Related topics

- [Party 快速入門](/zh-TW/services/playfab/multiplayer/networking/quickstart.md)
- [使用多個 PlayFab Party 網路](/zh-TW/services/playfab/multiplayer/networking/concepts-multiple-networks.md)
- [使用 Multiplayer SDK 將 Party 與 Lobby 整合](/zh-TW/services/playfab/multiplayer/networking/party-lobby-integration.md)
- [PlayFab Party 功能](/zh-TW/services/playfab/multiplayer/networking/party-features.md)
- [PFProfilesEntityDataObject](/zh-TW/services/playfab/api-references/c/pfprofilestypes/structs/pfprofilesentitydataobject.md)