Passer au contenu principal
Les services XBOX peuvent être appelés de deux manières principales : à l’aide de l’API des services XBOX (XSAPI) ou en appelant directement les points de terminaison REST. Quelle que soit la façon dont votre code appelle les services XBOX, il est important d’utiliser des modèles d’appel et une logique de nouvelle tentative appropriés. Pour comprendre comment écrire une logique de nouvelle tentative appropriée, il est nécessaire de connaître les deux types de points de terminaison REST : idempotents et non idempotents. Ils sont décrits ci-dessous.

​
Points de terminaison non idempotents

Les méthodes HTTP qui ont des effets secondaires en cas d’appels répétés sont considérées comme non idempotentes. Cela signifie que si un client appelle le point de terminaison et qu’un délai d’expiration réseau se produit, il n’est pas sûr de réessayer la méthode, car la ressource a peut-être été mise à jour sans que le réseau ait pu informer l’appelant de la réussite. En cas d’erreur, au lieu de réessayer, le client doit d’abord vérifier si l’appel a réussi. Il ne doit réessayer que si l’appel a échoué. Dans l’API des services XBOX, certaines API sont marquées en interne comme appelant des points de terminaison non idempotents. Cela signifie que si des échecs se produisent lors de l’appel de ces points de terminaison, les API ne réessaient pas automatiquement. La liste complète des API non idempotentes est la suivante :

​
Méthodes idempotentes

Les méthodes HTTP idempotentes, en revanche, n’ont pas d’effets secondaires. Elles peuvent donc être réessayées sans risque. Dans l’API des services XBOX, toutes les méthodes idempotentes sont automatiquement réessayées dans certaines conditions. La liste complète des API idempotentes comprend toutes les API qui ne figurent pas dans la liste des API non idempotentes ci-dessus.

​
Pratiques exemplaires de logique de nouvelle tentative

Pour les appels idempotents, les conditions suivantes doivent entraîner une nouvelle tentative automatique :
  • Toutes les erreurs réseau
  • 401: Unauthorized
  • 408: RequestTimeout
  • 429: Too Many Requests
  • 500: InternalError
  • 502: BadGateway
  • 503: ServiceUnavailable
  • 504: GatewayTimeout
Sur UWP, l’erreur 401: Unauthorized est traitée de manière particulière. Cette valeur indique que le jeton d’authentification des services XBOX a expiré; l’API des services XBOX appelle donc le système d’exploitation pour actualiser le jeton, puis effectue une seule nouvelle tentative. Lors d’une nouvelle tentative, la bonne pratique consiste à ne pas appeler le service avant l’heure indiquée par l’en-tête « Retry-After ». XSAPI implémente maintenant cette bonne pratique. Si un code d’état HTTP d’échec et un en-tête « Retry-After » ont été retournés pour une API, les appels supplémentaires à cette même API avant l’heure Retry-After retournent immédiatement l’erreur d’origine sans solliciter le service. Lors d’une nouvelle tentative d’appel, la bonne pratique consiste à appliquer un backoff exponentiel avec une gigue aléatoire afin de répartir la charge sur le service. XSAPI commence avec un délai par défaut de 2 secondes, contrôlé à l’aide de XblContextSettingsSetHttpRetryDelay. Cela signifie que, par défaut, chaque nouvelle tentative applique un backoff exponentiel de 2, 4, 8 secondes ou plus. La gigue fait varier le délai entre la valeur de backoff actuelle et la suivante en fonction du temps de réponse, afin de mieux répartir la charge entre les appareils qui effectuent la nouvelle tentative. Les titres doivent contrôler le temps consacré aux nouvelles tentatives d’un appel. Avec XSAPI, les développeurs contrôlent directement ce temps à l’aide de la fonction XblContextSettingsSetHttpTimeoutWindow. Par défaut, cette valeur est définie sur 20 secondes. La définir sur 0 seconde désactive de fait la logique de nouvelle tentative.

​
Ajustement dynamique du délai d’expiration HTTP interne

