> ## 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.

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

> S2S 呼び出しパターンと Multiplayer Session Directory (MPSD) を使用して、Business Partner 認証によりタイトル サーバーから XBOX Live セッションを管理します。

このトピックでは、Multiplayer Session Directory (MPSD) におけるサービス間 (S2S) の呼び出しパターンの使い方について説明します。

他のサービスと同様に、MPSD は S2S 呼び出しパターンをサポートしています。これらはクライアントの呼び出しパターンを拡張したもので、単一のサービス呼び出しでタイトル サービスから複数ユーザーを効率的に管理できるようにします。

クライアントではなくタイトル サービス経由でマルチプレイヤー セッションを管理することで、エラー処理ロジックを簡素化し、セッション書き込み操作における競合状態を回避できます。これは特に、メンバー数が多い大規模なセッション タイプに当てはまります。したがって、大規模多人数同時参加型オンライン ゲーム (MMO) や、1 セッションあたりのプレイヤー数が多いタイトルでは、MPSD セッションをタイトル サーバー経由で管理することがベスト プラクティスとなります。

RESTful な MPSD 呼び出しパターンに関する一般的な情報については、[XBOX services RESTful リファレンス](/reference/live/rest/atoc-xboxlivews-reference) を参照してください。

## MPSD S2S 認証

XBOX services の Multiplayer サービスに対する S2S 呼び出しの認証は、他の XBOX services とは異なります。`Delegation` トークンを使用した呼び出しはサポートされておらず、サービス認証を使用した呼び出しのみが機能します。この認証方式によって、MPSD S2S の追加機能を利用できます。

他の S2S 呼び出しと同様に、Business Partner Certificate が必要です。フル アクセスの `Multiplayer.Manage` ポリシーが必要です。これは、Business Partner Certificate が作成された Web サービスが S2S 呼び出しに対して正しいアクセス レベルを提供できるようにするために必要です。

サービス認証には次の認証フローが使用されます。

1. Business Partner Certificate を使用して XBOX Authorization Service for Services を呼び出し、`S` トークンを取得します。

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

3. `X` トークンとヘッダー (次のセクションで指定) を使用して MPSD サービスを呼び出します。

## MPSD S2S ヘッダー

### タイトル ヘッダー

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

```json theme={null}
X-Xbl-OnBehalfOf-Title:[titleid in decimal]
```

#### 例

```json theme={null}
Request.Headers["X-Xbl-OnBehalfOf-Title"] = "484921321";
```

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

### ユーザー ヘッダー

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

```json theme={null}
X-Xbl-OnBehalfOf-Users:[xuid][;privilege][,xuid[;privilege]]...
```

#### 例

```json theme={null}
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` ヘッダーを使用できます。

```json theme={null}
    X-Xbl-Deny-Scope: Multiplayer.Manage
```

#### 例

```json theme={null}
    Request.Headers["X-Xbl-Deny-Scope"] = "Multiplayer.Manage";
```

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

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

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

複数ユーザーを 1 回の呼び出しで扱うことで、S2S 呼び出しのセッション メンバー管理を最適化できます。

ユーザー ヘッダーを指定する場合、セッション ドキュメント本文内の標準的な "me" メンバーは使用できません。代わりに次のオプションが利用できます。

