サービス間 (S2S) でのマルチプレイヤーセッション管理

このトピックでは、Multiplayer Session Directory (MPSD) におけるサービス間 (S2S) の呼び出しパターンの使い方について説明します。他のサービスと同様に、MPSD は S2S 呼び出しパターンをサポートしています。これらはクライアントの呼び出しパターンを拡張したもので、単一のサービス呼び出しでタイトルサービスから複数ユーザーを効率的に管理できるようにします。クライアントではなくタイトルサービス経由でマルチプレイヤーセッションを管理することで、エラー処理ロジックを簡素化し、セッション書き込み操作における競合状態を回避できます。これは特に、メンバー数が多い大規模なセッションタイプに当てはまります。したがって、大規模多人数同時参加型オンラインゲーム (MMO) や、1 セッションあたりのプレイヤー数が多いタイトルでは、MPSD セッションをタイトルサーバー経由で管理することがベストプラクティスとなります。 RESTful な MPSD 呼び出しパターンに関する一般的な情報については、XBOX services RESTful リファレンスを参照してください。

MPSD S2S 認証

XBOX services の Multiplayer サービスに対する S2S 呼び出しの認証は、他の XBOX services とは異なります。Delegation トークンを使用した呼び出しはサポートされておらず、サービス認証を使用した呼び出しのみが機能します。この認証方式によって、MPSD S2S の追加機能を利用できます。他の S2S 呼び出しと同様に、Business Partner Certificate が必要です。フルアクセスの Multiplayer.Manage ポリシーが必要です。これは、Business Partner Certificate が作成された Web サービスが S2S 呼び出しに対して正しいアクセスレベルを提供できるようにするために必要です。サービス認証には次の認証フローが使用されます。

Business Partner Certificate を使用して XBOX Authorization Service for Services を呼び出し、S トークンを取得します。
この S トークンと SandboxId を使用して XBOX Secure Token Service (XSTS) を呼び出し、X トークンを取得します。このステップで Delegation トークンや User トークンを使用してはなりません。このフローで指定する SandboxId は、Business Partner Certificate の作成時に指定したサンドボックスのセットに含まれている必要があります。特定のサンドボックスなしで作成された Business Partner Certificate はサポートされておらず、サンドボックスが不足していることを示す認証エラーの原因となります。
X トークンとヘッダー (次のセクションで指定) を使用して MPSD サービスを呼び出します。

MPSD S2S ヘッダー

タイトルヘッダー

正しいタイトルとして動作するために、X-Xbl-OnBehalfOf-Title ヘッダーが以下の形式で必要です。

X-Xbl-OnBehalfOf-Title:[titleid in decimal]

例

Request.Headers["X-Xbl-OnBehalfOf-Title"] = "484921321";

このヘッダーは、特定のタイトルに対する呼び出しを行うために指定する必要があります。

ユーザーヘッダー

特定のユーザーまたはユーザーのセットとして動作するために、X-Xbl-OnBehalfOf-Users ヘッダーが以下の形式で必要です。

X-Xbl-OnBehalfOf-Users:[xuid][;privilege][,xuid[;privilege]]...

例

Request.Headers["X-Xbl-OnBehalfOf-Users"] = "741837829132;priv=multiplayer","8922333146718;priv=multiplayer"

現在サポートされている特権は priv=multiplayer のみです。これはユーザーがマルチプレイヤー特権を持っていることを示します。 X-Xbl-OnBehalfOf-Users ヘッダーを使用する場合、ヘッダーで識別されるユーザーが自分のコンソールから直接呼び出しを行っているかのように扱われます。そのため、呼び出し元サービスはユーザーのセキュリティを維持する責任があります。

実際の XUID のみを使用できます。
ユーザーに対して宣言する特権は正しくなければなりません。
ユーザーは、自分に代わって実行される任意のアクションに同意している必要があります。

最後の要件は、コンソール上のタイトル自体が実行できたであろう操作のみをサービスが実行できることを意味します。たとえば、ユーザーが実際にコンソール上でそのタイトルを起動して操作している場合にのみ、サービスはそのユーザーをアクティブとして設定できます。ユーザーがコンソール上のタイトルとやり取りしなくなったら、サービスはそのユーザーを非アクティブに設定する必要があります。同様に、ユーザーが招待を送信する明示的なアクションを行った場合にのみ、サービスは代わりに招待を送信できます。