XSAPI ajuste dynamiquement le délai d’expiration HTTP interne en fonction du temps restant dans XblContextSettingsGetHttpTimeoutWindow. Le délai d’expiration HTTP interne détermine combien de temps le système d’exploitation consacre à l’opération réseau HTTP avant de l’abandonner. L’appel n’est réessayé que s’il reste au moins 5 secondes dans XblContextSettingsGetHttpTimeoutWindow, afin de laisser un délai raisonnable pour que l’appel se termine. Cette règle ne s’applique pas au premier appel; il est donc acceptable de définir XblContextSettingsSetHttpTimeoutWindow sur 0, ce qui entraîne un seul appel. Grâce à cette logique, XblContextSettingsGetHttpTimeoutWindow est plus déterministe quant au moment où l’appel d’API rend la main. Si un en-tête « Retry-After » a été retourné, aucune nouvelle tentative n’est effectuée avant que l’heure « Retry-After » soit atteinte. Si l’heure « Retry-After » est postérieure à XblContextSettingsGetHttpTimeoutWindow, l’appel rend la main à la fin de XblContextSettingsGetHttpTimeoutWindow.

​
Gestion des erreurs

Les développeurs de titres doivent toujours mettre en place une gestion des erreurs appropriée pour chaque appel de service et s’assurer qu’ils gèrent correctement les réponses d’échec. De nombreuses conditions réelles peuvent faire qu’une requête aux services XBOX retourne des codes d’échec, par exemple :
  • Le réseau n’est pas disponible. Par exemple, l’appareil a perdu la 4G ou le Wi-Fi, ou le réseau est tombé en panne.
  • Les services subissent une charge trop importante (503).
  • Une défaillance s’est produite sur le service (500).
  • Trop de requêtes ont été envoyées au service (429).
  • Conflit d’opération d’écriture (412). Par exemple, un autre joueur d’une session multijoueur a soumis une modification en premier.
  • L’utilisateur a été banni ou n’a pas l’autorisation.
  • L’utilisateur s’est déconnecté.
Une gestion des erreurs appropriée est essentielle pour garantir le bon fonctionnement du jeu dans ces conditions. Pour plus de détails sur les pratiques exemplaires de gestion des erreurs, consultez Gestion des erreurs. Pour une vidéo sur ce sujet, consultez la présentation XSAPI: C++, No Exceptions! dans les vidéos Xfest 2015.

​
Meilleurs modèles d’appel

​
Utiliser des requêtes groupées

Certains points de terminaison prennent en charge le regroupement ou l’agrégation d’un ensemble de requêtes en un seul appel. Par exemple, avec le service de profil des services XBOX, vous pouvez demander le profil d’un seul utilisateur ou ceux d’un ensemble d’utilisateurs. Ainsi, si vous avez besoin des profils d’un ensemble d’utilisateurs, il serait très inefficace d’appeler le point de terminaison ou l’API un par un pour chaque profil utilisateur. Chaque appel ajoute une surcharge d’authentification importante. Transmettez plutôt à l’API tous les utilisateurs pour lesquels vous souhaitez obtenir des informations en une seule fois, afin que le point de terminaison puisse traiter tous les profils utilisateur simultanément et retourner une seule réponse.

​
Utiliser le service Real-Time Activity (RTA) au lieu de l’interrogation

La bonne pratique consiste à utiliser le service Real-Time Activity (RTA) au lieu d’une interrogation périodique. Le service Real-Time Activity expose un WebSocket qui envoie une notification aux clients lorsque des ressources ciblées changent sur le service. Le service RTA fournit des notifications sur les changements de présence, les changements de statistiques, les modifications de documents de session multijoueur et les changements de relations sociales. Pour indiquer les informations qui l’intéressent, le client doit d’abord s’abonner à l’élément au moyen du WebSocket. Cela évite d’interroger le service pour détecter les changements, puisque vous serez informé précisément du moment où l’élément change. XSAPI expose le service RTA sous la forme d’un ensemble d’API d’abonnement que les clients peuvent utiliser. Chacune de ces API dispose d’API *ChangedHandler correspondantes, qui acceptent une fonction de rappel appelée lorsqu’un élément change.
  • XblPresenceSubscribeToDevicePresenceChange
  • XblPresenceSubscribeToTitlePresenceChange
  • XblUserStatisticsSubscribeToStatisticChange
  • XblSocialSubscribeToSocialRelationshipChange

​
Utiliser les gestionnaires côté client de XSAPI

XSAPI dispose d’un ensemble de gestionnaires qui font office de cache et de machines à états et qui se chargent de tout le travail complexe pour certains scénarios.

​
Social Manager

