DevKit Agent para administrar kits de desarrollo de XBOX - XBOX Game Development Documentation

El DevKit Agent es un proceso que se ejecuta en cada XBOX Development Kit. Este proceso le permite administrar sus kits de desarrollo desde un servicio hospedado para escenarios locales y remotos. El agente envía solicitudes de latido al servicio configurado con una cadencia regular y configurable, y su servicio puede emitir trabajos que se ejecutan en la consola. Los trabajos son operaciones atómicas para escenarios de administración de archivos y de la consola. Los escenarios comunes incluyen la configuración de la consola, la ejecución de títulos y las operaciones de copia de archivos mediante las herramientas wd* que se describen aquí.

DevKit Agent

El DevKit Agent es, en su funcionamiento, una máquina de estados sencilla. Cada 10 segundos o inmediatamente después de procesar un trabajo, el agente envía un latido para solicitar un único trabajo al servidor. El trabajo se procesa de inmediato y activeJobId se devuelve en el siguiente latido. Si no se está procesando ningún trabajo, activeJobID es un GUID compuesto solo por ceros. El intervalo de latido se puede ajustar mediante la propiedad heartbeatInterval en KitHeartbeatResponse. Los latidos posteriores se envían con ese intervalo a menos que se vuelva a cambiar en el servidor o cuando el agente se reinicie. Después de cualquier reinicio de la consola, el intervalo se restablece a un valor predeterminado de 10 segundos.

El agente no almacena su estado, más allá del último jobID procesado, pero sí informa de la fecha y hora en que se inició y del tiempo de actividad de la consola.

Traiga su propio servicio

El DevKit Agent está diseñado en torno a la premisa de que usted trae su propio servicio. Las opciones de configuración de la consola proporcionan al agente el URI de su servicio. Su servidor escucha las solicitudes de latido del agente, inspecciona el mensaje de latido para determinar el siguiente trabajo apropiado que debe ejecutar el agente y, después, envía el trabajo al agente. Su servidor tiene el control; el agente no realiza ninguna operación lógica que interfiera con el flujo de trabajo previsto. El Microsoft Game Development Kit (GDK) proporciona DevKitAgentAPI.yaml. Es un documento compatible con OpenApi v3.0.3 que describe el contrato entre el DevKit Agent y su servidor. Este documento detalla las rutas de acceso admitidas (por ejemplo, /KitHeartbeat) y los esquemas de componentes (por ejemplo, ExecuteCommandJob, KitHeartbeatResponse, FileUpload, etc.). A partir del GDK de junio de 2023, el archivo se instala en %SDK_ROOT%\toolKit\include\DevKitAgentAPI.yaml. El agente interactuará con cualquier implementación de servicio que se adhiera al contrato de OpenAPI. Para obtener más información sobre el contrato de OpenAPI, consulte lo siguiente:

Solicitud de latido del agente

El siguiente es un ejemplo de una solicitud de latido después de un executeCommandJob, con formato JSON. El latido contiene detalles sobre el agente (versión del esquema, tiempo de actividad, etc.), la consola (ipAddress, runningApplication, etc.) y el estado de los trabajos del agente (activeJobId, lastProcessedJobResult, etc.). Para ver el esquema completo, puede cargar DevKitAgentAPI.yaml en diversos generadores, como Swagger.

  "agentSchemaVersion": "2023.10.0",
  "kit": {
    "hostname": "DevKit01",
    "ipAddress": "172.200.0.1",
    "osVersion": "10.0.25398.2258 (xb_flt_2309zn.230918-2000)",
     "runningApplicationId": "41336PublisherName.ExampleGame_8wekyb3d8bbwe!App",
    "runningApplication": {
      "displayName": "Example Game",
      "fullName": "41336PublisherName.ExampleGame",
      "aumids": "41336PublisherName.ExampleGame_8wekyb3d8bbwe!App"
    },
    "uptime": 1234567890,
    "deviceType": "ScarlettDevkit"
  },
  "activeJobId": "85a5cb10-cee1-4eac-865d-978746090428",
  "lastProcessedJobResult": {
    "id": "235a5dfb10-lbb5-4bad-725d-978746083564",
    "executeCommandJobResult": {
      "commandOutput": "Here are some \"quotes\"",
      "exitCode": 1,
      "processId": 1337,
      "job": {
        "commandLine": "cmd.exe /C ECHO Here are some \\\"quotes.\\\"",
        "workingDirectory": "d:\\",
        "commandLineIsScript": true,
        "waitForExit": true,
        "willReboot": true
      }
    },
    "jobType": "executeCommandJob"
  },
  "agentStartTime": "2023-04-07T23:47:13.434Z",
  "currentDateTime": "2023-05-09T23:47:13.434Z"
}

Trabajos

Los trabajos son operaciones únicas que el agente debe procesar. Actualmente hay cuatro tipos de trabajos:

