- Résumé des révisions
- Introduction
- Terminologie utilisée dans ce document
- Multiplayer Session Directory
- Sessions MPSD
- Attributs des modèles de session
- Mise à jour du schéma de contrat
- Initialisation des membres dans les documents de session
- Session de ticket de match
- Modèles de qualité de service (QoS)
- Détails de la phase QoS et de l’initialisation de session
- Session XBOX Cloud Compute
- Session brute et propriétés de titre personnalisées
- Dégradation des membres actifs
- FAQ et résolution des problèmes
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 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.
Terminologie utilisée dans ce document
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).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.
Sessions MPSD
Les sessions tiennent à jour deux listes d’entités associées :- Les membres (utilisateurs) qui ont rejoint une session ou y ont été invités.
- Les serveurs (serveurs cloud ou serveurs dédiés) qui ont rejoint la session.
- Des valeurs constantes définies lors de la création.
- Des propriétés modifiables.
- 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.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. 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.
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 :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 :
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.
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/systemDé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 :
-
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.
-
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 ».
-
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.
- 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.
- 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 :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//constants/systemModè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 :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.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 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.
- 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.
- 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.
- 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é.
- 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.
- Si le membre est actif, activeTitleId est le titre dans lequel le membre est actif, en décimal.
- 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.
- Présent si ce membre se trouve dans le tableau properties/system/turn ; absent sinon.
- 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.
- 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.
- 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.
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).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.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 :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 :-
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.
- Vérifiez l’URI que vous utilisez.
- 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 :- 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_<number>» pour inviter un joueur.
- 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 «