マルチプレイヤー セッション ディレクトリの概要

このトピックでは、マルチプレイヤー セッション ディレクトリ (MPSD) サービスによって、タイトルが、ユーザー グループの接続に必要な基本情報を共有できるようにする方法を説明します。

MPSD は、招待が送信および受け入れられるとき、およびユーザーがゲーマー カード経由で参加するときに、シェルおよび本体のオペレーティング システムと調整します。

MPSD は、複数のクライアントにわたってゲームのマルチプレイヤー システム データを一元化します。 MPSD により、セッション機能が同期され、一貫性が保たれます。

MPSD は、Xbox サービス クラウドで稼働するサービスです。 これは、XblMultiplayer の関数でラップされます。

このトピックでは、以下の内容を説明します。

• MPSD セッション
• MPSD の変更通知処理および切断検出
• セッションへの MPSD ハンドル
• セッション更新の同期
• MPSD の呼び出し
• マルチプレイヤー セッション エクスプローラー

MPSD セッション

MPSD セッションは、XblMultiplayerSessionHandle によって識別され、1 人以上のユーザーがゲームをプレイするシナリオを表します。 セッションは、MPSD によって Xbox サービス クラウドにセキュア JSON ドキュメントとして格納されます。

MPSD セッションの具体的な特性は次のとおりです。

• タイトルによって作成され、管理されます。
• 一意の URI を持ちます。 詳細については、「セッション ディレクトリ URI」を参照してください。
• ユーザー (セッション メンバーと呼ばれます) 間の接続を可能にします。
• メンバーごとの属性、ゲーム設定、ブートストラップ情報、ゲーム サーバー情報など、ゲーム プレイを可能にする情報を格納します。

すべてのセッションに、プレイヤーの Xbox ユーザー ID (XUID) およびセキュア デバイス アソシエーション アドレス データが含まれます。

MPSD では、さまざまな種類のマルチプレイヤー ゲームを設定するためのセッションがいくつかサポートされています。これには、次のバリエーションが含まれます。

このトピックの先頭に戻る。

MPSD の変更通知処理および切断検出

クライアントは、リアルタイム アクティビティ (RTA) サービス Web ソケットを使用して MPSD に接続します。

接続は次の処理に使用されます。

• セッションの変更が発生したときに、タイトルが開始するイベント サブスクリプションに基づいて、簡単な通知 (ショルダー タップ) を送信する。
• ユーザーの切断を検出する。
• ユーザーを非アクティブとして設定し、切断検出に基づいてセッションからユーザーを削除する。

ユーザー接続の実行

Xbox サービス API (XSAPI) ライブラリは、クライアントと MPSD の間の接続を管理します。

1. タイトルが XblMultiplayerSetSubscriptionsEnabled を呼び出します。 このメソッドは、クライアントが、マルチプレイヤーを対象として RTA 接続を使用することを XSAPI に伝えます。

2. タイトルが現在のユーザーをアクティブな状態に設定して XblMultiplayerWriteSessionAsync または XblMultiplayerWriteSessionByHandleAsync を初めて呼び出すと、接続が作成されて MPSD に接続されます。

セッション変更のサブスクライブ

MPSD は、興味を引くことが変更されたことを簡単に伝えるためにショルダー タップを使用します。 サブスクリプションが有効になっている場合、タイトルは XblMultiplayerSessionSetSessionChangeSubscription を呼び出すことで、セッション変更のショルダー タップをサブスクライブできます。

詳細については、「マルチプレイヤー タスク」のトピックの「MPSD セッション変更通知のサブスクライブ」セクションを参照してください。

ショルダー タップの処理

セッションの変更がそのセッションのタイトルのサブスクリプションと一致した場合、MPSD は XblMultiplayerSessionChangedHandler ハンドラーを使用して、タイトルに変更を通知します。 その後、タイトルはセッションを取得し、取得したセッションのバージョンを以前にキャッシュしたビューと比較し、適切なアクションを実行します。

接続状態の変更に関する通知の処理