Social Manager se charge de tout le travail complexe lié aux listes d’amis et aux profils. Social Manager maintient à jour votre liste d’amis, leurs profils et leurs données de présence à l’aide du service RTA. Social Manager expose une API synchrone très bien adaptée aux moteurs de jeu. Les jeux peuvent appeler fréquemment les API de Social Manager, car celui-ci conserve en mémoire un cache des informations les plus récentes du service. Consultez Social Manager.

​
Multiplayer Manager

Pour la gestion des sessions multijoueur, Multiplayer Manager est une solution prête à l’emploi pour les jeux multijoueur traditionnels. L’API Multiplayer Manager comprend la gestion de la liste des joueurs et des sessions, gère les invitations de jeu, la jonction en cours de partie et le matchmaking, et s’intègre à votre solution de mise en réseau existante. Elle se charge de tout le travail complexe lié à l’implémentation des flux multijoueur traditionnels. Consultez Multiplayer Manager.

​
Limitation (limitation précise du débit)

Les services XBOX appliquent une limitation pour empêcher un appareil de soumettre le service à une charge extrême. Il est important de savoir quand votre titre a été limité. Pour déterminer si votre titre a été limité, utilisez l’une des approches suivantes :
  • Surveiller le code d’état HTTP 429
  • Utiliser des assertions de débogage
  • Utiliser l’outil XBOX services Trace Analyzer
Ces approches sont décrites ci-dessous.

​
Surveillance du code d’état HTTP 429

Vous pouvez utiliser Fiddler et surveiller le renvoi éventuel d’un code d’état HTTP 429. La réponse JSON contient des détails sur la manière dont le point de terminaison a été limité. Par exemple :
Si vous utilisez XSAPI, les API retournent une erreur HTTP_E_STATUS_429_TOO_MANY_REQUESTS et définissent le message d’erreur de manière à détailler la façon dont l’API a été limitée.

​
Utilisation d’assertions de débogage

Avec XSAPI, si l’appel est limité alors que vous êtes dans un sandbox de développement et que vous utilisez une build de débogage du titre, une assertion est déclenchée pour informer immédiatement le développeur qu’une limitation s’est produite. Cela permet d’éviter de passer involontairement à côté d’une erreur de limitation 429 en raison d’un code mal écrit. Si vous souhaitez désactiver ces assertions pour continuer à travailler sans corriger le code incriminé, vous pouvez utiliser l’API XblDisableAssertsForXboxLiveThrottlingInDevSandboxes :
Cette API n’empêche pas votre titre d’être limité. Cette API désactive les assertions dans les sandboxes de développement lors de l’utilisation d’une build de débogage.

​
Utilisation de l’outil XBOX services Trace Analyzer

Une autre façon de déterminer si votre titre a été limité consiste à enregistrer une trace des appels aux services XBOX, puis à l’analyser à l’aide de l’outil XBOX services Trace Analyzer. Pour enregistrer une trace, vous pouvez utiliser Fiddler pour enregistrer un fichier .SAZ, ou utiliser la journalisation des traces intégrée de XSAPI. Pour plus d’informations sur l’activation des traces dans XSAPI, consultez l’article XBOX XBOX services Trace Analyzer (XblTraceAnalyzer.exe). Une fois la trace obtenue, l’outil XBOX services Trace Analyzer vous avertit lorsqu’il détecte des appels limités.

​
Les services XBOX sont-ils opérationnels?

Les services XBOX constituent un ensemble de microservices qui exposent des fonctionnalités XBOX telles que le profil, les amis et la présence, les statistiques, les classements, les succès, le multijoueur et le matchmaking. Il n’existe pas de serveur ou de point de terminaison unique qui détermine si les services XBOX sont opérationnels. Si un serveur tombe en panne, les autres microservices des services XBOX sont en grande partie indépendants et devraient rester opérationnels. Si un service subit une panne temporaire, il est important de savoir si l’appel à ce service est critique pour votre jeu. Essayez d’offrir une expérience raisonnable en cas de problèmes intermittents de réseau ou de service. Par exemple, si le service de présence retourne un échec, cet appel n’est probablement pas critique pour votre jeu. Signalez à l’utilisateur la dernière présence connue, au lieu d’indiquer que le réseau XBOX est hors service. Les services XBOX suivent le modèle de cohérence dit « cohérence à terme ». Cela signifie que si aucune nouvelle mise à jour n’est effectuée, toutes les requêtes portant sur cette ressource finiront par retourner la dernière valeur mise à jour. Il existe donc une courte période pendant laquelle les informations sont obsolètes, le temps que les données se propagent.
Dernière modification le 19 octobre 2026