> ## 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
> Guide approfondi de MPSD couvrant les attributs des modèles de session, le schéma du contrat v107, les modèles QoS, l'initialisation des membres et la résolution des problèmes multijoueurs.
Cet article fournit une vue d'ensemble de la création de sessions multijoueurs à l'aide du service Multiplayer Session Directory (MPSD) des services XBOX, sur les plateformes postérieures à la XBOX 360.
Cet article s'adresse principalement aux développeurs de titres XBOX qui soumettent leurs modèles de session directement à Partner Center.
Cet article couvre la configuration de MPSD, son utilisation et la résolution des problèmes liés aux sessions multijoueurs.
**Contenu :**
* [Résumé des révisions](#rs)
* [Introduction](#intro)
* [Terminologie utilisée dans ce document](#tuitd)
* [Multiplayer Session Directory](#tmsd)
* [Sessions MPSD](#mpsds)
* [Attributs des modèles de session](#sta)
* [Mise à jour du schéma de contrat](#csu)
* [Initialisation des membres dans les documents de session](#miisd)
* [Session de ticket de match](#mts)
* [Modèles de qualité de service (QoS)](#qost)
* [Détails de la phase QoS et de l'initialisation de session](#qospasid)
* [Session XBOX Cloud Compute](#xccs)
* [Session brute et propriétés de titre personnalisées](#rsactp)
* Dégradation des membres actifs
* [FAQ et résolution des problèmes](#fat)
## Résumé des révisions
Les bibliothèques XBOX Services API (XSAPI) côté client utilisent actuellement la version de contrat 104 pour communiquer avec les services MPSD.
Cette version du document met à jour le schéma des modèles de session vers la version de contrat 107, qui est la dernière version de contrat prise en charge par les services MPSD.
Les modifications entre les versions 104 et 107 sont résumées dans la section [Mise à jour du schéma de contrat](#_Contract_schema_update) ci-dessous.
Notez que les modèles écrits pour la version de contrat 104 devront être mis à jour s'ils sont republiés en version 107.
Cependant, les services sont rétrocompatibles ; vous pouvez donc continuer à utiliser les bibliothèques actuelles, qui seront mises à jour dans une prochaine version.
La révision précédente de ce document a mis à jour les informations relatives aux sessions serveur et ajouté une nouvelle section sur les XSAPI et les appels de service RESTful.
En outre, le tableau de la section Requête d'informations sur l'état de session a été mis à jour et la section Modèles de qualité de service (QoS) a été révisée.
## Introduction
Une session multijoueur est un document sécurisé qui réside dans le cloud sur Multiplayer Session Directory (MPSD) ; ce document représente un groupe de personnes qui jouent à un jeu.
Plus précisément, les sessions multijoueurs présentent les caractéristiques suivantes :
* Chaque session possède un URI unique.
* Le document de session contient les membres actuels, les paramètres de jeu, les données d'amorçage et les informations sur le serveur de jeu.
* Les titres créent et gèrent leurs propres sessions.
* Une session permet la connectivité entre ses membres.
Multiplayer Session Directory (MPSD) centralise les métadonnées des sessions de jeu pour tous les clients.
MPSD fournit les informations de base nécessaires sur une session pour aider à configurer les associations d'appareils sécurisées entre les clients.
MPSD fournit également des métadonnées de premier démarrage de base permettant à un client de se connecter au jeu avant que celui-ci ne commence à échanger des données de jeu plus spécifiques.
Compte tenu de la gestion de la durée de vie des processus (PLM) et du basculement entre tâches propre aux applications sur XBOX One et versions ultérieures, MPSD garantit que les clients disposent des informations correctes pour contacter les pairs et les serveurs identifiés comme faisant partie de la session de jeu active, et se coordonne avec le shell et le système d'exploitation de la console pour réserver, activer et gérer la durée de vie des joueurs pour une session de jeu.
## Terminologie utilisée dans ce document
| Terme | Définition |
| - | - |
| Session multijoueur | Document sécurisé qui réside dans le cloud des services XBOX et représente un groupe d'utilisateurs qui sont (ou seront) connectés ensemble pendant qu'ils jouent à un titre sur XBOX One ou version ultérieure (y compris PC). Tous les aspects du multijoueur, comme le matchmaking, les groupes, la jonction en cours de partie, etc., s'appuient sur la session multijoueur. |
| Session de jeu | Il s'agit de la session de jeu proprement dite, exposée dans MPSD, dans laquelle les utilisateurs jouent ensemble. Tous les scénarios multijoueurs aboutissent finalement à une session de jeu. |
| Session de ticket de match | Il s'agit d'une session utilisée pour suivre la soumission des tickets de match pendant le matchmaking. |
| Joueur inactif | Joueur dont l'état a été défini sur Inactive dans la session. Le titre définit un utilisateur sur l'état Inactive lorsque le jeu est contraint, suspendu ou inactif de toute autre manière définie par le titre. |
## Multiplayer Session Directory
MPSD facilite et aide les titres à coordonner les informations de session entre les joueurs en ligne.
Différents types de sessions peuvent être créés pour accomplir différentes tâches du jeu multijoueur.
Le tableau suivant présente les différences entre la façon dont ces tâches étaient réalisées sur XBOX 360 et la façon dont elles le sont sur XBOX One ou version ultérieure (y compris PC).
| Fonction ou tâche | XBOX 360 | XBOX One ou version ultérieure |
| - | - | - |
| **Obtenir des informations sur la session de jeu** | **XSessionGetDetails**, **XSessionSearchByID**, ou suivi par vos propres moyens. | Demander les informations de session au service. |
| **Migrer l'hôte** | Si nécessaire, le titre appelle **XSessionMigrateHost.** | Inutile de créer une nouvelle session ; il suffit d'attribuer un nouvel hôte pour le SessionID. |
| **Gérer plusieurs sessions de joueurs** | Délicat de gérer plusieurs sessions à la fois. Par exemple, **XNetReplaceKey** par rapport à **XNetUnregisterKey**. | Une session basée sur un service simplifie la gestion d'une session et facilite la gestion de plusieurs sessions. |
| **Gérer les déconnexions de compte et de réseau** | Les déconnexions réseau et les déconnexions de compte doivent être gérées différemment, avec respectivement **XCloseHandle** ou **XSessionDelete**. | Un service centralisé simplifie la gestion des déconnexions, et les délais d'expiration sont définis dans la configuration du jeu. |
### Modèles de session
* Sessions de jeu
* Session contenant les XUID des joueurs, les données d'adresse d'appareil sécurisée et les états des propriétés. Elle est considérée comme la session de jeu proprement dite.
* Peut être pair-à-pair, pair-à-hôte, pair-à-serveur ou hybride.
* Sessions de ticket de match
* Session soumise au matchmaking pour trouver d'autres joueurs avec qui jouer. Notez qu'une session de jeu peut également être une session de ticket si le jeu cherche davantage de joueurs.
* Sessions serveur
* Sessions de jeu créées et utilisées via le traitement XBOX Compute.
La figure 1 illustre des utilisations des sessions MPSD : les cadres bleus représentent les sessions MPSD et les cadres rouges les services qui les utilisent.
**Figure 1. Utilisation des sessions MPSD :** (figure manquante)
## Sessions MPSD
Les sessions tiennent à jour deux listes d'entités associées :
1. Les membres (utilisateurs) qui ont rejoint une session ou y ont été invités.
2. Les serveurs (serveurs cloud ou serveurs dédiés) qui ont rejoint la session.
Chaque entité possède :
1. Des valeurs constantes définies lors de la création.
2. Des propriétés modifiables.
3. Des métadonnées en lecture seule.
### XSAPI et appels de service RESTful
Il existe deux façons d'interagir avec les services Sessions et Matchmaking des services XBOX.
* Appels HTTPS standard
* Wrappers XSAPI
#### Utilisation d'appels HTTPS standard vers les services RESTful
Pour XBOX One et versions ultérieures, la première façon d'interagir avec les services Sessions et Matchmaking des services XBOX consiste à utiliser des appels HTTPS standard vers les URI RESTful des services XBOX.
Cela offre aux titres de la flexibilité pour appeler ces services et interagir avec eux en fonction de leurs configurations de serveur et de jeu.
Pour obtenir la liste de ces URI, consultez [Référence RESTful des services XBOX](/fr/reference/live/rest/atoc-xboxlivews-reference).
#### Utilisation des wrappers XSAPI pour les services RESTful
La seconde façon d'interagir avec les services Sessions et Matchmaking consiste à utiliser les XSAPI, qui servent de wrappers pour les URI des services RESTful.
Ils permettent une approche plus traditionnelle de l'utilisation des API dans le code, sans avoir à gérer le trafic HTTPS pour chaque appel.
Pour plus d'informations sur les XSAPI, consultez la [page GitHub xbox-live-api](https://github.com/microsoft/xbox-live-api).
Cette documentation de référence comprend :
* JSON Parsing API Reference : documentation de référence des API d'analyse JSON.
* Espace de noms Windows.Web : membres de l'espace de noms Windows.Web.
* XBOX Compute SDK Reference : API de création d'instances de serveur de jeu pour XBOX Compute.
### Sessions et modèles MPSD
Les sessions MPSD sont créées à partir de modèles ingérés via Partner Center.
Les modèles sont des documents JSON qui définissent le cadre de la session en cours de création.
Le modèle fournit les constantes de la nouvelle session.
L'extrait suivant est un exemple de configuration de modèle.
```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": {}
}
}
```
La session de ticket de match doit être utilisée avec un modèle de session de jeu configuré avec des valeurs de délai d'expiration QoS dans son objet **memberInitialization**.
**Figure 2. Exemple de hopper :**
L'extrait de code suivant est un exemple de modèle de session de jeu pair-à-pair (QoS géré par le titre).
```json theme={null}
{
"constants": {
"system": {
"version": 1,
"maxMembersCount": 10,
"visibility": "private",
"capabilities": {
"connectivity": true
},
"memberInitialization": {
"joinTimeout": 20000,
"externalEvaluation": false,
"membersNeededToStart": 2
}
},
"custom": {}
}
}
```
Voici un exemple de session pair-à-serveur et de modèle RAW.
```json theme={null}
{
"constants": {
"system": {
"version": 1,
"maxMembersCount": 10,
"visibility": "private",
"capabilities": {}
},
"custom": {}
}
}
```
Le code suivant montre un exemple de modèle de session de ticket de match, utilisé pour Smart Match.
```json theme={null}
{
"constants": {
"system": {
"version": 1,
"maxMembersCount": 10,
"visibility": "private",
"capabilities": {},
"memberInitialization": {
"joinTimeout": 20000,
"externalEvaluation": false,
"membersNeededToStart": 1
}
},
"custom": {}
}
}
```
### Vérification des modèles configurés pour votre SCID
#### Modèles de session
La liste des modèles de session qui existent dans un SCID, ainsi que les détails d'un modèle de session spécifique, peuvent être récupérés auprès de MPSD :
```uri theme={null}
GET /serviceconfigs/{scid}/sessiontemplates
GET /serviceconfigs/{scid}/sessiontemplates/{session-template-name}
```
#### Requête d'informations sur l'état de session
Les sessions peuvent être interrogées au niveau de la configuration de service et du modèle de session :
```uri theme={null}
GET /serviceconfigs/{scid}/sessions
GET /serviceconfigs/{scid}/sessiontemplates/{session-template-name}/sessions
```
Par défaut, cette requête renvoie jusqu'à 100 sessions non privées.
La requête peut être modifiée à l'aide des paramètres de chaîne de requête suivants :
| Chaîne de requête | Effet | Description |
| - | - | - |
| keyword=foo | Inclure uniquement les sessions qui ont le mot clé « foo ». | |
| XUID=123 | Inclure uniquement les sessions dans lesquelles se trouve l'utilisateur « 123 ». | Par défaut, l'utilisateur doit être actif dans la session pour qu'elle soit incluse. |
| *reservations*=**true** | Inclure les sessions pour lesquelles l'utilisateur est défini comme joueur réservé, mais qu'il n'a pas rejointes pour devenir un joueur actif. | Uniquement lors de l'interrogation de vos propres sessions, ou lors de l'interrogation de serveur à serveur des sessions d'un utilisateur spécifique. |
| *inactive*=**true** | Inclure les sessions que l'utilisateur a acceptées, mais dans lesquelles il ne joue pas activement. | Les sessions dans lesquelles l'utilisateur est « ready » mais pas « active » comptent comme inactives. |
| *private*=**true** | Inclure les sessions privées. | Uniquement lors de l'interrogation de vos propres sessions, ou lors d'une interrogation de serveur à serveur. |
| *visibility*=open | Inclure uniquement les sessions « open ». | Si la valeur est « private », la directive « private=true » doit également être définie. |
| *take*=5 | Renvoyer jusqu'à cinq sessions. | Doit être comprise entre 0 et 100. |
Le résultat est un tableau JSON de références de session.
Certaines données de session sont incluses directement.
**Remarque** Chaque requête doit inclure un filtre de mot clé, un filtre XUID, ou les deux.
Définir *private* (qui renvoie les sessions privées) ou *reservations* (qui renvoie les sessions que l'utilisateur n'a pas rejointes) sur **true** exige que l'appelant dispose d'un accès de niveau serveur à la session, ou que la revendication XUID de l'appelant corresponde au filtre XUID de l'URI.
Sinon, l'erreur 403 Forbidden est renvoyée (que de telles sessions existent ou non).
L'extrait de code suivant montre un exemple de réponse à une requête.
```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" ]
} ]
}
```
## Attributs des modèles de session
## Mise à jour du schéma de contrat
Comme indiqué au début de ce document, la dernière version de contrat des modèles de session est la 107, qui introduit quelques modifications du schéma par rapport à la version précédente 104.
Les modèles écrits pour la version de contrat 104 devront être mis à jour s'ils sont republiés en version 107.
Voici un résumé des modifications.
* **/constants/system/managedInitialization** est renommé **/constants/system/memberInitialization**.
* Le champ **autoEvaluate** est renommé **externalEvaluation** et sa polarité est inversée, sauf que **false** reste la valeur par défaut.
* La valeur par défaut de **membersNeededToStart** passe de 2 à 1.
* La valeur par défaut de **joinTimeout** passe de 5 secondes à 10 secondes.
* La valeur par défaut de **measurementTimeout** passe de 5 secondes à 30 secondes.
* **/constants/system/timeouts** est supprimé, et les délais d'expiration sont renommés et déplacés sous **/constants/system**.
* Le délai d'expiration **reserved** devient **reservedRemovalTimeout**.
* Le délai d'expiration **inactive** devient **inactiveRemovalTimeout** et sa nouvelle valeur par défaut est 0 au lieu de 2 heures.
* Le délai d'expiration **ready** devient **readyRemovalTimeout**.
* Le délai d'expiration **sessionEmpty** devient **sessionEmptyTimeout**.
* **/constants/system/capabilities/gameplay** doit être défini sur **true** pour les sessions qui représentent un jeu réel (par opposition aux sessions auxiliaires, comme les sessions de match et de lobby) afin d'activer les joueurs récents et le signalement de réputation.
### Objets système
Chacun des objets système du document de session possède un schéma fixe appliqué et interprété par MPSD.
Dans le corps des requêtes PUT, les objets système sont validés et fusionnés comme les objets personnalisés.
Mais contrairement aux objets personnalisés, une fois fusionnés, les objets système sont davantage validés et traités en fonction de ces schémas.
**/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
}
```
### Délais d'expiration
Les sessions peuvent être modifiées par des minuteurs et d'autres événements externes.
L'objet **Timeouts** de MPSD fournit un mécanisme de base pour gérer la durée de vie des sessions et les membres.
Le champ **nextTimer** de la session indique l'heure du prochain minuteur.
Les clients peuvent utiliser cette information pour choisir un intervalle approprié pour la prochaine interrogation.
Cette valeur est également renvoyée dans l'en-tête HTTP **Expires**.
Les délais d'expiration sont exprimés en millisecondes.
La valeur zéro est autorisée et signifie que le délai d'expiration doit être immédiat.
Si un délai d'expiration donné n'est pas spécifié, il est considéré comme infini.
Comme les délais d'expiration ont des valeurs par défaut, le modèle de session doit spécifier explicitement « null » pour un délai d'expiration infini.
#### SessionEmptyTimeout
La valeur **/constants/system/sessionEmptyTimeout** configure le nombre de millisecondes après lequel une session devenue vide est supprimée.
La valeur par défaut est zéro, ce qui signifie que la session est supprimée immédiatement.
Si la valeur n'est pas spécifiée, les sessions vides sont conservées indéfiniment.
#### Délais d'expiration des membres
Les trois autres délais d'expiration de **/constants/system** contrôlent la durée pendant laquelle un membre peut rester dans un état particulier :
* **reservedRemovalTimeout**
* La réservation est supprimée à l'expiration du délai. La valeur par défaut est de 30 secondes.
* **inactiveRemovalTimeout**
* Un membre inactif est retiré de la session après deux heures par défaut.
* **readyRemovalTimeout**
* Les membres à l'état « ready » repassent à l'état inactif après trois minutes par défaut.
## Initialisation des membres dans les documents de session
### Initialisation des membres
L'objet **memberInitialization** contrôle les étapes d'initialisation qui suivent la création de la session et/ou l'arrivée de nouveaux membres dans la session.
Les délais d'expiration et les étapes d'initialisation sont suivis automatiquement par la session, y compris les mesures QoS si des métriques sont définies.
Ces délais d'expiration remplacent les délais d'expiration de réservation et d'état ready de la session pour les membres dont la propriété **initializationEpisode** est définie.
Exemple :
```json theme={null}
"memberInitialization": {
"joinTimeout": 5000,
"measurementTimeout": 5000,
"evaluationTimeout": 5000, // only specify for external evaluation
"externalEvaluation": true,
"membersNeededToStart": 2
},
```
**Figure 3. Flux d'initialisation des membres :**
Chacune des trois étapes de l'initialisation des membres peut expirer :
1. **joiningTimeout**
* Durée, en millisecondes, dont disposent les utilisateurs pour rejoindre la session. Les réservations des membres qui ne parviennent pas à rejoindre la session sont supprimées.
2. **measuringTimeout**
* Durée dont disposent les membres pour charger leurs mesures. Les membres qui ne parviennent pas à charger leurs mesures sont marqués avec un *failureReason* « timeout ».
3. **evaluationTimeout**
* Durée dont dispose un membre pour prendre et charger la décision d'évaluation. Si aucune décision n'est reçue, cela compte comme un échec.
**externalEvaluation**
* MPSD peut effectuer une évaluation QoS automatique selon les exigences fournies dans le modèle de session. L'évaluation est effectuée lorsque externalEvaluation est défini sur false. **externalEvaluation** doit être défini sur **true** lorsqu'un **evaluationTimeout** est défini. Si vous avez deux exigences pair-à-pair ou pair-à-hôte, vous devez tout de même définir **externalEvaluation** sur **false** pour que la session termine automatiquement l'initialisation.
**membersNeededToStart**
* Il s'agit du nombre minimal de réservations de membres qui doivent exister avec "initialize":"true" et réussir le QoS pour que l'évaluation automatique réussisse.
### Épisodes d'initialisation
Lorsque l'objet **memberInitialization** est défini, MPSD fait progresser les phases d'initialisation par épisode.
Le premier épisode démarre lors de la création de la session et inclut toutes les phases définies dans le modèle.
Tout nouveau membre invité ou ayant rejoint la session pendant qu'un épisode est déjà en cours est marqué pour l'épisode suivant.
L'état d'un épisode ou de **memberInitialization** en général peut être récupéré à partir de l'objet **initializing** de la session.
**Remarque** Sachez que cet objet est supprimé une fois l'initialisation terminée.
Exemple :
```json theme={null}
"initializing": {
"stage": "measuring",
"stageStartTime": "2009-06-15T13:45:30.0900000Z",
"episode": 1
},
```
L'étape passe de joining à measuring, puis à evaluating.
Si un épisode échoue, l'étape est définie sur *failed* et la session ne peut pas être initialisée.
Sinon, lorsqu'un épisode d'initialisation se termine, l'objet **initializing** est supprimé.
Les échecs d'initialisation peuvent également être suivis pour chaque membre.
Ils sont définis lors de la sortie de l'étape joining ou measuring si ce membre ne réussit pas.
Exemple :
```json theme={null}
"initializationFailure": "latency",
```
Par ordre de priorité, la valeur de cet attribut peut être *timeout, latency, bandwidthdown, bandwidthup, network, group* ou *episode*.
La valeur network signifie que la configuration et/ou les conditions réseau (comme une traduction d'adresses réseau \[NAT] conflictuelle) ont empêché la mesure des métriques QoS.
La seule valeur possible à la fin de l'étape joining est *group*.
(En cas d'expiration du délai de l'étape joining, la réservation est supprimée.)
Si **memberInitialization** est défini et que le membre a été ajouté avec "initialize": true, cette valeur est définie sur l'épisode d'initialisation auquel le membre participera. La valeur 1 est utilisée pour les membres ajoutés à une nouvelle session au moment de sa création, et elle est supprimée à la fin de l'épisode d'initialisation.
```json theme={null}
"initializationEpisode": 1,
```
## Session de ticket de match
Lorsqu'une session MPSD est utilisée comme session de ticket de match, certaines propriétés et constantes de session spéciales sont utilisées.
**/members/{index}/constants/system**
```json theme={null}
{
{
"xuid": "12345678",
"initialize": "false", // Run initialization for this user (if "memberInitialization" is set). Defaults to false.
```
Lorsque le service de matchmaking ajoute des utilisateurs à une session, il fournit un contexte sur la manière dont ils ont été associés dans la session et sur les raisons de cette association, dans le champ **matchmakingResult**.
```json theme={null}
"matchmakingResult": {
```
Il s'agit d'une copie des **serverMeasurements** d'un utilisateur provenant de la session de matchmaking.
```json theme={null}
"serverMeasurements": {
"east.thunderhead.azure.com": {
"latency": 233 // Milliseconds
}
}
}
}
```
## Modèles de qualité de service (QoS)
Pour les modèles de session de jeu, il est possible d'ajouter des valeurs qui indiquent à MPSD de se coordonner avec la couche réseau et les fonctionnalités sociales de la console.
Cette coordination a pour objectif de valider la qualité de l'état de connexion avant la création d'une session et avant qu'un utilisateur soit informé que la partie est prête à être rejointe.
L'extrait de code suivant est un exemple de modèle de session de jeu pair-à-hôte avec 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": {}
}
}
```
Cet extrait de code est un exemple de modèle de session de jeu pair-à-pair avec 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": {}
}
}
```
### Attributs des modèles de session QoS
Si un objet **memberInitialization** est défini, la session s'attend à ce que le système client ou le titre effectue l'initialisation après la création de la session et/ou lorsque de nouveaux membres rejoignent la session.
Les délais d'expiration et les étapes d'initialisation sont suivis automatiquement par la session, y compris les mesures QoS si des métriques sont définies.
Ces délais d'expiration remplacent les délais d'expiration de réservation et d'état ready de la session pour les membres dont la propriété **initializationEpisode** est définie.
```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.
},
```
Une session de jeu avec QoS nécessite la fonctionnalité de connectivité.
Si aucune métrique n'est spécifiée, les métriques prennent par défaut les valeurs nécessaires pour satisfaire les exigences QoS.
Si elles sont spécifiées, elles doivent être suffisantes pour satisfaire les exigences QoS.
```json theme={null}
"metrics": {
"latency": true,
"bandwidthDown": true,
"bandwidthUp": true,
"custom": true
```
Les seuils suivants s'appliquent à chaque connexion par paire entre tous les membres d'une session :
```json theme={null}
"peerToPeerRequirements": {
"latencyMaximum": 250, // Milliseconds
"bandwidthMinimum": 10000 // Kilobits per second
},
```
Les seuils suivants s'appliquent à chaque connexion depuis un candidat hôte :
```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".
},
```
Les chaînes de connexion au serveur potentielles suivantes doivent être évaluées (notez que les chaînes de connexion doivent être en minuscules) :
```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**
Ces indicateurs contrôlent l'état du membre et **activeTitle**, et ils s'excluent mutuellement (définir les deux sur **true** est une erreur).
Pour chacun d'eux, **false** équivaut à « absent ». L'état par défaut est « inactive », c'est-à-dire qu'aucun des deux n'est présent.
```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
}
}
```
## Détails de la phase QoS et de l'initialisation de session
MPSD suit et signale les résultats QoS pour la création de partie une fois que le modèle a terminé l'initialisation des membres.
La progression de cette opération est représentée par un objet *initializing* dans le document de session, comme décrit dans la section [Initialisation des membres](#_Member_initialization_in) ci-dessus.
L'objet *initializing* possède un attribut *stage*, qui représente l'étape d'initialisation en cours.
L'étape passe de *joining* à *measuring*, puis à *evaluating*.
* Si l'épisode d'initialisation #1 échoue, l'étape est définie sur *failed* et la session ne peut pas être initialisée. Sinon, lorsqu'un épisode d'initialisation se termine, l'objet « initializing » est supprimé. Si **externalEvaluation** est défini sur **false**, l'étape evaluating est ignorée. Si ni **metrics** ni **measurementServerAddresses** ne sont définis, l'étape measuring est ignorée.
```json theme={null}
"initializing": {
"stage": "measuring",
"stageStartTime": "2009-06-15T13:45:30.0900000Z",
"episode": 1
},
```
* Les candidats hôtes sont des jetons d'appareil répertoriés par ordre de préférence. Ils sont définis après l'étape *measuring* de l'épisode d'initialisation #1 si **peerToHostRequirements** est défini et que **/properties/system/host** ne l'est pas. Ils sont effacés une fois qu'un objet **/properties/system/host** est défini.
```json theme={null}
"hostCandidates": [ "ab90a362", "99582e67" ],
"constants": { /* Property Bag */ },
"properties": { /* Property Bag */ },
"members": {
"1": {
"constants": { /* Property Bag */ },
"properties": { /* Property Bag */ },
```
* L'attribut *gamertag* n'est défini que si le membre a accepté et si une revendication de gamertag a été trouvée pour ce membre.
```json theme={null}
"gamertag": "stacy",
```
* L'attribut *deviceToken* est défini lorsque le membre charge une adresse d'appareil sécurisée. Il s'agit d'une chaîne non sensible à la casse qui peut être utilisée pour les comparaisons d'égalité.
```json theme={null}
"deviceToken": "9f4032ba7",
```
* La valeur *reserved* est supprimée après que l'utilisateur a exécuté sa première requête PUT sur le document de session. Lorsque des joueurs sont réservés, cela signifie qu'ils ont été invités à la session de jeu, mais qu'ils n'ont pas encore accepté et que leurs connexions n'ont pas été évaluées.
```json theme={null}
"reserved": true,
```
* Si le membre est actif, *activeTitleId* est le titre dans lequel le membre est actif, en décimal.
```json theme={null}
"activeTitleId": "8397267",
```
* Cet attribut fait référence à l'heure à laquelle l'utilisateur a rejoint la session. Si *reserved* vaut **true**, *joinTime* correspond à l'heure à laquelle la réservation a été effectuée.
```json theme={null}
"joinTime": "2009-06-15T13:45:30.0900000Z",
```
* Présent si ce membre se trouve dans le tableau properties/system/turn ; absent sinon.
```json theme={null}
"turn": true,
```
* L'attribut *initializationFailure* est défini sur l'objet membre lors de la sortie de l'étape joining ou measuring si le membre n'a pas réussi l'étape. Par ordre de priorité, il peut être défini sur *timeout*, *latency*, *bandwidthdown*, *bandwidthup*, *network*, *group* ou *episode*.
La valeur *network* signifie que la configuration et/ou les conditions réseau (comme des traductions d'adresses réseau \[NAT] conflictuelles) ont empêché la mesure des métriques QoS. La seule valeur possible à la fin de l'étape joining est *group*. (En cas d'expiration du délai de l'étape joining, la réservation est supprimée.) La valeur *episode* est définie après l'échec d'une étape « evaluation » sur tous les membres de l'épisode d'initialisation qui n'ont pas échoué pendant les étapes joining ou measuring.
```json theme={null}
"initializationFailure": "latency",
```
* Si **memberInitialization** est défini et que le membre a été ajouté avec "initialize": true, cette valeur est définie sur l'épisode d'initialisation auquel le membre participera. La valeur 1 est utilisée pour les membres ajoutés à une nouvelle session au moment de sa création. Elle est supprimée à la fin de l'épisode d'initialisation.
```json theme={null}
"initializationEpisode": 1,
```
* L'attribut *next* représente la valeur d'index du membre suivant dans la session. Il a la même valeur que l'attribut *next* de l'objet **membersInfo** ci-dessous s'il n'y a plus de membres à ajouter.
```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 */ }
}
}
}
```
## Session XBOX Cloud Compute (dépréciée)
Une session XBOX Cloud Compute contient la liste ordonnée des chaînes de connexion non sensibles à la casse que la session peut utiliser pour se connecter à un serveur de jeu.
En général, les titres doivent utiliser la première chaîne de la liste, mais les titres plus élaborés peuvent utiliser un mécanisme personnalisé pour choisir l'une des autres (par exemple, en fonction de la charge).
```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"
}
}
```
## Session brute et propriétés de titre personnalisées
Une session peut servir à stocker des informations de gestion personnalisées (métadonnées) relatives à une partie multijoueur.
Les données de jeu ou les informations enregistrées doivent être stockées dans TMS++.
### Conteneurs de propriétés
Chacun des objets ci-dessus marqués comme conteneur de propriétés (Property Bag) se compose de deux objets internes facultatifs, system et custom.
Les objets custom peuvent contenir n'importe quel JSON.
```json theme={null}
"custom": {
"myField1": true,
"myField2": "string",
"myField3": 5.5,
"myField4": { "myObject": null },
"myField5": [ "my", "array" ]
}
```
## Dégradation des membres actifs
Les membres actifs sont automatiquement marqués comme inactifs lorsque MPSD détecte que l'utilisateur n'est plus engagé dans le titre.
Cela peut se produire, par exemple, si Presence fait expirer l'enregistrement de l'utilisateur.
Ce mécanisme n'est qu'un filet de sécurité : les titres doivent toujours marquer de manière proactive les membres comme inactifs (ou les retirer de la session) lorsqu'ils quittent le titre ou basculent vers une autre application, se déconnectent ou cessent d'être engagés de toute autre manière.
## FAQ et résolution des problèmes
### Comment appeler MPSD ?
Avec l'authentification par certificat : client-sessiondirectory.xboxlive.com
Exemple :
```uri theme={null}
PUT https://client-sessiondirectory-stress.xboxlive.com/serviceconfigs/8cvda84-2606-4bab-8eda-d12313e65143/sessiontemplates/teamDeathmatch/sessions/3baafc35-816d-49cd-9656-5772506c988a
```
Avec l'authentification XToken : sessiondirectory.xboxlive.com
Exemple :
```uri theme={null}
PUT https://sessiondirectory-stress.xboxlive.com/serviceconfigs/8cvda84-2606-4bab-8eda-d12313e65143/sessiontemplates/teamDeathmatch/sessions/3baafc35-816d-49cd-9656-5772506c988a
```
### Comment savoir quels SCID, modèle de session et sandbox utiliser ?
Ces informations se trouvent dans Partner Center pour votre titre.
Si vous n'avez pas encore accès à Partner Center, contactez votre gestionnaire de compte développeur, qui pourra vous aider à obtenir ces informations.
### Existe-t-il un exemple de corps de requête auquel je peux comparer le mien ?
### J'obtiens une erreur 404 lors de l'appel de MPSD.
Collectez des traces Fiddler pour obtenir plus d'informations, puis procédez comme suit :
1. Recherchez dans le message renvoyé dans le corps de HttpResponse les messages 404 courants :
* *The requested service config is either invalid or not configured for sessions*. Vérifiez que le SCID utilisé est correct.
* *The requested session wasn't found*. Vérifiez que la session a été créée et que le modèle de session est correct avant de la récupérer. Vous pouvez créer une session avec un appel PUT.
2. Vérifiez l'URI que vous utilisez.
3. Redémarrez la console et/ou réessayez avec un nouvel utilisateur.
### J'obtiens une erreur 403 lors de l'appel de MPSD.
Il s'agit généralement d'un problème d'autorisations ou d'étendue.
Collectez des traces Fiddler pour obtenir plus d'informations, puis procédez comme suit :
1. Recherchez dans les messages renvoyés dans le corps de HttpResponse les messages 403 courants :
* \*The requested service config cannot be accessed. \*
* Vérifiez que vous utilisez un compte qui a accès à la sandbox.
* Vérifiez que vous vous trouvez dans la bonne sandbox.
* Si vous utilisez l'authentification par certificat et obtenez cette erreur, contactez votre DAM.
* *The requested session cannot be accessed. Private Sessions can only be read by members of the session.*
* Vous essayez d'accéder à une session dont la visibilité est « private ». Seuls les membres de la session peuvent lire le document de session.
* *The request body can't contain existing member references unless the authentication principal includes a server.*
* Vous ne pouvez pas faire rejoindre une session à un autre utilisateur au nom d'un utilisateur. Vous pouvez seulement l'inviter. Définissez l'index sur « `reserve_` » pour inviter un joueur.
### J'obtiens une erreur 412 Precondition Failed.
La requête suivante renvoie 412 Precondition Failed si la session existe déjà :
```http theme={null}
> PUT /serviceconfigs/00000000-0000-0000-0000-000000000000/sessiontemplates/quick/sessions/foo HTTP/1.1
> Content-Type: application/json
> If-None-Match: \*
```
La requête suivante renvoie 412 Precondition Failed si l'etag de la session ne correspond pas à l'en-tête If-Match :
```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
```
### J'obtiens des erreurs comme 405, 409, 503 et 400 lors de l'appel de MPSD.
Collectez des traces Fiddler pour obtenir plus d'informations, puis vérifiez les messages renvoyés dans le corps de HttpResponse.
Vous pouvez également obtenir le corps de la réponse si vous utilisez les XSAPI en définissant la propriété [HCSettingsSetTraceLevel](/fr/reference/live/httpclient/trace/functions/hcsettingssettracelevel) sur [HCTraceLevel](/fr/reference/live/httpclient/trace/enums/hctracelevel)::Information, ce qui affiche les informations dans la sortie de débogage si [HCTraceSetTraceToDebugger](/fr/reference/live/httpclient/trace/functions/hctracesettracetodebugger) est défini, ou vous pouvez utiliser [HCTraceSetClientCallback](/fr/reference/live/httpclient/trace/functions/hctracesetclientcallback) pour obtenir un rappel dans lequel vous pouvez ajouter le journal de trace à la journalisation de votre jeu. Vous pouvez également utiliser [XblAddServiceCallRoutedHandler](/fr/reference/live/xsapi-c/xbox_live_global_c/functions/xbladdservicecallroutedhandler) pour être appelé à chaque appel de service et l'acheminer vers votre propre journalisation.
### Que puis-je ou dois-je modifier dans les modèles de mon titre ?
Les modèles de session ne sont pas des valeurs par défaut, mais plutôt un moule.
Vous ne pouvez cependant pas remplacer les constantes déjà définies dans les modèles, même si vous pouvez en ajouter.
### J'obtiens une erreur indiquant que ma session n'est pas initialisée.
Lorsque l'initialisation des membres est présente dans votre modèle (généralement dans les scénarios de jeu, de groupe et de ticket de match), vous devez vous assurer que « initialize=true » est défini pour suffisamment de réservations de membres (membres nécessaires pour démarrer) afin de réussir le QoS et de résoudre ce problème.
### Ma session n'est pas créée et j'obtiens une réponse HTTP 204.
Cela indique qu'aucun utilisateur n'a été ajouté à la session lors de sa création.
S'il n'y a aucun utilisateur pour une session au moment de sa création, la session n'est pas créée.
Veillez à ajouter au moins un joueur à une session lors de sa création.
Pour les scénarios de serveur dédié, obtenez un joueur qui essaie de créer un match ou qui doit en créer un, et faites de cet utilisateur le joueur initial de ce match.
Vous pouvez également modifier ou supprimer **sessionEmptyTimeout**.
### Quand dois-je interroger MPSD ?
Vous devez éviter d'interroger régulièrement les sessions MPSD.
De manière générale, vous pouvez y parvenir en concevant votre code de façon à n'utiliser la session MPSD que pour l'établissement initial de la connectivité réseau de chaque client, et pour le rétablissement de l'état réseau d'un ou plusieurs clients ayant perdu la connectivité.
Il est également important de tirer parti des primitives de synchronisation basées sur les etags de MPSD afin d'éliminer la nécessité d'actualiser l'état de la session pour résoudre les conditions de concurrence.
Une application courante de ces principes est le cas où un ensemble de N clients doivent tous se connecter ensemble et jouer dans un maillage pair-à-pair.
Plutôt que d'interroger régulièrement la session pour détecter de nouveaux membres, chaque membre peut rejoindre la session, se connecter aux membres déjà présents dans la session et supposer que tous ceux qui rejoindront plus tard feront de même.
Consultez les exemples Chat et Player Rendezvous pour savoir comment implémenter cela.
Dans de rares cas, une interrogation régulière peut être nécessaire pendant de brèves périodes ; contactez votre gestionnaire de compte développeur si vous pensez devoir le faire.
## Related topics
- [Présentation de l'appel direct du service Multijoueur](/fr/services/xbox-services/multiplayer/concepts/live-intro-calling-mp-directly.md)
- [Multiplayer Session Directory (MPSD)](/fr/services/xbox-services/multiplayer/mpsd/live-mpsd-nav.md)
- [Concepts de Multiplayer Session Directory (MPSD)](/fr/services/xbox-services/multiplayer/mpsd/concepts/live-mpsd-concepts-nav.md)
- [Vue d'ensemble de Multiplayer Session Directory](/fr/services/xbox-services/multiplayer/mpsd/live-mpsd-overview.md)
- [Exemple de code Multiplayer Session Directory (MPSD)](/fr/services/xbox-services/multiplayer/mpsd/how-to/live-mpsd-howto-nav.md)