タイトルは、MPSD への接続の状態の変更について通知を受けることができます。

2 つのイベントが次の変更を通知します。

• XblMultiplayerSessionSubscriptionLostHandler ハンドラーは、RTA サービスを使用する MPSD へのタイトルの接続が失われたときに発生します。 このイベントが発生した場合、タイトルはマルチプレイヤーをシャットダウンする必要があります。
• XblRealTimeActivityConnectionStateChangeHandler ハンドラーは、RTA サービスへのタイトルの接続の正常性が一時的に変更されたときに発生します。 タイトルは、このイベントの受信時にアクションを実行する必要はありませんが、イベントは診断目的に役立つ場合があります。

クライアントの切断

タイトルのクライアントは、タイトルが XblMultiplayerSetSubscriptionsEnabled への呼び出しで通知を無効にすると、MPSD から切断されます。 この呼び出しの直後に、XblMultiplayerSessionSubscriptionLostHandler ハンドラーが発生し、クライアントが MPSD から切断されたことが示されます。

切断検出

MPSD は、その切断検出機能を使用して、ユーザーの正常でない切断をすばやく確認します。 正常でない切断の原因には、プレイヤーのネットワークが失敗したか、タイトルがクラッシュした場合が含まれます。

MPSD は、切断されたプレイヤーの状態を Active から Inactive に変更し、メンバーのセッションへのサブスクリプションに基づいて、必要に応じて他のセッション メンバーに変更を通知します。

RTA 再接続の処理

XSAPI は、切断時に RTA に再接続し、RTA サブスクリプションを再送信しようとします。 (詳細については、「RTA サービスのベスト プラクティス」を参照してください。) マルチプレイヤーの RTA サブスクリプションを再送信すると、MPSD セッションのユーザーをクライアントの RTA 接続に関連付けるために使用される接続 ID が更新されます。

XSAPI は、XblMultiplayerAddConnectionIdChangedHandler を使用して、MPSD 接続 ID の変更についてタイトルに通知します。 コールバック内では、タイトルは MPSD セッションに新しい接続 ID を記述する必要があります。 XblMultiplayerSessionCurrentUserSetStatus を呼び出してから、XblMultiplayerWriteSessionAsync を呼び出してセッションに記述することにより、新しい接続 ID をセッションに記述することができます。

void* context{ nullptr };
XblFunctionContext connectionIdChangedFunctionContext = XblMultiplayerAddConnectionIdChangedHandler(
    xblContextHandle,
    [](void* context) {
        XblMultiplayerSessionHandle sessionHandle; // Retrieve the MPSD session to update
        XblMultiplayerSessionCurrentUserSetStatus(sessionHandle, XblMultiplayerSessionMemberStatus::Active);

        auto asyncBlock = std::make_unique<XAsyncBlock>();
        asyncBlock->queue = queue;
        asyncBlock->context = nullptr;
        asyncBlock->callback = [](XAsyncBlock* asyncBlock)
        {
            std::unique_ptr<XAsyncBlock> asyncBlockPtr{ asyncBlock };

            XblMultiplayerSessionHandle sessionHandle;
            HRESULT hr = XblMultiplayerWriteSessionResult(asyncBlock, &sessionHandle);
            if (SUCCEEDED(hr))
            {
                // If the write call succeeds, the connection ID has been updated and no further action is needed.
            }
            else
            {
                // If the write call fails, it's likely that the user has been removed from the session.
            }
        };

        auto hr = XblMultiplayerWriteSessionAsync(xblContextHandle, sessionHandle, XblMultiplayerSessionWriteMode::UpdateExisting, asyncBlock.get());
        if (SUCCEEDED(hr))
        {
            asyncBlock.release();
        }
    }, 
    context);

このトピックの先頭に戻る。

セッションへの MPSD ハンドル

