> ## 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 objects and their relationships
> ネットワーク、デバイス、エンドポイント、チャット コントロールなどの中心的な PlayFab Party オブジェクトと、それらがリアルタイム チャットおよびデータ通信でどのように関連するかを学びます。
PlayFab Party API のパワーと柔軟性を使いこなすには、そのスコープ内で定義されている以下の重要なオブジェクトを理解することから始まります。
* [**デバイス**](#device) - 物理デバイス上で実行されているゲームの明確なインスタンス。API が使用されているとき、ローカル デバイスが常に存在します。
* [**ユーザー**](#user) - ログオンしている個々のプレイヤー。より正確には、ゲームが認証と識別の目的で PlayFab Party に提供する PlayFab の `title_player_account` [エンティティ](/services/playfab/live-service-management/game-configuration/entities)。1 つ以上のユーザーが指定されたデバイスに関連付けられます。
* [**ネットワーク**](#network) - チャットまたはデータ通信を交換するためにゲームが作成する、1 つ以上のデバイスとそれらの認可されたユーザーのセキュアなコレクション。ネットワークは通常、ゲームのマルチプレイヤー セッションまたはチャット パーティのコンセプトと一致します。
* [**エンドポイント**](#endpoint) - ネットワーク内でデータを送受信するための抽象化。エンドポイントはデバイス、ユーザー、または任意のゲーム固有のコンセプトを表す場合があります。
* [**チャット コントロール**](#chat-control) - 1 つ以上のネットワークで音声とテキスト チャットの構成、発信元、およびターゲットを設定するためのユーザーの表現。
## オブジェクトの関係
簡略化された概念階層として、[ネットワーク](#network) には [デバイス](#device) が含まれ、それらには [ユーザー](#user)、任意の [エンドポイント](#endpoint)、および任意の [チャット コントロール](#chat-control) が含まれます。例:
上記の関係図は理解しやすいものですが、実際には PlayFab Party の機能の不完全な描写であり、それだけで解釈すると誤解を招く可能性があります。実際には、Party API はデバイスが *複数の* ネットワークに同時に接続することをサポートしています。たとえば、同じフレンド グループが見知らぬ人との別の大きなゲーム セッションに参加および退出しながらも、そのフレンド グループとの通信を長期間維持したい場合があります。このより広範なシナリオを考慮することで、これらのオブジェクト間の関係をよりよく理解できます。
デバイスがネットワークに *属している* と概念化するのは直感的に感じられるかもしれませんが、これは正しくありません。デバイスはネットワークに *参加している* と考えるほうがより正確です。したがって、Party ライブラリは、特定のインスタンスに遭遇したとき、それが共有するローカル デバイスとのネットワーク数に関係なく、リモートまたはローカルのいずれかに関係なく、単一のデバイス API オブジェクトを常に作成します。
例として、以下の図は 2 つのネットワークと 3 つのデバイス、ユーザー、チャット コントロール、エンドポイントを示しています。*デバイス A* とその 2 つのチャット コントロール (関連ユーザー付き) は *ネットワーク 1* に参加しており、*デバイス B* と *C* は単一のチャット コントロール (関連ユーザー付き) で *ネットワーク 1* *と* *ネットワーク 2* の両方に接続しています。すべてのデバイスは、接続している各ネットワーク内で 1 つまたは 2 つのエンドポイントを作成しています。
図では、すべてのデバイスが 3 つのデバイスすべてとそれらのチャット コントロールの単一のインスタンスを見ることができます。少なくとも 1 つのネットワークを互いに共有しているためです。*デバイス A* は *ネットワーク 1* の *エンドポイント 1-4* のみを知っていますが、*デバイス B* と *C* は *ネットワーク 2* で作成した *エンドポイント 5-7* も見ることができます。
*デバイス C* が代わりに *ネットワーク 2* のみに参加し、両方のネットワークに参加していない場合、以下のようになります。
* *デバイス C* は明らかに *ネットワーク 1* で *エンドポイント 4* を作成できず、*エンドポイント 1-3* も見ることができません。
* *デバイス C* は *ネットワーク 1* 内のみの *デバイス A* またはその 2 つのチャット コントロールについて知りません。
* 同様に、*デバイス A* は *ネットワーク 2* 内のみの *デバイス C* またはそのチャット コントロールを見ません。
ただし、*デバイス B* は両方のネットワークに参加しているため、すべてのデバイスとそのチャット コントロールを **引き続き** 見ることができます。
つまり、デバイスとチャット コントロールがネットワークとの厳密な階層ツリー関係の「外」にあるにもかかわらず、ゲーム インスタンスは付随するネットワークのコンテキストなしでリモート デバイスやチャット コントロールに実際に遭遇することは決してないことに注意することが重要です。ローカルとリモートのデバイスまたはチャット コントロールが少なくとも 1 つの共通ネットワークを持っている場合、リモート オブジェクトは表示されます。ただし、共通ネットワークがない場合、リモート オブジェクトは決して作成されません。
PlayFab Party を正常に使用するために、ゲームが複数のネットワークに同時に接続する必要はありません。複数のネットワークを使用するかどうか、および使用方法について詳しくは、[後続の高度なトピック](/services/playfab/multiplayer/networking/concepts-multiple-networks) を参照してください。
## 共通のオブジェクト属性
すべてのオブジェクトには明確に定義された有効期間があります。ローカル ゲーム インスタンスは、各オブジェクトを直接、またはゲームの選択したタイム ウィンドウ中にのみシグナルされる標準化された通知メカニズムを使用して作成および破棄します。通知の操作については、後のトピックで詳しく説明します。
すべての PlayFab Party API オブジェクトは、*カスタム コンテキスト* の概念もサポートしています。これは、オブジェクトに任意のローカルのみの「ショートカット」ポインターまたは値を保存する単なる方法です。カスタム コンテキストにより、PlayFab Party オブジェクトから、メモリ内の対応するプライベート ゲーム オブジェクト (存在する場合) に戻ることが、非効率的なルックアップを実行することなく簡単にできます。これらの値はリモート送信されません。ポインター値はローカル ゲーム インスタンスにのみ意味があるためです。
最後に、[ネットワーク](#network) を除く上記のすべてのオブジェクトには、オブジェクトを所有するローカル [デバイス](#device) のみが利用できるメソッドとプロパティを含む専用の「Local」サブオブジェクトがあります。
たとえば、任意のローカルまたはリモート [エンドポイント](#endpoint) を表すために使用される基本の `PartyEndpoint` オブジェクトと、そのエンドポイントが実際にローカル デバイスによって作成された場合にのみ `PartyEndpoint::GetLocal()` を介して取得できる、より具体的な `PartyLocalEndpoint` オブジェクトがあります。ここでは、ゲーム データを送信するための `PartyLocalEndpoint::SendMessage()` メソッドが公開されています。1 つのデバイスが別のリモート デバイスのソース エンドポイントから何らかの方法でデータを送信できるようにするのは意味がないためです。
C++ PlayFab Party インターフェース (推奨) を使用する場合、オブジェクトは C++ クラス インスタンスとして公開されます。フラット C インターフェースを使用する場合、オブジェクトはハンドル値で表されます。
## すべての主要なオブジェクトの役割の詳細
1. [Manager](#manager) (`PartyManager`)
2. [Network](#network) (`PartyNetwork`)
3. [Device](#device) (`PartyDevice` と `PartyLocalDevice`)
4. [User](#user) (ユーザー エンティティ ID と `PartyLocalUser`)
5. [Endpoint](#endpoint) (`PartyEndpoint` と `PartyLocalEndpoint`)
6. [Chat Control](#chat-control) (`PartyChatControl` と `PartyLocalChatControl`)
7. [State Change](#state-change) (`PartyStateChange`)
### Manager
前述のオブジェクトに加えて、PlayFab Party API はトップレベルの `PartyManager` シングルトン オブジェクトも公開します。
このユーティリティ/組織オブジェクトは、他のオブジェクトを扱い始めるための出発点として大部分使用されます。たとえば、Manager は新しい [ネットワーク](#network) やローカル [ユーザー](#user) が最初に作成される場所です。すべての非同期操作の完了と通知もここに集中されます。最も基本的には、Manager は使用前に PlayFab Party ライブラリ自体を初期化し、不要になったときにクリーンアップする場所です。
### Network
`PartyNetwork` オブジェクトは、参加している [デバイス](#device)、それらの認可された [ユーザー](#user)、および付随する [エンドポイント](#endpoint) または [チャット コントロール](#chat-control) のセキュアなコレクションを表します。*ネットワーク* は最初は空で作成されますが、デバイスがそれらに接続し、少なくとも 1 つのローカル ユーザーを *ネットワーク* に認証します。認証されたユーザーがいない *ネットワーク* は、タイムアウト後に自動的に破棄されます。
*ネットワーク* に接続するには、*ネットワーク記述子* を使用して *ネットワーク* を参照します。*ネットワーク記述子* は、PlayFab Party が内部的に *ネットワーク* を識別および特定するのに必要な情報を含む、ほぼ不透明なバイナリ構造です。API は、構造体を Web サービスに適した文字列にシリアル化したり戻したりするメソッドを提供します。これにより、一般的なソーシャル プラットフォームの招待メカニズム、[PlayFab マッチメイキング](/services/playfab/multiplayer/matchmaking)、または PlayFab Party 自体の範囲外のその他の外部ランデブー メカニズムを使用して、他のデバイスと交換できます。
*ネットワーク* の *ネットワーク記述子* は、まれな状況で変更される可能性があります。ゲームは、そのような変更の通知に備え、追加のデバイスの接続の問題を回避するために、既存の *ネットワーク* の新しい *ネットワーク記述子* を更新または再アドバタイズする必要があります。
*ネットワーク記述子* を持っていても、*ネットワーク* へのアクセスは認可されたユーザーに制限されます。このユーザー認可は、[招待とセキュリティ モデル](/services/playfab/multiplayer/networking/concepts-invitations-security-model) トピックで詳しく説明されているように、*ネットワーク* 作成時、およびその後の招待の作成と取り消しを通じて行われます。
ゲームは、招待を使用してユーザーのフレンドのみに参加を制限したり、悪意のあるプレイヤーが *ネットワーク* に参加するのを防いだりすることを選択できます。
デバイスは一度に複数の *ネットワーク* に接続できます。複数の *ネットワーク* を使用するかどうか、および使用方法について詳しくは、[後のトピック](/services/playfab/multiplayer/networking/concepts-multiple-networks) で学んでください。
`PartyNetwork` オブジェクトで実行できるアクションの種類には、ローカル ユーザーを認証すること、チャット コントロールの接続と列挙、エンドポイントの作成と列挙、または *ネットワーク* 全体のパフォーマンス情報の取得が含まれます。
### Device
`PartyDevice` オブジェクトは、物理デバイス上で実行されているゲームとその PlayFab Party ライブラリ コードの明確なインスタンスを表します。ほとんどの操作は `PartyDevice` オブジェクト自体で実行されるわけではありません。むしろ、特に複数のローカル [ユーザー](#user) を同時にサポートするプラットフォームとゲームの場合、どの [エンドポイント](#endpoint) や [チャット コントロール](#chat-control) がそのゲーム インスタンスに属するかを定義するための組織メカニズムです。PlayFab Party はこの関係の知識を利用して、たとえばデバイス上の複数のターゲットがメッセージを受信する必要がある場合でも、メッセージのコピーを 1 つだけ送信することで、ゲーム データとチャットの送信を最適化します。
リモート `PartyDevice` オブジェクトは、[ネットワーク](#network) への接続とそのネットワークへのユーザー認証の「副産物」です。それらは、*デバイス* に関連付けられた有効な認証済みリモート ユーザーが、ローカル *デバイス* も接続しているネットワークに参加している場合にのみ作成されます。同様に、それが真実でなくなったときにも破棄されます。
一方、`PartyLocalDevice` 特殊サブオブジェクトは、PlayFab Party が初期化されている限り、ローカル ゲーム インスタンスが参照できるように常に利用可能です。これは明示的に作成または破棄されることはありません。
### User
PlayFab Party の *ユーザー* は、ゲームが [PlayFab プレイヤー ログイン](/services/playfab/identity/player-identity/login) を実行して `title_player_account` [エンティティ ID](/services/playfab/live-service-management/game-configuration/entities) とトークンを取得する、一意の人間プレイヤーです。
リモート ユーザーは、[チャット コントロール](#chat-control) および任意で [エンドポイント](#endpoint) に関連付けられたエンティティ ID 文字列のみで PlayFab Party API 内で識別されます。専用のオブジェクトを使用して表されるわけではありません。これは、PlayFab Party に、生の識別と他のオブジェクトに関連付けられたラベルとして以外に、任意のユーザーと有意義に相互作用する機能がないためです。
逆に、ローカル *ユーザー* には明示的な `PartyLocalUser` オブジェクトがあります。ゲームが PlayFab Party 内でその有効期間の管理を所有するためです。ゲームは通常、該当の [ログイン](/services/playfab/identity/player-identity/login) メソッドを使用してその PlayFab プレイヤーを正常にログインさせたときに `PartyLocalUser` を作成し、そのユーザーがログオフしたときに適切に `PartyLocalUser` を破棄します。複数のローカル プレイヤーがログインすることをサポートするプラットフォームとゲームの場合、各プレイヤーに対して追加の `PartyLocalUser` オブジェクトを作成する必要があります。
`PartyLocalUser` オブジェクトは、すべての認証の基盤であるため重要です。新しい [ネットワーク](#network) を作成するか、そのネットワークに認証するには、有効なローカル *ユーザー* が存在する必要があります。
ユーザーの認可については、[招待とセキュリティ モデル](/services/playfab/multiplayer/networking/concepts-invitations-security-model) を扱うトピックで詳しく説明されています。
`PartyLocalUser` オブジェクト自体で実行される操作はごくわずかですが、ほぼすべての操作で `PartyLocalUser` を提供または存在させる必要があります。
`PartyLocalUser` オブジェクトは `PartyManager` オブジェクトを使用して作成されます。それらは、その作成者によってのみ明示的に破棄できます。それらはリモート [デバイス](#device) 上に直接オブジェクトの表現を持ちませんが、それらに関連付けられたチャット コントロールとエンドポイントは、所有デバイスが `PartyLocalUser` を削除するか、ネットワークから正常またはそれ以外の方法で切断された場合に破棄されます。
### Endpoint
`PartyEndpoint` オブジェクトはオプションですが、それらを活用するゲームの PlayFab Party データ通信のコアです。典型的なネットワーキング ソケットと同様に、*エンドポイント* は [ネットワーク](#network) 内でデータ メッセージの発信または対象を指定する抽象化されたアドレッシング メカニズムです。それらは [デバイス](#device)、個々の [ユーザー](#user)、またはメッセージの送受信のために一意に識別したい任意のゲーム定義のコンセプト (例: 戦車ユニット) を表現できます。
特殊化された `PartyLocalEndpoint` サブオブジェクトは、ローカル ゲーム インスタンスによってネットワーク内で作成された *エンドポイント* 用です。ここに、ほとんどの *エンドポイント* 機能があります。その `PartyLocalEndpoint::SendMessage()` は、同じネットワーク内の 1 つ以上の他の `PartyEndpoint` オブジェクトに `PartyLocalEndpoint` からゲーム データ ペイロードを送信します。インターネット パケット損失に最適に対応する方法を選択するためのさまざまなオプション (例: 配信および/または順序の保証)、低レイテンシと、同じまたは他のローカル エンドポイントからの複数のメッセージを結合してより低い帯域幅使用を実現することとの間のトレードオフを制御するオプション、および接続品質がゲームの送信率をサポートするのに十分でない場合の対応オプションを提供します。
データ メッセージ自体のソースまたは宛先であることに加えて、各 `PartyEndpoint` オブジェクトには PlayFab Party によって 16 ビットの *エンドポイント固有識別子* も割り当てられ、ネットワーク内の別の `PartyEndpoint` オブジェクトに送信または受信されるメッセージ ペイロードで、特定の *エンドポイント* を参照できます。これにより、独自のピアツーピア ID 合意ネゴシエーションを構築することなく、たとえば、それが表す可能性のある完全でより大きなユーザー [エンティティ ID](/services/playfab/live-service-management/game-configuration/entities) 文字列またはその他の識別子を送信するオーバーヘッドを回避する便利な方法が提供されます。
`PartyLocalEndpoint` オブジェクトは、それを含む `PartyNetwork` オブジェクトを使用して作成されます。そうすると、対応する `PartyEndpoint` オブジェクトがリモート デバイスに作成されます。*エンドポイント* は、その作成者によって明示的に破棄することも、所有デバイスがネットワークから切断したとき、または関連する `PartyLocalUser` オブジェクト (指定されている場合) がネットワークから削除されたときに暗黙的に破棄されます。
### Chat control
`PartyChatControl` オブジェクトは、PlayFab Party のオプションのチャット通信機能を使用するためのメカニズムです。それらは特定の [ユーザー](#user) の関連付けられたオーディオ入力/出力デバイス、設定、および通信ポリシーを表します。
特殊化された `PartyLocalChatControl` サブオブジェクトは、ローカル ゲーム インスタンスによって作成された *チャット コントロール* に対しても利用可能です。ここでは、たとえば、ネットワーク全体対チーム限定のチャットを選択するため、またはプラットフォーム ポリシー制限を適用するために、リモート `PartyChatControl` オブジェクトへのまたはそこからのチャット通信を許可する権限を構成します。ローカル *チャット コントロール* は、チャット テキストの送信、テキストの音声合成、音声ストリームの文字起こしと翻訳の要求、ミュートなどに使用されます。
`PartyLocalChatControl` オブジェクトは、リモート [デバイス](#device) 上の同じネットワーク内で `PartyChatControl` オブジェクトとして作成される前に、[ネットワーク](#network) に接続する必要があります。そのデバイスと *チャット コントロール* が複数のネットワークに共通で接続されている場合でも、デバイスは常に単一の代表的な `PartyChatControl` オブジェクトのみを見ます。これは、オーディオおよびテキスト チャット メッセージの不要な重複や中断を回避するのに役立ちます。
`PartyLocalChatControl` オブジェクトは、それを含む `PartyLocalDevice` オブジェクトを使用して作成されます。*チャット コントロール* は、その作成者によって明示的に破棄することも、所有デバイスがネットワークから切断したとき、または関連する `PartyLocalUser` オブジェクトがネットワークから削除されたときに暗黙的に破棄されます。
### State Change
`PartyStateChange` 構造体は、すべての非同期操作の完了、受信メッセージ、更新通知、およびその他の API 関連イベントをゲームに通知するために使用されます。
予測不可能なタイミングでのインターネット上の複雑なマルチマシン相互作用の処理を簡素化するため、PlayFab Party は、ゲームによる明示的な呼び出しの結果である場合を除いて、API から報告する状態を変更しないことを保証します。ただし、リモート開始操作またはローカル状態を変更する予期しない発生について学ぶ方法は依然として必要なため、PlayFab Party とゲームは特別なペアのメソッド `PartyManager::StartProcessingStateChanges()` と `PartyManager::FinishProcessingStateChanges()` を通じて協力します。これらは、そのような更新を処理するのに便利なゲームの作業ループの時点で呼び出されます。新しいイベントは、0 個以上の `PartyStateChange` 構造体の配列として `PartyManager::StartProcessingStateChanges()` から報告されます。ゲームが *状態変更* を処理し終わったら、その配列は `PartyManager::FinishProcessingStateChanges()` を使用して返されます。
`PartyStateChange` 構造体はそれ自体では完全なオブジェクトではありません。特定の完了または通知の種類、関連するオブジェクトへのポインター、およびエラー情報を含むより詳細な構造体にキャストされる基本ヘッダーです。
*状態変更* の操作については、後のトピックで詳しく説明します。
## 次のステップ
* [PlayFab Party の招待とセキュリティ モデルについて学ぶ](/services/playfab/multiplayer/networking/concepts-invitations-security-model)
* [PlayFab Party が検出フローとどのように相互作用するかを学ぶ](/services/playfab/multiplayer/networking/concepts-discovery)
* [PlayFab Party のチャット通信について詳しく知る](/services/playfab/community/voice-communications/concepts-chat)
* PlayFab Party で非同期操作と通知を扱う方法を確認する
## Related topics
- [objects_updated](/ja-jp/services/playfab/api-references/events/PlayerProfile/objects-updated.md)
- [PartyManager::SetOption](/ja-jp/services/playfab/multiplayer/networking/reference/classes/PartyManager/methods/partymanager_setoption.md)
- [OnRemotePlayerJoined](/ja-jp/services/playfab/multiplayer/networking/unity-party-api-reference/classes/playfabmultiplayermanager/events/partyunityonremoteplayerjoined.md)
- [OnRemotePlayerLeft](/ja-jp/services/playfab/multiplayer/networking/unity-party-api-reference/classes/playfabmultiplayermanager/events/partyunityonremoteplayerleft.md)
- [PartyManager::GetOption](/ja-jp/services/playfab/multiplayer/networking/reference/classes/PartyManager/methods/partymanager_getoption.md)