Deny-Scope ヘッダー

Multiplayer.Manage アクセスポリシーは、MPSD サービスへの S2S 呼び出しに対して、ユーザーのアクセス権限を上書きします。そのため、セッションへのアクセスはユーザーの権限に基づいて制限されません。ユーザーの権限チェックを再度有効にするには、次のように X-Xbl-Deny-Scope ヘッダーを使用できます。

    X-Xbl-Deny-Scope: Multiplayer.Manage

例

    Request.Headers["X-Xbl-Deny-Scope"] = "Multiplayer.Manage";

このヘッダーは、ユーザー (ユーザーヘッダーによる) のセッションへのアクセスを確認する際に、Multiplayer.Manage アクセスポリシーが上書きとして使用されないようにします。これは、ユーザーがセッションに対する正しいアクセス権を持っており、可視性や参加制限のためのブロックがサーバーアクセスによって上書きされていないことを確認するために使用できます。

このヘッダーを設定する場合は、フォールバックとして Web サービスに Multiplayer.Runtime アクセスを付与する必要もあります。これにより、ユーザーの権限が拒否された場合でもアクセスが可能になります。それ以外の場合、エラーシナリオでサービスアクセスは付与されず、403 ステータスが返されます。Multiplayer.Runtime アクセスにはアクティングユーザーが必要です。X-Xbl-Deny-Scope ヘッダーは、X-Xbl-OnBehalfOf-Users または DelegationToken クレームから取得したユーザークレームと組み合わせた場合にのみ機能します。

セッションメンバー管理

複数ユーザーを 1 回の呼び出しで扱うことで、S2S 呼び出しのセッションメンバー管理を最適化できます。ユーザーヘッダーを指定する場合、セッションドキュメント本文内の標準的な “me” メンバーは使用できません。代わりに次のオプションが利用できます。

{
    "members": {

        // (For example, me_59135345328) Requires a user principal with an xuid claim.
        "me_{xuid}": {
            "constants": { /* Property Bag */ },
            "properties": { /* Property Bag */ },
        },

        // Applies the requested change to each acting user's member.
        "me_all": {
            "constants": { /* Property Bag */ },
            "properties": { /* Property Bag */ },
        },

        // Applies the requested change to each acting user's member if they're 
        // already in the session.
        "me_allInSession": {
            "constants": { /* Property Bag */ },
            "properties": { /* Property Bag */ },

        // Requires a single user principal with an xuid claim.
        "me": {
            "constants": { /* Property Bag */ },
            "properties": { /* Property Bag */ },
        },

        }
    }
}

タイトルサービスでは、これらのパターンを使用して、単一の MPSD 呼び出しで複数のユーザーに対する操作 (プレイヤーの追加や削除など) を実行してください。

セッションメンバーの追加

前述のパターンのいずれかを使用して、セッションメンバーを追加または変更できます。一般に、プレイヤーを追加する最小の操作はプロパティまたは定数、通常はメンバーのアクティブステータスプロパティを設定することです。

アクティブに設定されていないメンバーは、MPSD セッションの InactiveTimeout 値に依存するサービスによって自動的に削除されます。

必要に応じて、同じ呼び出しでユーザーに対する他の必要なプロパティおよび定数を設定してください。

{
    "members": {

        "me_{xuid}": {
            "constants": { /* Property Bag */ },
            "properties": { "system": { "active": true } 
                            /* Additional Properties */ },
        }
    }
}

例

{
     // Adding two session members with one call.
    "members": {

        "me_1234567890123456": {
            "properties": { "system": { "active": true }},
        },

        "me_2345678901234567": {
            "properties": { "system": { "active": true }},        
        } 
    }
}

セッションメンバーの削除

メンバーセクションを null に設定することで、セッションメンバーを削除できます。

{
    "members": {

        "me_{xuid}": {
            null,
        }
    }
}

例

{
     // Removing two session members with one call.
    "members": {

        "me_1234567890123456": {
            null,
        },

        "me_2345678901234567": {
            null,
        } 
    }
}

メンバー予約

一般に、すべてのセッション管理がタイトルサービスによって行われる場合は、セッションメンバーの予約は不要です。このシナリオでは、予約を必要とせずにセッションメンバーを直接追加または削除できます。セッションメンバーの予約は、作成されたセッションがクライアントによっても管理される場合にのみ使用してください。 on-behalf-of-user ヘッダーで指定したユーザーの順序で、複数ユーザーに対するセッション予約を追加できます。次のパターンは新しいセッションを作成する場合にのみ有効です。