MPSD セッション ハンドルは、その他の型指定されたデータも含めることができるセッションへの抽象的で不変の参照です。 ファイル ハンドルに似ています。 すべてのハンドルには、ハンドル ID (GUID) と、サービス構成 ID (SCID)、セッション テンプレート、およびセッション名で構成される完全セッション参照があります。 ハンドルを更新することはできませんが、作成、読み取り、および削除は可能です。

ハンドルの型

2015 マルチプレイヤーでは、招待ハンドルとアクティビティ ハンドルがサポートされています。

招待ハンドル

招待ハンドルは、特定のユーザーへの招待を表します。 型固有のデータには、招待元のユーザー、招待対象のユーザー、招待を説明するコンテキスト文字列 (たとえば、特定のゲーム モード) があります。

招待ハンドルは、開いているセッションへの読み取り/書き込みアクセスを許可します。 セッションが閉じられている場合、ハンドルは読み取り専用のセッション アクセスを許可します。

招待ハンドルの作成

招待ハンドルを作成するには、タイトルが XblMultiplayerSendInvitesAsync を呼び出します。 このメソッドは、受信者が招待を受け入れるために操作できる通知で、指定されたユーザーに招待を送信します。

アクティビティ ハンドルの作成

アクティビティ ハンドルを作成するには、タイトルが XblMultiplayerSetActivityAsync を呼び出します。 MPSD は、新しいハンドル ID をセッション メンバーのバインドされたアクティビティとして設定します。

以前にバインドされたアクティビティがあった場合、MPSD は対応するハンドルを削除します。 アクティブなメンバーが非アクティブになるか、またはセッションから離れると、MPSD は、バインドされているアクティビティ ハンドルを削除します。

ハンドルを使用する

タイトルがハンドルを使用するのは、ユーザーが招待を受け入れたとき (招待ハンドル)、およびユーザーがフレンドの現在のアクティビティに参加したとき (アクティビティ ハンドル) です。

どちらの場合も、タイトルは次のアクションを実行する必要があります。

1. タイトルのアクティベーション パラメーターからハンドル ID を取得します。
2. ローカル MPSD セッション オブジェクトを作成し、それをアクティブとして参加させます。
3. 適切なハンドルを渡して、セッションを書き込みます。

このトピックの先頭に戻る。

セッション更新の同期

セッションは、メンバーのだれもが作成または更新できる共有リソースです。 その結果、競合する書き込みが発生する可能性があります。 これが予期しない結果につながることがあります。たとえば、あるタイトルが行った変更を別のタイトルが上書きしてしまう可能性があります。 MPSD でのこれらの競合の解決方法は、オプティミスティック同時実行制御および読み取り/変更/書き込みパターンをサポートすることです。

MPSD によるセッション更新の同期では、2 つの関連する高レベルの実装パターンを使用します。

• アービターは、セッションの共有部分を更新します。 実装に関わるアービターが 1 つの場合は、ほとんどの書き込み操作について同期更新の使用を回避できます。 タイトルは、次のいずれかの場合は、同期を回避できます。

  • セッションの共有部分に対してアービターが加えた更新 (アービターの ID の通信に関連する場合を除く)
  • セッション内のメンバー領域に対してタイトルが加えた更新

  注意

  前述の更新の種類は同期する必要はありませんが、XblMultiplayerSessionProperties::HostDeviceToken プロパティに更新を同期することは依然として重要です。 このプロパティは、アービターの識別情報を、たとえばアービター移行の一環として伝えるために使用されます。

• すべてのクライアントがセッションの共有部分を更新します。 この場合は、セッションの共有部分のすべての更新を同期する必要があります。 ただし、タイトルは引き続き同期せずに、自分のメンバー領域に書き込めることができます。

マルチプレイヤー API を使用した更新セッションの同期

次のマルチプレイヤー API のメソッドは、オプティミスティックな同時実行性を実装します。

• XblMultiplayerWriteSessionAsync
• XblMultiplayerWriteSessionByHandleAsync

各書き込みメソッドは、XblMultiplayerSessionWriteMode 値を受け取ります。 SynchronizedUpdate の値の受け渡しは、更新のオプティミスティックな同時実行性を利用します。