executeCommandJob: Ejecuta un comando en la consola. Está disponible el conjunto completo de comandos wd* para su ejecución. Puede encontrar más información sobre las herramientas de línea de comandos de consola wd* aquí.
downloadFilesJob: La dirección URL de origen de donde se recupera el archivo. Esta dirección URL puede ser arbitraria y proporciona la misma autenticación configurada que las llamadas de latido. Las llamadas se realizan mediante GET y no es obligatorio que usen SSL.
uploadFilesJob: La dirección URL de destino donde se carga el archivo. Esta dirección URL puede ser arbitraria y proporciona la misma autenticación configurada que las llamadas de latido. Las llamadas se realizan mediante POST o PUT y no es obligatorio que usen SSL
cancelCurrentJob: Este trabajo indica al agente que cancele el trabajo que se está ejecutando actualmente.

> - Establezca WaitForExit en false en un trabajo Execute Command para forzar una ejecución de tipo “iniciar y olvidar”. La propiedad LastProcessedJobResult no se rellenará con ninguna salida ni código de salida, y el agente solicitará inmediatamente el siguiente trabajo.

Seguridad y autenticación

Al usar el agente, diseñamos un sistema que permite una comunicación segura y autenticada para el servicio de producción, así como facilidades durante el desarrollo. El agente requiere la comunicación con el servidor a través de HTTPS y se autentica en el servidor mediante un Xtoken. Como resultado, el URI del agente debe configurarse como un usuario de confianza (Relying Party) en el Partner Center.

HTTPS permite al dispositivo saber que se está comunicando con un servicio de confianza, pero HTTPS no permite al servicio saber que el dispositivo es de confianza.
Los Xtokens se usan para que el servicio pueda autenticar el dispositivo con la notificación Developer Device ID (ddi), para identificar de forma única el kit de desarrollo.

El agente pasa un Xtoken generado al servidor en el encabezado XBOX-AGENT-XTOKEN de la solicitud de latido. A continuación, el servidor descifra y valida la firma del token para autenticar el agente. El servidor puede entonces responder con un trabajo nuevo o ignorar la solicitud. Se ha agregado una nueva notificación como opción para la configuración de su usuario de confianza, denominada Developer Device ID (ddi). Esta nueva notificación está diseñada para garantizar que el dispositivo que envía latidos a su servicio es el esperado. La notificación ddi está disponible para cualquier usuario de confianza configurado en el Partner Center, pero tenga en cuenta que esta notificación solo se rellenará cuando se ejecute en un XBOX Developer Kit; devolverá null en dispositivos comerciales. La ddi devolverá el XBOX Live Device ID del dispositivo, y el XBOX Live Device ID de su DevKit está disponible mediante xbdiaginfo o desde Configuración en el shell comercial. Lo anterior es el procedimiento recomendado para su implementación de producción; se pueden usar certificados autofirmados con el DevKit Agent y su servicio, no se requieren certificados con cadena completa. Además, durante el desarrollo, al trabajar con kits conocidos, no sería necesario inspeccionar la ddi en el servidor. Para obtener más información sobre los XTokens, consulte https://developer.microsoft.com/en-us/games/xbox/docs/gdk/live-security-token-nav.

Configurar el DevKit Agent

Establezca dos valores de configuración en la consola: el URI del servidor (DevkitAgentServiceUri) y el usuario de confianza (DevKitAgentRelyingParty) Para establecer estos valores, vaya a una línea de comandos del Microsoft Game Development Kit (GDK), conéctese a la consola de destino y emita los comandos siguientes.

C:\Program Files (x86)\Microsoft GDK\bin>xbconfig DevKitAgentServiceUri=https://myserver.mydomain.com

DevKitAgentServiceUri: https://myserver.mydomain.com

C:\Program Files (x86)\Microsoft GDK\bin>xbconfig DevKitAgentRelyingParty=rp://myagentRP.mydomain.com
  
DevKitAgentRelyingParty: rp://myagentRP.mydomain.com

Iniciar y detener el agente

El agente se inicia y se detiene automáticamente en función de la presencia de la opción de configuración DevKitAgentServiceUri. Para detener el agente, emita el siguiente comando desde un símbolo del sistema de XBOX

C:\Program Files (x86)\Microsoft GDK\bin>xbconfig DevKitAgentServiceUri=""

o envíe el comando wdConfig equivalente a través del servidor del agente:

wdconfig DevKitAgentServiceUri=""

Consulte también

Herramientas de línea de comandos de la consola

​DevKit Agent

​Traiga su propio servicio

​Solicitud de latido del agente

​Trabajos

​Seguridad y autenticación

​Configurar el DevKit Agent

​Iniciar y detener el agente

​Consulte también

DevKit Agent

Traiga su propio servicio

Solicitud de latido del agente

Trabajos

Seguridad y autenticación

Configurar el DevKit Agent

Iniciar y detener el agente

Consulte también