{
    "members": {

        // Reservation requests must start with zero.
        "reserve_0": {
            "constants": { "system": {"xuid": "{xuid}" }
                           /* additional constants */ }
        },

        "reserve_1": {
            "constants": { "system": {"xuid": "{xuid}" }
                           /* additional constants */ }
        },

        //...//

    }
}

例

{
     // Adding reservations for two session members with one call.
    "members": {

        "reserve_0": {
            "constants": { "system": {"xuid": "1234567890123456" }}
        },

        "reserve_1": {
            "constants": { "system": {"xuid": "2345678901234567" }}
        },
    }
}

大規模セッションでは予約はサポートされていません。予約と、セッションメンバーの追加または削除を混在させることはサポートされていません。

セッションメンバーの状態

タイトルサービスは、system プロパティを通じてセッションメンバーの状態を追跡・設定できます。これにより、メンバーの状態と情報を完全に制御できます。

メンバーのアクティブステータス

メンバーのアクティブステータスは、プレイヤーをセッション内でアクティブとしてマークします。これにより、inactiveRemovalTimeout セッション構成で定義されたシステムによる削除を防ぎます。

{
    "members": {

        // Member access through XUID.
        "me_{xuid}": {
            "properties": { "system": {"active": [true|false] }
                           /* additional constants */ }
        }
    }
}

一般に、セッションに追加されたセッションメンバーは常に active に設定してください。非アクティブなメンバーは、切断されてもセッションメンバーを一時的にセッションに残しておくべきフローでのみ使用してください。S2S フローでは、これもタイトルサーバーで直接管理できます。

メンバーの予約ステータス

reserved member プロパティを通じて、セッションメンバーの予約ステータスを判断できます。このプロパティが true に設定されている場合、そのセッションメンバーは予約された状態であり、まだセッション内でアクティブではありません。以下はセッションドキュメントの例です。

{
    /.../

    "members": {

        // First session member as an example.
        "1": {
            "constants": { /* Property Bag */ },
            "properties": { /* Property Bag */ },

            /.../

            "reserved": true,
            /.../
        }
    }
}

これらのメンバーは、reservedRemovalTimeout の期限切れ後に MPSD によってセッションから削除されます。

大規模セッションの制限事項

Large 機能を有効にした MPSD セッションは、100 人を超えるプレイヤーをサポートします。これらのセッションは通常のセッションとは異なる動作をします。詳細は、マルチプレイヤーで大規模セッションを有効化するを参照してください。大規模セッションへの操作は常に単一ユーザーとして実行されます。そのため、大規模セッションへの S2S 呼び出しでは、X-Xbl-OnBehalfOf-Users ヘッダーに単一のユーザーのみを含める必要があります。複数ユーザー操作はサポートされていません。各ユーザーに対して個別に呼び出しを行って、ユーザーの追加または削除を行う必要があります。基となるセッションドキュメントでのロック競合を回避するために、これらの S2S 呼び出しは順次実行してください。同じドキュメントに対する並列操作は呼び出し時間を長くし、全体の操作時間を短縮しません。 S2S 呼び出しの結果は、大規模セッションの完全なメンバーリストへのアクセスを提供しません。呼び出しで指定されたユーザーのメンバーデータのみが返されます。そのため、タイトルサービスは大規模セッションのメンバーユーザー情報を独自のロジックで追跡し、MPSD のメンバー情報を使用して XBOX Requirements (XR) を正しくサポートする必要があります。

Encounters と Groups

Large 機能を持つセッションでは、最近のプレイヤーリストは自動的には更新されません。代わりに、他のプレイヤーは Encounters と Groups を通じて最近のプレイヤーリストに直接追加されます。詳細は、マルチプレイヤーで大規模セッションを有効化するを参照してください。セッションメンバーを encounter の一部としてフラグ付けするには、次のパターンを使用します。