列挙内のその他の値は、セッションの最初の作成時の潜在的な競合の解決に役立ちます。 他のタイトルが書き込む可能性がある MPSD セッション部分への書き込みでは必ず、同期更新を使用する必要があります。 ただし、すべての書き込みを保護する必要はありません。

タイトルがローカル セッション オブジェクトをいずれかの書き込みセッション メソッドを使用して MPSD に書き込もうとすると、HTTP/412 ステータス コードを受け取る場合があります。 この場合、再び書き込みを試みる前に、XblMultiplayerGetSessionAsync の呼び出しを発行して最新のサーバー バージョンのセッションを取得してローカル コピーを更新する必要があります。 そうしないと、ローカル セッション ドキュメントは不良なデータを保持したままになり、セッションを書き込むための呼び出しは継続して失敗します。

マルチプレイヤー REST API を使用した更新セッションの同期

MPSD は、HTTP の "if-match" ヘッダーと ETag 設定および読み取り/変更/書き込みパターンを使用して、REST 機能を通じてセッション更新でオプティミスティック同時実行制御をサポートします。 書き込み要求に渡される ETag は、MPSD が前の読み取り要求で返したものである必要があります。

このトピックの先頭に戻る。

MPSD の呼び出し

タイトルは、次の方法で MPSD にアクセスして、マルチプレイヤー システムとマッチメイキングを使用できます。

• マルチプレイヤー API を使用することをお勧めします。これには、RESTful 機能のラッパーの役割を果たすクラスが含まれています。 詳細については、XblMultiplayer プレフィックス関数を参照してください。 SmartMatch マッチメイキングの場合、XblMatchmaking プレフィックス関数で表されるマッチメイキング API を使用します。
• 「Xbox サービス RESTful リファレンス」に含まれる、マルチプレーヤーおよびマッチメイキング REST API に対する直接の標準 HTTP 呼び出しを使用します。 適用可能な URI は、「セッション ディレクトリ URI」(マルチプレイヤー用) および「マッチメイキング URI」(マッチメイキング用) セクションに記載されています。 関連する JSON オブジェクトは、「JavaScript Object Notation (JSON) オブジェクト リファレンス」に記載されています。

マルチプレイヤー API を使用して MPSD を呼び出す

XSAPI でマルチプレイヤー と マッチメイキング API を使用して MPSD を呼び出すことをお勧めします。

基になる REST 機能のラッパー コードを使用すると、呼び出しごとに HTTP トラフィックを処理することなく、より従来的な方法でクライアント側 API メソッドを使用できます。

Multiplayer REST API を使用した MPSD との対話

タイトル、またはそのサービスでは、Multiplayer REST API および Matchmaking REST API への標準 HTTP 呼び出しを使用できます。 REST の機能を直接利用するとき、呼び出し元は、セッション ディレクトリの URI に対して DELETE、PUT、POST、および GET 呼び出しを発行してほとんどの操作を行います。 PUT 要求では、要求本文は既存のセッションにマージされます。

既存のセッションが存在しない場合は、要求本文は、パートナー センター に格納されているセッション テンプレートと共に新しいセッションを作成するために使用されます。

すべてのフィールドはオプションで、指定する必要があるのは差分だけです。 したがって、{} は、ゼロの差分が指定された有効な PUT 要求です。

サーバーのセッションの公式コピーに影響を与えずにマージの結果を返す仮定の PUT 要求を実行するには、クエリ文字列 ?nocommit=true を PUT 要求に追加できます。

Multiplayer および Matchmaking REST API メソッドの要求および応答は JSON ドキュメントです。 マルチプレイヤー セッションの要求構造については、「MultiplayerSessionRequest (JSON)」を参照してください。

関連する応答構造については、「MultiplayerSession (JSON)」を参照してください。 応答構造は、セッション メンバーをリンク リストとして構成し、セッションとそのメンバーのその他の読み取り専用プロパティを格納します。

セッションおよびセッション テンプレートのクエリ (REST)

