DevKit Agent
Le fonctionnement du DevKit Agent repose sur une simple machine à états. Toutes les 10 secondes, ou immédiatement après le traitement d’une tâche, l’agent envoie une pulsation pour demander une seule tâche au serveur. La tâche est alors immédiatement traitée et activeJobId est retourné dans la pulsation suivante. Si aucune tâche n’est en cours de traitement, activeJobID est un GUID composé uniquement de zéros. L’intervalle de pulsation peut être ajusté à l’aide de la propriété heartbeatInterval de KitHeartbeatResponse. Les pulsations suivantes sont envoyées à cet intervalle, sauf s’il est à nouveau modifié sur le serveur ou au redémarrage de l’agent. Après tout redémarrage de la console, l’intervalle est réinitialisé à la valeur par défaut de 10 secondes.L’agent n’stocke pas son état, hormis le dernier jobID traité, mais il indique la date et l’heure de son démarrage ainsi que la durée de fonctionnement de la console.
Utiliser votre propre service
Le DevKit Agent est conçu sur le principe que vous utilisez votre propre service. Les paramètres de configuration de la console fournissent à l’agent l’URI de votre service. Votre serveur écoute les requêtes de pulsation de l’agent, examine le message de pulsation pour déterminer la prochaine tâche que l’agent doit exécuter, puis envoie cette tâche à l’agent. Votre serveur garde le contrôle : l’agent n’effectue aucune opération logique susceptible d’interférer avec le flux de travail souhaité. Le Microsoft Game Development Kit (GDK) fournit DevKitAgentAPI.yaml. Il s’agit d’un document conforme à OpenApi v3.0.3 qui décrit le contrat entre le DevKit Agent et votre serveur. Ce document détaille les chemins pris en charge (par exemple, /KitHeartbeat) et les schémas de composants (par exemple, ExecuteCommandJob, KitHeartbeatResponse, FileUpload, etc.). À partir du GDK de juin 2023, le fichier est installé dans %SDK_ROOT%\toolKit\include\DevKitAgentAPI.yaml. L’agent peut fonctionner avec toute implémentation de service qui respecte le contrat OpenAPI. Pour plus de renseignements sur le contrat OpenAPI, consultez les ressources suivantes :- https://spec.openapis.org/oas/v3.0.3.html
- https://openapi-generator.tech/docs/usage
- https://openapi-generator.tech/docs/generators/
- Documentation de l’API Web ASP.NET Core avec Swagger / OpenAPI
Requête de pulsation de l’agent
Voici un exemple de requête de pulsation faisant suite à un executeCommandJob, au format JSON. La pulsation contient des détails sur l’agent (version du schéma, durée de fonctionnement, etc.), sur la console (ipAddress, runningApplication, etc.) et sur l’état des tâches de l’agent (activeJobId, lastProcessedJobResult, etc.). Pour afficher le schéma complet, vous pouvez charger DevKitAgentAPI.yaml dans divers générateurs, comme Swagger.Tâches
Les tâches sont des opérations uniques que l’agent doit traiter. Il existe actuellement quatre types de tâches :- executeCommandJob : exécute une commande sur la console. L’ensemble des commandes wd* peut être exécuté. Vous trouverez plus d’informations sur les outils en ligne de commande de la console wd* ici.
- downloadFilesJob : URL source à partir de laquelle récupérer le fichier. Cette URL peut être arbitraire et fournit la même authentification configurée que les appels de pulsation. Les appels sont effectués par GET et ne sont pas tenus d’utiliser SSL.
- uploadFilesJob : URL de destination vers laquelle téléverser le fichier. Cette URL peut être arbitraire et fournit la même authentification configurée que les appels de pulsation. Les appels sont effectués par POST ou PUT et ne sont pas tenus d’utiliser SSL
- cancelCurrentJob : cette tâche indique à l’agent d’annuler la tâche en cours d’exécution.
> - Définissez WaitForExit sur false dans une tâche Execute Command pour forcer une exécution de type « fire-and-forget ». La propriété LastProcessedJobResult ne sera alimentée par aucune sortie ni aucun code de sortie, et l’agent demandera immédiatement la tâche suivante.
Sécurité et authentification
Pour l’utilisation de l’agent, nous avons conçu un système qui permet une communication sécurisée et authentifiée avec le service de production, tout en offrant des facilités pendant le développement. L’agent doit communiquer avec le serveur par HTTPS et s’authentifie auprès du serveur à l’aide d’un Xtoken. Par conséquent, l’URI de l’agent doit être configuré en tant que partie de confiance (Relying Party) dans Partner Center.- HTTPS permet à l’appareil de savoir qu’il communique avec un service approuvé, mais HTTPS ne permet pas au service de savoir que l’appareil est approuvé.
- Les Xtokens permettent au service d’authentifier l’appareil grâce à la revendication Developer Device ID (ddi), afin d’identifier de façon unique le kit de développement.
XBOX-AGENT-XTOKEN de la requête de pulsation. Le serveur déchiffre ensuite le jeton et valide sa signature pour authentifier l’agent. Le serveur peut alors répondre avec une nouvelle tâche ou ignorer la requête. Une nouvelle revendication, appelée Developer Device ID (ddi), a été ajoutée en option à la configuration de votre partie de confiance. Elle est conçue pour vérifier que l’appareil qui envoie des pulsations à votre service est bien attendu. La revendication ddi est disponible pour toute partie de confiance configurée dans Partner Center, mais notez qu’elle n’est renseignée que lors d’une exécution sur un kit de développement XBOX; elle retourne null en version commerciale. La revendication ddi retourne le XBOX Live Device ID de l’appareil; le XBOX Live Device ID de votre kit de développement est disponible par xbdiaginfo ou dans les paramètres de l’interface commerciale.
Ce qui précède constitue la meilleure pratique pour votre déploiement en production. Des certificats auto-signés peuvent être utilisés avec le DevKit Agent et votre service; des certificats entièrement chaînés ne sont pas requis. De plus, pendant le développement, lorsque vous travaillez avec des kits connus, il n’est pas nécessaire d’examiner la revendication ddi sur le serveur.
Pour plus de renseignements sur les XTokens, consultez https://developer.microsoft.com/en-us/games/xbox/docs/gdk/live-security-token-nav.