```json theme={null}
{
    "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 呼び出しで複数のユーザーに対する操作 (プレイヤーの追加や削除など) を実行してください。

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

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

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

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

```json theme={null}
{
    "members": {

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

#### 例

```json theme={null}
{
     // Adding two session members with one call.
    "members": {

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

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

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

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

```json theme={null}
{
    "members": {

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

#### 例

```json theme={null}
{
     // Removing two session members with one call.
    "members": {

        "me_1234567890123456": {
            null,
        },

        "me_2345678901234567": {
            null,
        } 
    }
}
```

### メンバー予約

一般に、すべてのセッション管理がタイトル サービスによって行われる場合は、セッション メンバーの予約は不要です。このシナリオでは、予約を必要とせずにセッション メンバーを直接追加または削除できます。セッション メンバーの予約は、作成されたセッションがクライアントによっても管理される場合にのみ使用してください。

`on-behalf-of-user` ヘッダーで指定したユーザーの順序で、複数ユーザーに対するセッション予約を追加できます。次のパターンは新しいセッションを作成する場合にのみ有効です。

```json theme={null}
{
    "members": {

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

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

        //...//

    }
}
```

#### 例

```json theme={null}
{
     // Adding reservations for two session members with one call.
    "members": {

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

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

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

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

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

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

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

```json theme={null}
{
    "members": {

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

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

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

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

以下はセッション ドキュメントの例です。

```json theme={null}
{
    /.../

    "members": {

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

            /.../

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

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

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

Large 機能を有効にした MPSD セッションは、100 人を超えるプレイヤーをサポートします。これらのセッションは通常のセッションとは異なる動作をします。詳細は、[マルチプレイヤーで大規模セッションを有効化する](/services/xbox-services/multiplayer/mpsd/concepts/live-large-sessions) を参照してください。

大規模セッションへの操作は常に単一ユーザーとして実行されます。そのため、大規模セッションへの S2S 呼び出しでは、`X-Xbl-OnBehalfOf-Users` ヘッダーに単一のユーザーのみを含める必要があります。複数ユーザー操作はサポートされていません。各ユーザーに対して個別に呼び出しを行って、ユーザーの追加または削除を行う必要があります。基となるセッション ドキュメントでのロック競合を回避するために、これらの S2S 呼び出しは順次実行してください。同じドキュメントに対する並列操作は呼び出し時間を長くし、全体の操作時間を短縮しません。

S2S 呼び出しの結果は、大規模セッションの完全なメンバー リストへのアクセスを提供しません。呼び出しで指定されたユーザーのメンバー データのみが返されます。

そのため、タイトル サービスは大規模セッションのメンバー ユーザー情報を独自のロジックで追跡し、MPSD のメンバー情報を使用して XBOX Requirements (XR) を正しくサポートする必要があります。

### Encounters と Groups

Large 機能を持つセッションでは、最近のプレイヤー リストは自動的には更新されません。代わりに、他のプレイヤーは Encounters と Groups を通じて最近のプレイヤー リストに直接追加されます。詳細は、[マルチプレイヤーで大規模セッションを有効化する](/services/xbox-services/multiplayer/mpsd/concepts/live-large-sessions) を参照してください。

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

```json theme={null}
{
    "members": {

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

#### 例

```json theme={null}
{
     // 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" ] }},
        },
    }
}
```

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

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

```json theme={null}
{
    "members": {

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

#### 例

```json theme={null}
{
     // 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` プロパティ リストからそのグループを削除します。空のリストで書き込み操作を行うと、すべてのグループ メンバーシップが削除されます。

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

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

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

ハンドルに関する詳細は、次を参照してください。

* マルチプレイヤーの概念の概要トピック内の [セッション ハンドル](/services/xbox-services/multiplayer/concepts/live-multiplayer-concepts#session-handles) セクション
* Multiplayer Session Directory の概要トピック内の [MPSD ハンドルからセッションへ](/services/xbox-services/multiplayer/mpsd/live-mpsd-overview#mpsd-handles-to-sessions) セクション

プレイヤーのアクティビティを直接制御するには、[Multiplayer Activity Service (MPA)](/services/xbox-services/multiplayer/mpa/live-mpa-overview) を参照してください。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 呼び出しを通じて制御されるセッションの出発点となります。

```json theme={null}
{
   "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 呼び出しフローを持つ大規模セッションの出発点となります。

```json theme={null}
{
   "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 RESTful リファレンス](/reference/live/rest/atoc-xboxlivews-reference)

[タイトル サービスから XBOX services への呼び出し](/services/xbox-services/fundamentals/s2s-auth-calls/s2s-calls/live-title-service-calls-xbox-live)


## Related topics

- [サービス間 (S2S) 呼び出しパターン](/ja-jp/services/xbox-services/fundamentals/s2s-auth-calls/s2s-calls/s2s-call-patterns/live-s2s-call-patterns-nav.md)
- [XBOX services マルチプレイヤーの概要](/ja-jp/services/xbox-services/multiplayer/overviews/live-multiplayer-intro.md)
- [マルチプレイヤー セッションの詳細トピック](/ja-jp/services/xbox-services/multiplayer/mpsd/concepts/live-mpsd-details.md)
- [XR-067 マルチプレイヤー セッション状態の維持](/ja-jp/publishing/certification/xr/xr-067.md)
- [マルチプレイヤーセッションテンプレート](/ja-jp/services/xbox-services/multiplayer/mpsd/concepts/live-session-templates.md)