タイトルでは、サービス構成およびセッション テンプレート レベルでセッション情報をクエリできます。 このセクションでは、Multiplayer REST API を使用するクエリについて説明します。

基本的なセッション情報のクエリ

セッション ディレクトリおよびマッチメイキング URI を使用して、基本的なセッション情報のクエリを設定できます。 クエリの結果はセッション参照の JSON 配列であり、一部のセッション データはインラインで取り込まれます。 既定では、クエリは、最大 100 件のプライベートでないセッションを取得します。

セッション テンプレートのクエリ

SCID のセッション テンプレートの一覧および特定のセッション テンプレートの詳細を取得するには、次のいずれかの URI に対して GET メソッドを使用します。

• /serviceconfigs/{scid}/sessiontemplates
• /serviceconfigs/{scid}/sessiontemplates/{sessionTemplateName}

セッション状態のクエリ

セッション状態をクエリするには、次のいずれかの URI に対して GET メソッドを使用します。

• /serviceconfigs/{scid}/sessions
• /serviceconfigs/{scid}/sessiontemplates/{sessionTemplateName}/sessions

このトピックの先頭に戻る。

マルチプレイヤー セッション エクスプローラー

マルチプレイヤー セッション エクスプローラーは MPSD に組み込まれたツールであり、セッション、セッション テンプレート、およびローカライズ文字列の参照に使用します。 このツールは、開発サンド ボックスでの使用のみを目的としています。

マルチプレイヤー セッション エクスプローラーへのアクセス

マルチプレイヤー セッション エクスプローラーにアクセスするには、Xbox One 以降のコンソールでブラウザーを開き、[表示] ボタンを押し、[アドレス] ボックスに「https://sessiondirectory.xboxlive.com/debug」と入力します。

メイン ページを開く

1. ツールのメイン ページを開きます。 サンドボックス内のセキュリティ コンテキスト (サインインしたユーザーおよびサンドボックス) と、SCID のリストが表示されます。

2. メニュー ボタンを押すと、このページがホームにピン留めされ、URI を再入力する必要がなくなります。

利用可能なセッションとテンプレートの表示

1. ツールで SCID を選択すると、その SCID 内の、サインインしたユーザーがメンバーになっているセッションの一覧が表示されます。

2. この同じページで SCID を選択すると、SCID のサービス構成内にあるセッション テンプレートとローカライズ文字列を表示できます。 これらの項目は、パートナー センターを通じて取り込まれます。

セッションのすべての内容の表示

マルチプレイヤー セッション エクスプローラーで、セッション名を選択し、対応するセッションのすべての内容を表示します。

MPSD によって示されるセッションは、次の理由により、セッションの URI に対する標準の GET メソッドへの応答とは異なる場合があります。

• GET 呼び出しは X-Xbl-Contract-Version ヘッダーで古いコントラクト バージョンを使用している場合があります。 マルチプレイヤー セッション エクスプローラーは常に最新のコントラクト バージョンでセッションを表示します。

• セッションが通常どおり GET を介して要求されたときに、期限の切れるタイムアウトなど、変換や副作用がトリガーされる場合があります。 マルチプレイヤー セッション エクスプローラーはロジックの実行、変換、または副作用を伴うことなく、保存されているセッションのスナップショットをそのまま表示します。

• nextTimer JSON オブジェクト フィールドはこの副作用と同時に計算されるため、MPSD セッションには存在しません。

このトピックの先頭に戻る。

関連項目

• 「マルチプレイヤー セッションの高度なトピック」のトピックの「セッションの概要」セクション
• マルチプレイヤー セッション ステータス コード
• 「マルチプレイヤー タスク」のトピックの「MPSD セッションの更新」セクション
• 「マルチプレイヤー タスク」のトピックの「タイトルのアクティベーションからの MPSD セッションへの参加」セクション
• 「マルチプレイヤー タスク」のトピックの「MPSD セッション変更通知のサブスクライブ」セクション
• マッチメイキングの概要

このトピックの先頭に戻る。