> ## 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. # Multiplayer Session Directory > セッション テンプレート属性、契約バージョン 107 スキーマ、QoS テンプレート、メンバー初期化、マルチプレイヤーのトラブルシューティングを扱う MPSD の詳細ガイド。 この記事では、XBOX 360 以降のプラットフォームで XBOX services の Multiplayer Session Directory (MPSD) サービスを使用したマルチプレイヤー セッションの作成の概要について説明します。 この記事は、主にセッション テンプレートを Partner Center に直接提出する XBOX タイトル開発者を対象としています。 この記事では、マルチプレイヤー セッションの MPSD の構成、使用方法、およびトラブルシューティングについて説明します。 **目次:** * [改訂の概要](#rs) * [はじめに](#intro) * [このドキュメントで使用される用語](#tuitd) * [Multiplayer Session Directory](#tmsd) * [MPSD セッション](#mpsds) * [セッション テンプレートの属性](#sta) * [契約スキーマの更新](#csu) * [セッション ドキュメントにおけるメンバー初期化](#miisd) * [マッチ チケット セッション](#mts) * [Quality of Service (QoS) テンプレート](#qost) * [QoS フェーズおよびセッション初期化の詳細](#qospasid) * [XBOX Cloud Compute セッション](#xccs) * [Raw セッションおよびカスタム タイトル プロパティ](#rsactp) * アクティブ メンバーの減衰 * [FAQ とトラブルシューティング](#fat) ## 改訂の概要 現在のクライアント サイドの XBOX Services API (XSAPI) ライブラリは、MPSD サービスとの通信に契約バージョン 104 を使用しています。 このバージョンのドキュメントは、セッション テンプレート スキーマを、MPSD サービスがサポートする最新の契約バージョンである契約バージョン 107 に更新します。 バージョン 104 と 107 の間の変更点は、以下の [契約スキーマの更新](#_Contract_schema_update) セクションでまとめられています。 契約バージョン 104 用に書かれたテンプレートは、107 として再公開する場合に更新が必要な点に注意してください。 ただし、サービスは下位互換性があるため、現在のライブラリを引き続き使用できます。将来のリリースで更新される予定です。 このドキュメントの前回の改訂では、サーバー セッションに関する情報を更新し、XSAPI と RESTful サービス呼び出しに関する新しいセクションを追加しました。 さらに、Query for Session State Information セクションの表が更新され、Quality of Service (QoS) Templates セクションも改訂されました。 ## はじめに マルチプレイヤー セッションは、Multiplayer Session Directory (MPSD) のクラウドに存在する安全なドキュメントであり、このドキュメントはゲームをプレイしている人々のグループを表します。 具体的には、マルチプレイヤー セッションには次の特性があります。 * 各セッションには一意の URI があります。 * セッション ドキュメントには、現在のメンバー、ゲーム設定、ブートストラップ データ、およびゲーム サーバー情報が含まれています。 * タイトルは独自のセッションを作成および管理します。 * セッションはメンバー間の接続性を可能にします。 Multiplayer Session Directory (MPSD) は、すべてのクライアント間でゲーム セッションのメタデータを集中管理します。 MPSD は、クライアント間のセキュアなデバイス関連付けを設定するのに役立つ、セッションに関する基本情報を提供します。 MPSD はまた、より特定的なゲーム データの受け渡しを開始する前に、クライアントがゲームに接続するための基本的な初回ブート メタデータも提供します。 XBOX One 以降のアプリケーションのプロセス ライフタイム管理 (PLM) およびタスク切り替えの性質により、MPSD は、アクティブなゲーム セッションの一部として識別されるピアおよびサーバーに接続するために必要な正しい情報をクライアントが持っていることを保証し、シェルおよびコンソール オペレーティング システムと連携してゲーム セッションのプレイヤー ライフタイムを予約、アクティブ化、および管理します。 ## このドキュメントで使用される用語 | 用語 | 定義 | | - | - | | マルチプレイヤー セッション | XBOX services クラウドに存在し、XBOX One 以降 (PC を含む) でタイトルをプレイ中 (または今後プレイする) にお互いに接続されるユーザー グループを表す安全なドキュメント。マッチメイキング、パーティ、途中参加などのマルチプレイヤーのすべての側面は、マルチプレイヤー セッションを活用します。 | | ゲーム セッション | これは、ユーザーが一緒にプレイしている、MPSD で公開される実際のゲーム セッションです。すべてのマルチプレイヤー シナリオは最終的にはゲーム セッションになります。 | | マッチ チケット セッション | これは、マッチメイキング中にマッチ チケットの提出を追跡するために使用されるセッションです。 | | 非アクティブ プレイヤー | セッション内で非アクティブ状態に設定されたプレイヤー。タイトルは、ゲームが制約された、中断された、またはタイトルによって定義された非アクティブな状態にある場合に、ユーザーを非アクティブ状態に設定します。 | ## Multiplayer Session Directory MPSD は、オンライン プレイヤー間でセッション情報を調整するのに役立ち、タイトルを支援します。 マルチプレイヤー プレイのさまざまなタスクを達成するために、異なる種類のセッションを作成できます。 次の表は、XBOX 360 でそのようなタスクがどのように行われていたか、および XBOX One 以降 (PC を含む) でどのように達成されるかの違いを示しています。 | 機能またはタスク | XBOX 360 | XBOX One 以降 | | - | - | - | | **ゲーム セッション情報を取得する** | **XSessionGetDetails**、**XSessionSearchByID** を使用するか、自分で追跡します。 | サービスからセッション情報を要求します。 | | **ホストを移行する** | 必要に応じて、タイトルは **XSessionMigrateHost** を呼び出します。 | 新しいセッションを作成する必要はなく、SessionID に新しいホストを割り当てるだけです。 | | **複数のプレイヤー セッションを管理する** | 一度に複数のセッションを扱うのが難しい。たとえば、**XNetReplaceKey** と **XNetUnregisterKey** など。 | サービス ベースのセッションにより、1 つのセッションの管理がよりクリーンになり、複数のセッションを扱いやすくなります。 | | **サインアウトと切断を処理する** | 切断とサインアウトを、それぞれ **XCloseHandle** または **XSessionDelete** で異なる方法で処理する必要がある。 | 集中サービスにより、サインアウトと切断の処理が簡素化され、タイムアウトはゲーム構成で設定されます。 | ### セッション パターン * ゲーム セッション * プレイヤーの XUID、セキュア デバイス アドレス データ、およびプロパティ状態を持つセッション。これは実際のゲームプレイ セッションと考えられます。 * ピアツーピア、ピアツーホスト、ピアツーサーバー、またはハイブリッドにすることができます。 * マッチ チケット セッション * 一緒にプレイする他のプレイヤーを見つけるためにマッチメイキングに提出されるセッション。ゲームがさらにプレイヤーを探している場合は、ゲーム セッションもチケット セッションとして機能できることに注意してください。 * サーバー セッション * XBOX Compute 処理を通じて作成および使用されるゲーム セッション。 図 1 は MPSD セッションの使用法を示しており、青いボックスは MPSD セッションを表し、赤いボックスはそれらを使用するサービスを表します。 **図 1. MPSD セッションの使用:** (図はありません) ## MPSD セッション セッションは、関連するエンティティの 2 つのリストを保持します: 1. セッションに参加した、または招待されたメンバー (ユーザー)。 2. セッションに参加したサーバー (クラウド サーバーまたは専用サーバー)。 各エンティティには次のものがあります。 1. 作成時に設定された定数値。 2. 変更可能なプロパティ。 3. 読み取り専用のメタデータ。 ### XSAPI と RESTful サービス呼び出し XBOX services の Sessions および Matchmaking サービスとインターフェースする方法は 2 つあります。 * 標準の HTTPs 呼び出し * XSAPI ラッパー #### RESTful サービスへの標準 HTTPS 呼び出しを使用する XBOX One 以降で、XBOX services の Sessions および Matchmaking サービスとインターフェースする最初の方法は、RESTful XBOX services URI への標準 HTTPS 呼び出しを使用することです。 これにより、タイトルはサーバーおよびゲームの構成に応じてこれらのサービスを呼び出しインターフェースする柔軟性が得られます。 これらの URI のリストについては、[XBOX services RESTful リファレンス](https://devdocs.xbox.com/ja-jp/reference/live/rest/atoc-xboxlivews-reference.md) を参照してください。 #### RESTful サービス用の XSAPI ラッパーを使用する Sessions および Matchmaking サービスとインターフェースする 2 つ目の方法は、RESTful サービス URI のラッパーとして動作する XSAPI を使用することです。 これにより、各呼び出しに対して HTTPS トラフィックを処理することなく、コードで API を使用するより伝統的なアプローチが可能になります。 XSAPI の詳細については、[xbox-live-api GitHub ページ](https://github.com/microsoft/xbox-live-api) を参照してください。 そのリファレンス ドキュメントには次のものが含まれています。 * JSON Parsing API Reference - JSON パースの API のリファレンス資料。 * Windows.Web Namespace - Windows.Web 名前空間のメンバー。 * XBOX Compute SDK Reference - XBOX Compute 用のゲーム サーバー インスタンスを作成するための API。 ### MPSD セッションとテンプレート MPSD セッションは、Partner Center を通じて取り込まれたテンプレートを使用して作成されます。 テンプレートは、作成されるセッションのフレームワークを定義する JSON ドキュメントです。 テンプレートは、新しいセッションのための定数を提供します。 以下は、テンプレート構成の例からの抜粋です。 ```json theme={null} // Used for creating the session that you then pass into your match ticket request. This *should* not have any QoS requirements. MatchTicketSession (Contract Version: 107) { "constants": { "system": { "version": 1, "maxMembersCount": 10, "visibility": "private", "capabilities": {}, "memberInitialization": { "joinTimeout": 20000, "externalEvaluation": false, "membersNeededToStart": 1 } }, "custom": {} } } // This is the new game session that is returned after you've been matched. // Note: This is used for in-game QoS. For out-of-game QoS, you will need P2P/HTP requirements. GameSession (Contract Version:107) { "constants": { "system": { "maxMembersCount": 12, "capabilities": {"connectivity": true } }, "memberInitialization": { "joinTimeout": 20000, "measurementTimeout": 15000, "externalEvaluation": false, "membersNeededToStart": 4 }, "custom": {} } } ``` マッチ チケット セッションは、**memberInitialization** オブジェクトに QoS タイムアウト値が設定されたゲーム セッション テンプレートと一緒に使用する必要があります。 **図 2. サンプル ホッパー:** ![ホッパー編集ダイアログ ボックス](https://mintcdn.com/microsoft-4404708b/ktEik-YaZoen6Rhy/images/gdk/services/mpsd_image1.png?fit=max\&auto=format\&n=ktEik-YaZoen6Rhy\&q=85\&s=2413f594f853c2fbf7cd196028f2f33b) 以下のコード抜粋は、ピアツーピア ゲーム セッション テンプレート (タイトル管理の QoS) の例です。 ```json theme={null} { "constants": { "system": { "version": 1, "maxMembersCount": 10, "visibility": "private", "capabilities": { "connectivity": true }, "memberInitialization": { "joinTimeout": 20000, "externalEvaluation": false, "membersNeededToStart": 2 } }, "custom": {} } } ``` これは、ピアツーサーバー セッションおよび RAW テンプレートの例です。 ```json theme={null} { "constants": { "system": { "version": 1, "maxMembersCount": 10, "visibility": "private", "capabilities": {} }, "custom": {} } } ``` 次のコードは、Smart Match に使用されるマッチ チケット セッション テンプレートの例を示しています。 ```json theme={null} { "constants": { "system": { "version": 1, "maxMembersCount": 10, "visibility": "private", "capabilities": {}, "memberInitialization": { "joinTimeout": 20000, "externalEvaluation": false, "membersNeededToStart": 1 } }, "custom": {} } } ``` ### SCID に対して構成されているテンプレートを確認する #### セッション テンプレート SCID 内に存在するセッション テンプレートのリスト、および特定のセッション テンプレートの詳細は、MPSD から取得できます。 ```uri theme={null} GET /serviceconfigs/{scid}/sessiontemplates GET /serviceconfigs/{scid}/sessiontemplates/{session-template-name} ``` #### セッション状態情報をクエリする セッションはサービス構成およびセッション テンプレート レベルでクエリできます: ```uri theme={null} GET /serviceconfigs/{scid}/sessions GET /serviceconfigs/{scid}/sessiontemplates/{session-template-name}/sessions ``` デフォルトでは、これは最大 100 の非プライベート セッションを返します。 以下のクエリ文字列パラメーターを使用して、クエリを変更できます。 | クエリ文字列 | 効果 | 説明 | | - | - | - | | keyword=foo | キーワード "foo" を持つセッションのみを含めます。 | | | XUID=123 | ユーザー "123" が参加しているセッションのみを含めます。 | デフォルトでは、ユーザーがセッションに含まれるにはアクティブでなければなりません。 | | *reservations*=**true** | ユーザーが予約プレイヤーとして設定されているが、アクティブ プレイヤーになるために参加していないセッションを含めます。 | 自分自身のセッションをクエリしている場合、または特定ユーザーのセッションをサーバー間でクエリしている場合にのみ利用できます。 | | *inactive*=**true** | ユーザーが受諾しているが、アクティブにプレイしていないセッションを含めます。 | ユーザーが "ready" だが "active" ではないセッションは非アクティブとしてカウントされます。 | | *private*=**true** | プライベート セッションを含めます。 | 自分自身のセッションをクエリしている場合、またはサーバー間でクエリしている場合にのみ利用できます。 | | *visibility*=open | "open" セッションのみを含めます。 | "private" に設定されている場合、"private=true" ディレクティブも設定する必要があります。 | | *take*=5 | 最大 5 セッションを返します。 | 0 と 100 の間でなければなりません。 | 結果はセッション参照の JSON 配列です。 一部のセッション データはインラインで含まれます。 **注意** すべてのクエリには、keyword フィルタ、XUID フィルタ、またはその両方を含める必要があります。 *private* (プライベート セッションを返す) または *reservations* (ユーザーが参加していないセッションを返す) のいずれかを **true** に設定するには、呼び出し元がセッションへのサーバー レベルのアクセス権を持っているか、呼び出し元の XUID クレームが URI 内の XUID フィルタと一致する必要があります。 そうでない場合、403 Forbidden が返されます (そのようなセッションが実際に存在するかどうかにかかわらず)。 以下のコード抜粋は、クエリ応答の例を示しています。 ```json theme={null} { "results": [ { "xuid": "9876", // If the session was found from a xuid, that xuid. "startTime": "2009-06-15T13:45:30.0900000Z", "sessionRef": { "scid": "foo", "templateName": "bar", "name": "session-seven" }, "accepted": 4, // Approximate number of non-reserved members. "status": "active", // or "reserved" or "inactive". This is the state of the user in the session, not the session itself. Only present if the session was found using a xuid. "visibility": "open", // or "private", "visible", or "full" "myTurn": true, // Not present is the same as 'false'. Only present if the session was found using a xuid. "keywords": [ "one", "two" ] } ] } ``` ## セッション テンプレートの属性 ## 契約スキーマの更新 このドキュメントの冒頭で述べたように、最新のセッション テンプレート契約バージョンは 107 で、以前のバージョンである 104 からスキーマにいくつかの変更が導入されています。 契約バージョン 104 用に書かれたテンプレートは、107 として再公開する場合に更新が必要です。 以下は変更点のまとめです。 * **/constants/system/managedInitialization** は **/constants/system/memberInitialization** に名称変更されます。 * **autoEvaluate** フィールドは **externalEvaluation** に名称変更され、極性が変わります (ただし、**false** はデフォルトのままです)。 * **membersNeededToStart** のデフォルト値が 2 から 1 に変更されます。 * **joinTimeout** のデフォルト値が 5 秒から 10 秒に変更されます。 * **measurementTimeout** のデフォルトが 5 秒から 30 秒に変更されます。 * **/constants/system/timeouts** は削除され、タイムアウトは名前が変更され、**/constants/system** 配下に再配置されます。 * **reserved** タイムアウトは **reservedRemovalTimeout** になります。 * **inactive** タイムアウトは **inactiveRemovalTimeout** になり、新しいデフォルトは 2 時間ではなく 0 です。 * **ready** タイムアウトは **readyRemovalTimeout** になります。 * **sessionEmpty** タイムアウトは **sessionEmptyTimeout** になります。 * **/constants/system/capabilities/gameplay** は、直近プレイヤーおよび評判レポートを有効にするために、実際のゲームプレイを表すセッション (マッチやロビー セッションなどのヘルパー セッションとは対照的に) では **true** として指定する必要があります。 ### System オブジェクト セッション ドキュメント内の各 system オブジェクトには、MPSD によって強制および解釈される固定スキーマがあります。 PUT リクエストの本文内では、system オブジェクトはカスタム オブジェクトと同じように検証およびマージされます。 ただし、カスタム オブジェクトとは異なり、マージ後に system オブジェクトはこれらのスキーマに基づいてさらに検証および処理されます。 **/constants/system** ```json theme={null} { "version": 1, //Document Version (FAL release version 1, service contract 107) "maxMembersCount": 100, // Defaults to 100 if not set on creation. Must be between 1 and 100. "visibility": "private", // Or "visible" or "open", defaults to "open" if not set on creation. "initiators": [ "1234" ], // If specified on a new session, the creators xuid must be in the list (or the creator must be a server). "inviteProtocol": "party", // Optional URI scheme of the launch URI for invite toasts. "reservedRemovalTimeout": 10000, // Default is 30 seconds. Member is removed from the session. "inactiveRemovalTimeout": 0, // Default is zero. Member is removed from the session. "readyRemovalTimeout": 60000, // Default is three minutes. Member is removed from the session. "sessionEmptyTimeout": 0, // Default is zero. Session is deleted. // Capabilities are boolean values that are optionally set in the session template. If no capabilities are needed, an empty "capabilities" object should be in the template in order to prevent capabilities from being specified on session creation, unless the title desires dynamic session capabilities. "capabilities": { "clientMatchmaking": true, "connectivity": true, // Cannot be set if 'large' is specified. "suppressPresenceActivityCheck": false, "gameplay": false, "large": false }, /* If a "memberInitialization" object is set, the session expects the client system or title to perform initialization following session creation and/or as new members join the session. The timeouts and initialization stages are automatically tracked by the session, including QoS measurements if any metrics are set. These timeouts override the session's reservation and ready timeouts for members that have 'initializationEpisode' set. */ "memberInitialization": { "joinTimeout": 20000, // Milliseconds. Unspecified counts as 10 seconds. "externalEvaluation": false, "membersNeededToStart": 2 // Unspecified counts as 1. Must be between 0 and maxMembersCount. Only applies to episode 1. If 00 and the session is created with no members to initialize, episode 1 is skipped.. }, ``` **/properties/system** ```json theme={null} { // Optional array of case-insensitive strings. Cannot be set if the session's visibility is "private". "keywords": [ "hello" ], // Array of integer indices of members whose turn it is. Defaults to empty. Can't be set (and doesn't appear) on large sessions. "turn": [ 0 ], /* Restricts who can join "open" sessions. (Has no effect on reservations, which means it has no impact on "private" and "visible" sessions.) Defaults to "none". On large sessions, "none" is the only valid value. If "local", only users whose token's DeviceId matches someone else already in the session and "active": true. If "followed", only local users (as defined above) and users who are followed by an existing (not reserved) member of the session can join without a reservation. */ "joinRestriction": "none", // Device token of the host. Must match the "deviceToken" of at least one member, otherwise this field is deleted. // If "peerToHostRequirements" is set and "host" is set, the measurement stage assumes the given host is the correct host and only measures metrics to that host. // Can't be set on large sessions. "host": "99e4c701", // Can only be set while "initializing/stage" is "evaluating". True indicates success, and false indicates failure. Once set, "initializing/stage" is immediately updated, and this field is removed. "initializationSucceeded": true, /* The ordered list of case-insensitive connection strings that the session could use to connect to a game server. Generally titles should use the first on the list, but sophisticated titles could use a custom mechanism (e.g. Thunderhead) for choosing one of the others (e.g. based on load). */ "serverConnectionStringCandidates": [ "datacenter b", "serverfarm a" ], "matchmaking": { "targetSessionConstants": { }, // Force a specific connection string to be used (useful in preserveSession=always cases). "serverConnectionString": "datacenter b", }, // True if the match that was found didn't work out and needs to be resubmitted. Set to false to signal that the match did work, and the matchmaking service can release the session. "matchmakingResubmit": true } ``` ### タイムアウト セッションは、タイマーおよびその他の外部イベントによって変更される可能性があります。 MPSD の **Timeouts** オブジェクトは、セッション ライフタイムおよびメンバーを管理するための基本的なメカニズムを提供します。 セッションの **nextTimer** フィールドは、次のタイマーの時刻を示します。 クライアントはこの情報を使用して、次のポーリングに適した間隔を選択できます。 この値は **Expires** HTTP ヘッダーでも返されます。 タイムアウトはミリ秒で指定されます。 0 が許可され、タイムアウトが即時であることを意味します。 指定されたタイムアウトが指定されていない場合は、無限と見なされます。 タイムアウトにはデフォルトがあるため、セッション テンプレートは無限タイムアウトを明示的に "null" として指定する必要があります。 #### SessionEmptyTimeout **/constants/system/sessionEmptyTimeout** の値は、セッションが空になってから削除されるまでのミリ秒数を構成します。 デフォルトは 0 で、セッションはすぐに削除されます。 値が指定されていない場合、空のセッションは無期限に存続します。 #### メンバー タイムアウト **/constants/system** 内の他の 3 つのタイムアウトは、メンバーが特定の状態にとどまれる時間を制御します。 * **reservedRemovalTimeout** * タイムアウトが経過すると予約は削除されます。デフォルトは 30 秒です。 * **inactiveRemovalTimeout** * 非アクティブ メンバーは、デフォルトで 2 時間後にセッションから削除されます。 * **readyRemovalTimeout** * "ready" 状態のメンバーは、デフォルトで 3 分後に非アクティブ状態に戻ります。 ## セッション ドキュメントにおけるメンバー初期化 ### メンバー初期化 **memberInitialization** オブジェクトは、セッション作成後および/または新しいメンバーがセッションに参加する際の初期化ステージを制御します。 タイムアウトと初期化ステージは、任意のメトリックが設定されている場合の QoS 測定を含め、セッションによって自動的に追跡されます。 これらのタイムアウトは、**initializationEpisode** プロパティが設定されているメンバーに対して、セッションの reservation および ready タイムアウトをオーバーライドします。 例: ```json theme={null} "memberInitialization": { "joinTimeout": 5000, "measurementTimeout": 5000, "evaluationTimeout": 5000, // only specify for external evaluation "externalEvaluation": true, "membersNeededToStart": 2 }, ``` **図 3. メンバー初期化フロー:** ![メンバー初期化フローチャート](https://mintcdn.com/microsoft-4404708b/ktEik-YaZoen6Rhy/images/gdk/services/mpsd_image2.png?fit=max\&auto=format\&n=ktEik-YaZoen6Rhy\&q=85\&s=e5001dd95e5ffc9dc9be2449160aaa0a) メンバー初期化の 3 つの各ステージはタイムアウトすることができます。 1. **joiningTimeout** * ユーザーがセッションに参加するための時間 (ミリ秒単位)。参加できなかったメンバーの予約は削除されます。 2. **measuringTimeout** * メンバーが測定値をアップロードする時間。測定値のアップロードに失敗したメンバーは、*failureReason* が "timeout" とマークされます。 3. **evaluationTimeout** * メンバーが評価判定を行い、アップロードするための時間。判定が受信されなかった場合は失敗としてカウントされます。 **externalEvaluation** * MPSD は、セッション テンプレートで提供される要件に基づいて自動 QoS 評価を実行できます。externalEvaluation が false に設定されている場合、評価が実行されます。**evaluationTimeout** が設定されている場合、**externalEvaluation** は **true** である必要があります。ピアツーピアまたはピアツーホストの要件が 2 つある場合でも、セッションが自動的に初期化を完了できるように **externalEvaluation** を **false** に設定する必要があります。 **membersNeededToStart** * これは、自動評価が成功するために、"initialize":"true" が設定されて QoS をパスする必要があるメンバー予約の最小数です。 ### 初期化エピソード **memberInitialization** オブジェクトが設定されている場合、MPSD は初期化フェーズをエピソードごとに進めます。 最初のエピソードはセッションが作成されたときに開始され、テンプレートで定義されたすべてのフェーズを含みます。 エピソードが既に実行中に招待または参加した新しいメンバーは、次のエピソード用にマークされます。 エピソードや **memberInitialization** 全般の状態は、セッションの **initializing** オブジェクトから取得できます。 **注意** このオブジェクトは初期化完了後に削除されることに注意してください。 例: ```json theme={null} "initializing": { "stage": "measuring", "stageStartTime": "2009-06-15T13:45:30.0900000Z", "episode": 1 }, ``` ステージは joining から measuring、evaluating へと進みます。 エピソードが失敗した場合、ステージは *failed* に設定され、セッションは初期化できません。 それ以外の場合、初期化エピソードが完了すると、**initializing** オブジェクトは削除されます。 初期化の失敗は、各メンバーごとに追跡することもできます。 それらは、このメンバーがパスしなかった場合に joining または measuring ステージから移行する際に設定されます。 例: ```json theme={null} "initializationFailure": "latency", ``` 優先順位順に、この属性の値は *timeout、latency、bandwidthdown、bandwidthup、network、group*、または *episode* に設定できます。 network 値は、ネットワーク構成および/または条件 (競合するネットワーク アドレス変換 \[NAT] など) が QoS メトリックの測定を妨げたことを意味します。 joining の終了時に唯一可能な値は *group* です。 (joining のタイムアウトから、予約は削除されます。) **memberInitialization** が設定されており、メンバーが "initialize": true で追加された場合、これはメンバーが参加する初期化エピソードに設定されます。作成時に新しいセッションに追加されたメンバーには 1 の値が使用され、初期化エピソードが終了すると削除されます。 ```json theme={null} "initializationEpisode": 1, ``` ## マッチ チケット セッション MPSD セッションがマッチ チケット セッションとして使用される場合、いくつかの特別なセッション プロパティおよび定数が使用されます。 **/members/{index}/constants/system** ```json theme={null} { { "xuid": "12345678", "initialize": "false", // Run initialization for this user (if "memberInitialization" is set). Defaults to false. ``` Matchmaking サービスがユーザーをセッションに追加する場合、**matchmakingResult** フィールドに、それらがどのようにそしてなぜセッションにマッチされたかに関するコンテキストを提供します。 ```json theme={null} "matchmakingResult": { ``` これは、マッチメイキング セッションからのユーザーの **serverMeasurements** のコピーです。 ```json theme={null} "serverMeasurements": { "east.thunderhead.azure.com": { "latency": 233 // Milliseconds } } } } ``` ## Quality of Service (QoS) テンプレート ゲーム セッション テンプレートには、MPSD にネットワーク レイヤーおよびコンソール ソーシャル機能と連携するように通知する値を追加できます。 この連携の目的は、セッションが作成される前、およびゲームに参加準備完了とユーザーに通知される前に、接続状態の品質を検証することです。 以下のコード抜粋は、QoS を使用したピアツーホスト ゲーム セッション テンプレートの例です。 ```json theme={null} { "constants": { "system": { "version": 1, "maxMembersCount": 20, "visibility": "private", "capabilities": { "connectivity": true }, "memberInitialization": { "joinTimeout": 20000, "externalEvaluation": false, "membersNeededToStart": 1 }, "peerToHostRequirements": { "latencyMaximum": 350, "bandwidthDownMinimum": 1000, "bandwidthUpMinimum": 100, "hostSelectionMetric": "latency" } }, "custom": {} } } ``` このコード抜粋は、QoS を使用したピアツーピア ゲーム セッション テンプレートの例です。 ```json theme={null} { "constants": { "system": { "version": 1, "maxMembersCount": 20, "visibility": "private", "capabilities": { "connectivity": true }, "memberInitialization": { "joinTimeout": 20000, "externalEvaluation": false, "membersNeededToStart": 1 }, "peerToPeerRequirements": { "latencyMaximum": 250, "bandwidthMinimum": 10000 } }, "custom": {} } } ``` ### QoS セッション テンプレート属性 **memberInitialization** オブジェクトが設定されている場合、セッションはクライアント システムまたはタイトルがセッション作成後および/または新しいメンバーがセッションに参加する際に初期化を実行することを想定します。 タイムアウトと初期化ステージは、任意のメトリックが設定されている場合の QoS 測定を含め、セッションによって自動的に追跡されます。 これらのタイムアウトは、**initializationEpisode** プロパティが設定されているメンバーに対して、セッションの reservation および ready タイムアウトをオーバーライドします。 ```json theme={null} "memberInitialization": { "joinTimeout": 5000, // Milliseconds. Unspecified counts as 10 seconds. "measurementTimeout": 5000, // Milliseconds. Unspecified counts as 30 seconds. "evaluationTimeout": 5000, // Milliseconds. Can only be set if 'externalEvaluation' is true. Unspecified counts as 5 seconds. "externalEvaluation": true, "membersNeededToStart": 2 // Unspecified counts as 1. Must be between 0 and maxMembersCount. Only applies to episode 1. If 0 and the session is created with no members to initialize, episode 1 is skipped. }, ``` QoS を持つゲーム セッションには connectivity capability が必要です。 メトリックが指定されていない場合は、QoS 要件を満たすために必要なものにデフォルト設定されます。 指定されている場合は、QoS 要件を満たすのに十分でなければなりません。 ```json theme={null} "metrics": { "latency": true, "bandwidthDown": true, "bandwidthUp": true, "custom": true ``` 以下のしきい値は、セッション内のすべてのメンバーの各ペアワイズ接続に適用されます。 ```json theme={null} "peerToPeerRequirements": { "latencyMaximum": 250, // Milliseconds "bandwidthMinimum": 10000 // Kilobits per second }, ``` 以下のしきい値は、ホスト候補からの各接続に適用されます。 ```json theme={null} "peerToHostRequirements": { "latencyMaximum": 250, // Milliseconds "bandwidthDownMinimum": 100000, // Kilobits per second "bandwidthUpMinimum": 1000, // Kilobits per second "hostSelectionMetric": "bandwidthup" // Or "bandwidthdown" or "latency". Not specified is the same as "latency". }, ``` 以下の潜在的なサーバー接続文字列を評価する必要があります (接続文字列は小文字である必要があることに注意してください)。 ```json theme={null} "measurementServerAddresses": { "east.thunderhead.azure.com": { "secureDeviceAddress": "r5Y=" // Base-64 encoded secure-device-address }, "west.thunderhead.azure.com": { "secureDeviceAddress": "rwY=" } } } ``` **members/{index}/properties/system** これらのフラグはメンバーのステータスと **activeTitle** を制御し、相互に排他的です (両方を **true** に設定するとエラーになります)。 それぞれについて、**false** は "存在しない" と同じです。デフォルトのステータスは "inactive"、つまりどちらも存在しないことです。 ```json theme={null} "ready": true, "active": false, // Base-64 blob, or not present. Empty-string is the same as not present. // 'capabilities/connectivity' must be enabled in order for this to be set. "secureDeviceAddress": "ryY=", // List of members in my group, by index. Each element must be an integer 0 <= n < 'membersInfo/next'. // During member initialization, if any members in the list fail, this member will also fail. "group": [ 5 ], // QoS measurements by lower-case device token. // Like all fields, "measurements" must be updated as a whole. It should be set once when measurement is complete, not incrementally. // Metrics can me omitted if they weren't successfully measured, i.e. the peer is unreachable. // If a "measurements" object is set, it can't contain an entry for the member's own address. "measurements": { "e69c43a8": { "latency": 5953, // Milliseconds "bandwidthDown": 19342, // Kilobits per second "bandwidthUp": 944, // Kilobits per second "custom": { } } }, // QoS measurements by game-server connection string. Like all fields, "serverMeasurements" must be updated as a whole, so it should be set once when measurement is complete. // If empty, it means that none of the measurements completed within the "serverMeasurementTimeout". "serverMeasurements": { "east.thunderhead.azure.com": { "latency": 233 // Milliseconds } }, // Subscriptions for shoulder taps on session changes. The 'profile' indicates which session changes to tap as well as other properties of the registration like the min time between taps. // The subscription is named with a client-generated GUID that is also sent back with the tap as a context ID. // Subscriptions can be added and removed individually, without affecting other subscriptions in the "subscriptions" object. // To remove a subscription, set its context ID to null. // (Like the "ready" and "active" flags, the "subscriptions" data is copied out and maintained internally, so the normal replace-all rule on system fields doesn't apply to "subscriptions".) "subscriptions": { "961dc162-3a8c-4982-b58b-0347ed086bc9": { "profile": "party", // Or "matchmaking", "initialization", "roster", "queueHost", or "queue" "onBehalfOfTitleId": "3948320593", // Optional decimal title ID of the registered channel. If not set the title ID is taken from the token. }, "709fef70-4638-4b94-905b-24cb02706eb5": null } } ``` ## QoS フェーズおよびセッション初期化の詳細 MPSD は、テンプレートがメンバー初期化を完了した後、ゲーム作成のための QoS 結果を追跡およびレポートします。 この操作の進行状況は、上記の [メンバー初期化](#_Member_initialization_in) セクションで説明したように、セッション ドキュメントの *initializing* オブジェクトによって表されます。 *initializing* オブジェクトには *stage* 属性があり、これは初期化の現在のステージを表します。 ステージは *joining* から *measuring*、*evaluating* へと進みます。 * 初期化エピソード #1 が失敗した場合、ステージは *failed* に設定され、セッションは初期化できません。それ以外の場合、初期化エピソードが完了すると、"initializing" オブジェクトは削除されます。**externalEvaluation** が **false** に設定されている場合、evaluating ステージはスキップされます。**metrics** と **measurementServerAddresses** のどちらも設定されていない場合、measuring ステージはスキップされます。 ```json theme={null} "initializing": { "stage": "measuring", "stageStartTime": "2009-06-15T13:45:30.0900000Z", "episode": 1 }, ``` * ホスト候補は、優先順に一覧表示されたデバイス トークンです。これらは、**peerToHostRequirements** が設定されており、**/properties/system/host** が設定されていない場合、初期化エピソード #1 の *measuring* ステージの後に設定されます。**/properties/system/host** オブジェクトが設定された後にクリアされます。 ```json theme={null} "hostCandidates": [ "ab90a362", "99582e67" ], "constants": { /* Property Bag */ }, "properties": { /* Property Bag */ }, "members": { "1": { "constants": { /* Property Bag */ }, "properties": { /* Property Bag */ }, ``` * *gamertag* 属性は、メンバーが受諾しており、そのメンバーの ゲーマータグ クレームが見つかった場合にのみ設定されます。 ```json theme={null} "gamertag": "stacy", ``` * *deviceToken* 属性は、メンバーがセキュア デバイス アドレスをアップロードするときに設定されます。等価比較に使用できる大文字と小文字を区別しない文字列です。 ```json theme={null} "deviceToken": "9f4032ba7", ``` * *reserved* 値は、ユーザーがセッション ドキュメントに対する最初の PUT リクエストを実行した後に削除されます。プレイヤーが予約された状態のとき、それは彼らがゲーム セッションに招待されているが、まだ受諾もしていなければ接続も評価されていないことを意味します。 ```json theme={null} "reserved": true, ``` * メンバーがアクティブな場合、*activeTitleId* は、メンバーがアクティブになっているタイトルを 10 進数で示します。 ```json theme={null} "activeTitleId": "8397267", ``` * この属性は、ユーザーがセッションに参加した時刻を指します。*reserved* が **true** の場合、*joinTime* は予約が行われた時刻になります。 ```json theme={null} "joinTime": "2009-06-15T13:45:30.0900000Z", ``` * このメンバーが properties/system/turn 配列に含まれている場合に存在し、そうでない場合は存在しません。 ```json theme={null} "turn": true, ``` * *initializationFailure* 属性は、メンバーがそのステージを正常にパスしなかった場合、joining または measuring ステージから移行するときにメンバー オブジェクトに設定されます。優先順位順に、*timeout*、*latency*、*bandwidthdown*、*bandwidthup*、*network*、*group*、または *episode* に設定できます。 *network* 値は、ネットワーク構成および/または条件 (競合するネットワーク アドレス変換 \[NAT] など) が QoS メトリックの測定を妨げたことを意味します。joining の終了時に唯一可能な値は *group* です。(joining のタイムアウトから、予約は削除されます。) *episode* 値は、joining または measuring ステージで失敗しなかった初期化エピソードのすべてのメンバーに対して、"evaluation" ステージが失敗した後に設定されます。 ```json theme={null} "initializationFailure": "latency", ``` * **memberInitialization** が設定されており、メンバーが "initialize": true で追加された場合、これはメンバーが参加する初期化エピソードに設定されます。作成時に新しいセッションに追加されたメンバーには 1 の値が使用されます。初期化エピソードが終了すると削除されます。 ```json theme={null} "initializationEpisode": 1, ``` * *next* 属性は、セッション内の次のメンバーのインデックス値を表します。追加するメンバーがこれ以上ない場合、以下の **membersInfo** オブジェクト内の *next* 属性と同じ値になります。 ```json theme={null} "next": 4 }, "4": { "next": 5 /* etc */ } }, "membersInfo": { "first": 1, // The first member's index. "next": 5, // The index that the next member added will get. "count": 2, // The number of members. "accepted": 1 // The number of members that are no longer 'pending'. }, "servers": { "name": { "constants": { /* Property Bag */ }, "properties": { /* Property Bag */ } } } } ``` ## XBOX Cloud Compute セッション (非推奨) XBOX Cloud Compute セッションには、セッションがゲーム サーバーへの接続に使用できる大文字と小文字を区別しない接続文字列の順序付きリストが含まれます。 一般に、タイトルはリストの最初の文字列を使用する必要がありますが、洗練されたタイトルはカスタム メカニズム (たとえば、負荷に基づく) を使用して他のいずれかを選択できます。 ```json theme={null} "serverConnectionStringCandidates": [ "west.thunderhead.azure.com", "east.thunderhead.azure.com" ], "matchmaking": { "clientResult": { // Requires the clientMatchmaking property. "status": "searching", // Or "expired", "found", "failed", or "canceled". "statusDetails": "Description", // Default is empty string. "typicalWait": 30, // The expected number of seconds waiting as a non-negative integer. "targetSessionRef": { "scid": "1ECFDB89-36EB-4E59-8901-11F7393689AE", "templateName": "capture-the-flag", "name": "2D58F65F-0E3C-4F1F-8277-2BC9873FDB23" } }, "targetSessionConstants": { }, // Force a specific connection string to be used (useful in preserveSession=always cases). "serverConnectionString": "west.thunderhead.azure.com", // True if the match that was found didn't work out and needs to be resubmitted. Set to false // to signal that the match did work, and the matchmaking service can release the session. "resubmit": true } } ``` \*\*/servers/{server-name}/properties/system \*\* ```json theme={null} { "lockId": "opaque56789", // If set, a matchmaking service is servicing this session. "status": "searching", // Or "expired", "found", "failed", or "canceled". Optional. "statusDetails": "Description", // Optional free-form text. Default is empty string. "typicalWait": 30, // Optional. The expected number of seconds waiting as a non-negative integer. "targetSessionRef": { // Optional. "scid": "1ECFDB89-36EB-4E59-8901-11F7393689AE", "templateName": "capture-the-flag", "name": "2D58F65F-0E3C-4F1F-8277-2BC9873FDB23" } } ``` ## Raw セッションおよびカスタム タイトル プロパティ セッションは、マルチプレイヤー ゲームに関するカスタム ハウスキーピング情報 (メタデータ) を保存するために使用できます。 ゲーム データや保存された情報は TMS++ に保存する必要があります。 ### プロパティ バッグ 上記のプロパティ バッグとしてマークされたオブジェクトはそれぞれ、system と custom という 2 つのオプションの内部オブジェクトから構成されます。 custom オブジェクトには任意の JSON を含めることができます。 ```json theme={null} "custom": { "myField1": true, "myField2": "string", "myField3": 5.5, "myField4": { "myObject": null }, "myField5": [ "my", "array" ] } ``` ## アクティブ メンバーの減衰 MPSD がユーザーがタイトルに関与していないことを検出すると、アクティブ メンバーは自動的に非アクティブとマークされます。 これは、たとえば Presence がユーザー レコードをタイムアウトした場合に発生する可能性があります。 このメカニズムはあくまでバックストップです。つまり、タイトルはメンバーがタイトルから離れたり切り替えたり、サインアウトしたり、その他の方法で関与しなくなった場合に、それらのメンバーを非アクティブとしてマークする (またはセッションから削除する) ことを引き続き積極的に行う必要があります。 ## FAQ とトラブルシューティング ### MPSD を呼び出すにはどうすればよいですか? 証明書認証の使用: client-sessiondirectory.xboxlive.com 例: ```uri theme={null} PUT https://client-sessiondirectory-stress.xboxlive.com/serviceconfigs/8cvda84-2606-4bab-8eda-d12313e65143/sessiontemplates/teamDeathmatch/sessions/3baafc35-816d-49cd-9656-5772506c988a ``` XToken 認証の使用: sessiondirectory.xboxlive.com 例: ```uri theme={null} PUT https://sessiondirectory-stress.xboxlive.com/serviceconfigs/8cvda84-2606-4bab-8eda-d12313e65143/sessiontemplates/teamDeathmatch/sessions/3baafc35-816d-49cd-9656-5772506c988a ``` ### 使用する SCID、セッション テンプレート、サンドボックスはどうやって調べればよいですか? この情報は、タイトルの Partner Center で確認できます。 まだ Partner Center へのアクセス権をお持ちでない場合は、開発者アカウント マネージャーに連絡してください。情報を取得するお手伝いをします。 ### 自分のリクエスト本文と比較できるリクエスト本文の例はありますか? ### MPSD を呼び出すと 404 エラーが発生します。 Fiddler トレースを収集して詳細情報を取得し、次を実行してください: 1. HttpResponse 本文の一部として返されたメッセージで、一般的な 404 メッセージを確認します。 * *The requested service config is either invalid or not configured for sessions*。使用されている SCID が正しいことを確認します。 * *The requested session wasn't found*。取得する前にセッションが作成されており、セッション テンプレートが正しいことを確認します。PUT 呼び出しでセッションを作成できます。 2. 使用している URI を確認します。 3. コンソールを再起動するか、新しいユーザーで再試行します。 ### MPSD を呼び出すと 403 エラーが発生します。 これは通常、権限またはスコープの問題です。 Fiddler トレースを収集して詳細情報を取得し、次を実行してください: 1. HttpResponse 本文の一部として返されたメッセージで、一般的な 403 メッセージを確認します。 * *The requested service config cannot be accessed.* * サンドボックスにアクセス権を持つアカウントを使用していることを確認します。 * 正しいサンドボックス内にいることを確認します。 * 証明書認証を使用していてこのエラーが発生した場合は、DAM に連絡してください。 * *The requested session cannot be accessed. Private Sessions can only be read by members of the session.* * 可視性が "private" のセッションにアクセスしようとしています。セッション内のメンバーのみがセッション ドキュメントを読むことができます。 * *The request body can't contain existing member references unless the authentication principal includes a server.* * ユーザーの代わりに他のユーザーをセッションに参加させることはできません。招待のみ可能です。プレイヤーを招待するには、インデックスを "reserve\_\" に設定します。 ### 412 Precondition Failed エラーが発生します。 セッションが既に存在する場合、これは 412 Precondition Failed を返します: ```http theme={null} > PUT /serviceconfigs/00000000-0000-0000-0000-000000000000/sessiontemplates/quick/sessions/foo HTTP/1.1 > Content-Type: application/json > If-None-Match: \* ``` セッションの etag が If-Match ヘッダーと一致しない場合、これは 412 Precondition Failed を返します: ```http theme={null} > PUT /serviceconfigs/00000000-0000-0000-0000-000000000000/sessiontemplates/quick/sessions/foo HTTP/1.1 > Content-Type: application/json > If--Match: 9555A7DE-8B91-40E4-8CFB-0629312C9C7D ``` ### MPSD を呼び出すと 405、409、503、400 などのエラーが発生します。 Fiddler トレースを収集して詳細情報を取得し、HttpResponse 本文の一部として返されたメッセージを確認します。 XSAPI を使用している場合、[HCSettingsSetTraceLevel](https://devdocs.xbox.com/ja-jp/reference/live/httpclient/trace/functions/hcsettingssettracelevel.md) プロパティを [HCTraceLevel](https://devdocs.xbox.com/ja-jp/reference/live/httpclient/trace/enums/hctracelevel.md)::Information に設定することで応答本文を取得することもできます。[HCTraceSetTraceToDebugger](https://devdocs.xbox.com/ja-jp/reference/live/httpclient/trace/functions/hctracesettracetodebugger.md) が設定されている場合はデバッグ出力に情報が出力されます。または、[HCTraceSetClientCallback](https://devdocs.xbox.com/ja-jp/reference/live/httpclient/trace/functions/hctracesetclientcallback.md) を使用して、ゲーム独自のトレース ログにトレース ログを追加できるコールバックを取得できます。また、[XblAddServiceCallRoutedHandler](https://devdocs.xbox.com/ja-jp/reference/live/xsapi-c/xbox_live_global_c/functions/xbladdservicecallroutedhandler.md) を使用して、各サービス呼び出しに対して呼び出されるようにし、独自のログにルーティングすることもできます。 ### タイトルのテンプレートで何を変更できますか、または変更する必要がありますか? セッション テンプレートはデフォルトではなく、むしろ型のようなものです。 ただし、テンプレートで既に設定されている定数をオーバーライドすることはできませんが、追加することはできます。 ### セッションが初期化されていないというエラーが表示されます。 メンバー初期化がテンプレートに存在する場合 (通常はゲーム、パーティ、およびマッチ チケットのシナリオ)、この問題を解決するには、QoS をパスするのに十分な数のメンバー予約 (start に必要なメンバー数) に "initialize=true" が設定されていることを確認する必要があります。 ### セッションが作成されず、HTTP 204 エラーが発生します。 これは、セッションを作成したときにセッションに追加されたユーザーがいなかったことを示します。 作成時にセッションのユーザーがいない場合、セッションは作成されません。 作成時に少なくとも 1 人のプレイヤーをセッションに追加していることを確認します。 専用サーバー シナリオでは、マッチを作成しようとしている、またはマッチを作成する必要があるプレイヤーを取得し、そのユーザーをそのマッチの初期プレイヤーにします。 あるいは、**sessionEmptyTimeout** を変更または削除することもできます。 ### MPSD をポーリングするタイミングは? MPSD セッションのポーリングは避けるべきです。 高レベルでは、各クライアントのネットワーク接続の初期確立、および接続を失ったクライアントのためのネットワーク状態の再確立にのみ MPSD セッションを使用する方法でコードを設計することによってこれを行うことができます。 競合状態を解決するためにセッション状態を更新する必要をなくすため、MPSD の etag ベースの同期プリミティブを活用することも重要です。 これらの原則の一般的な適用は、N クライアントのセットがすべて接続してピアツーピア メッシュでプレイする必要がある場合です。 新しいメンバーのためにセッションを定期的にクエリするのではなく、各メンバーはセッションに参加し、既にセッションにいるメンバーに接続し、後の参加者も同じことをすると想定できます。 これを実装する方法の例については、Chat および Player Rendezvous サンプルを参照してください。 短期間ポーリングが必要になるまれなケースもあります。これが必要だと思われる場合は、開発者アカウント マネージャーに連絡してください。 ## Related topics - [マルチプレイヤー サービスを直接呼び出すことの概要](https://devdocs.xbox.com/ja-jp/services/xbox-services/multiplayer/concepts/live-intro-calling-mp-directly.md) - [Multiplayer Session Directory (MPSD)](https://devdocs.xbox.com/ja-jp/services/xbox-services/multiplayer/mpsd/live-mpsd-nav.md) - [Multiplayer Session Directory の概要](https://devdocs.xbox.com/ja-jp/services/xbox-services/multiplayer/mpsd/live-mpsd-overview.md) - [Multiplayer Session Directory (MPSD) の概念 (目次)](https://devdocs.xbox.com/ja-jp/services/xbox-services/multiplayer/mpsd/concepts/live-mpsd-concepts-nav.md) - [Multiplayer Session Directory (MPSD) のサンプルコード](https://devdocs.xbox.com/ja-jp/services/xbox-services/multiplayer/mpsd/how-to/live-mpsd-howto-nav.md)