{
    "members": {

        "me_{xuid}": {
            "properties": { 
                "system": { 
                    "encounters": [ "{uniqueEncounterID1}", 
                                    "{uniqueEncounterID2}",
                                    // ... //
                                  ] },
        }
    }
}

例

{
     // Marking two members as part of the same encounter.
    "members": {

        "me_1234567890123456": {
            "properties": {
                "system": {
                    "encounters": [ "757093D8-E41F-49D0-BB13-17A49B20C6B9" ] }},
        },

        "me_2345678901234567": {
            "properties": {
                "system": {
                    "encounters": [ "757093D8-E41F-49D0-BB13-17A49B20C6B9" ] }},
        },
    }
}

encounter を正しくキャプチャするには、encounters プロパティをすべての参加セッションメンバーに 30 秒以内に書き込む必要があります。encounter のセットは point-in-time プロパティです。ただちに消費され、応答には表示されません。

セッションメンバーをグループの一部としてフラグ付けするには、次のパターンを使用します。

{
    "members": {

        "me_{xuid}": {
            "properties": { 
                "system": { 
                    "groups": [ "{uniqueGroupID1}", 
                                "{uniqueGroupID2}",
                                // ... //
                              ] },
        }
    }
}

例

{
     // Marking two members as part of the same group.
    "members": {

        "me_1234567890123456": {
            "properties": { 
                "system": { 
                    "groups": [ "group-ADFB431" ] }},
        },

        "me_2345678901234567": {
            "properties": { 
                "system": { 
                    "groups": [ "group-ADFB431" ] }},
        },
    }
}

グループのリストは、書き込み操作のたびに置き換えられます。メンバーをグループから削除するには、groups プロパティリストからそのグループを削除します。空のリストで書き込み操作を行うと、すべてのグループメンバーシップが削除されます。

groups プロパティは永続的で、メンバーの応答に表示されます。

アクティビティセッション管理

ユーザーの MPSD アクティビティハンドルは、プラットフォームでの招待や参加中への参加 (join-in-progress) にどのセッションが使用されるかを決定します。このハンドルは S2S 呼び出しからは設定できず、クライアント API 経由でのみ利用できます。タイトルサーバーはクライアントとセッション名を共有することで、S2S セッションに対するアクティビティハンドルの作成を可能にできます。ハンドルに関する詳細は、次を参照してください。

マルチプレイヤーの概念の概要トピック内のセッションハンドルセクション
Multiplayer Session Directory の概要トピック内の MPSD ハンドルからセッションへセクション

プレイヤーのアクティビティを直接制御するには、Multiplayer Activity Service (MPA) を参照してください。MPA と MPSD を同時に使用することはできません。

ベストプラクティス

MPSD S2S 呼び出しを行う際は、問題を回避しパフォーマンスを向上させるために、次のベストプラクティスに従ってください。

複数ユーザーの操作をまとめる 可能な限り、MPSD への S2S 呼び出しは複数ユーザーに対するバッチ操作として実行してください。これによりパフォーマンスが向上し、ネットワークトラフィックが削減されます。呼び出しを削減する効率的なアプローチは、MPSD 操作をタイトルサーバーでキューに入れ、5 秒間隔ですべての要求をマージすることです。これにより、効率性とレイテンシのバランスが取れます。
複数のセッションおよびメンバー操作をマージする タイトルは、可能な限りユーザー操作をマージしてください。セッションメンバーの追加は、同時に関連するすべてのメンバープロパティの設定と組み合わせて行う必要があります。
同じドキュメントへの S2S 呼び出しは順次実行する 同じ MPSD ドキュメントへのすべての呼び出しは、常に順次実行してください。並列に操作を行うと、基となる MPSD ドキュメントのロック競合を引き起こし、パフォーマンスの低下や要求の失敗につながる可能性があります。
クライアントでハンドルアクティビティ操作に応答する MPSD アクティビティハンドルはクライアント API 経由でのみサポートされます。タイトルサービスは、セッション名を共有し関連するクライアント API を使用することで、クライアントにこれらのハンドルを作成させる必要があります。
クライアントセッションサブスクリプションと接続は不要 完全に S2S 呼び出し経由で管理されるすべての MPSD セッションでは、接続機能は不要です。S2S 呼び出しフローでは、クライアントとの WebSocket 接続は不要です。代わりに、タイトルサービスがセッションメンバーの追加または削除を直接完全に処理する必要があります。
大規模セッションの操作 大規模セッションの S2S ロジックは、複数メンバーによる操作が利用できないため、小規模セッションとは異なる方法で処理する必要があります。タイトルサービスは、メンバーの追加または削除を含む同じセッションドキュメントへのすべての操作を順次実行する必要があります。多数のメンバーの場合、メンバー操作に遅延が発生することがあります。このような遅延は許容範囲内であり、プラットフォームの要件に違反するものではありません。大規模セッションのメンバーロジックを簡素化するために、タイトルは MPSD セッションを使用してプレイヤーのメンバーシップのみを追跡し、他のすべてのプレイヤーデータを内部的に処理できます。タイトルサーバー用の大規模 MPSD セッションは、プレイヤーがいなくてもサーバー起動時に作成するのが最も簡単です。これには、次の例に示すように、MPSD セッション定数で sessionEmptyTimeout を構成する必要があります。
大規模セッションでの join-in-progress や招待 大規模セッションは、XBOX services を通じて join-in-progress と招待をサポートします。ほとんどのシナリオでは、この機能をサポートするために通常のセッションを使用する方が簡単です。このセッションはタイトルサーバーまたはクライアントによって制御でき、関連する大規模セッションに参加するための情報を含める必要があります。
大規模セッションでの encounters 大規模セッションでの encounters が正しくキャプチャされるようにするには、すべての encounters メンバープロパティを 30 秒以内に書き込む必要があります。タイトルサービスは、すべての参加メンバーの encounters プロパティに対する更新を、常に単一のサービス呼び出しにバッチ処理するようにしてください。encounter は一意の識別子を使用する必要があります。GUID の使用をお勧めします。

S2S セッションテンプレートの例

次のセッションテンプレートは、S2S 呼び出しを通じて制御されるセッションの出発点となります。

{
   "constants": {
        "system": {
            "version": 1,
            // Should be set to the maximum supported player number on the server.
            "maxMembersCount": 50,
            "visibility": "open",
            "inviteProtocol": "game",
            "capabilities": {
                "gameplay": true
            },
            // Optional: allows the session to linger for 60 minutes when it's empty.
            "sessionEmptyTimeout": 3600
        },
        "custom": {}
    }
}

S2S 大規模セッションテンプレートの例

次のセッションテンプレートは、S2S 呼び出しフローを持つ大規模セッションの出発点となります。

{
   "constants": {
        "system": {
            "version": 1,
            // Should be set to the maximum supported player number on the server.
            "maxMembersCount": 5000,
            "visibility": "open",
            "capabilities": {
                "large": true,
                "gameplay": true
            },
            // Optional: allows the session to linger for 60 minutes when it's empty.
            "sessionEmptyTimeout": 3600
        },
        "custom": {}
    }
}

XBOX Services

PlayFab

サービス間 (S2S) でのマルチプレイヤーセッション管理

MPSD S2S 認証

MPSD S2S ヘッダー

タイトルヘッダー

例

ユーザーヘッダー

例

Deny-Scope ヘッダー

例

セッションメンバー管理

セッションメンバーの追加

例

セッションメンバーの削除

例

メンバー予約

例

セッションメンバーの状態

メンバーのアクティブステータス

メンバーの予約ステータス

大規模セッションの制限事項

Encounters と Groups

例

例

アクティビティセッション管理

ベストプラクティス

S2S セッションテンプレートの例

S2S 大規模セッションテンプレートの例

関連項目

​MPSD S2S 認証

​MPSD S2S ヘッダー

​タイトル ヘッダー

​例

​ユーザー ヘッダー

​例

​Deny-Scope ヘッダー

​例

​セッション メンバー管理

​セッション メンバーの追加

​例

​セッション メンバーの削除

​例

​メンバー予約

​例

​セッション メンバーの状態

​メンバーのアクティブ ステータス

​メンバーの予約ステータス

​大規模セッションの制限事項

​Encounters と Groups

​例

​例

​アクティビティ セッション管理

​ベスト プラクティス

​S2S セッション テンプレートの例

​S2S 大規模セッション テンプレートの例

​関連項目

MPSD S2S 認証

MPSD S2S ヘッダー

タイトルヘッダー

例

ユーザーヘッダー

例

Deny-Scope ヘッダー

例

セッションメンバー管理

セッションメンバーの追加

例

セッションメンバーの削除

例

メンバー予約

例

セッションメンバーの状態

メンバーのアクティブステータス

メンバーの予約ステータス

大規模セッションの制限事項

Encounters と Groups

例

例

アクティビティセッション管理

ベストプラクティス

S2S セッションテンプレートの例

S2S 大規模セッションテンプレートの例

関連項目