DevKit Agent
O DevKit Agent é uma máquina de estado simples em sua operação. A cada 10 segundos ou imediatamente após processar um trabalho, o agente envia um heartbeat para solicitar um único trabalho ao servidor. O trabalho é então processado imediatamente, e o activeJobId é enviado de volta no próximo heartbeat. Se nenhum trabalho estiver sendo processado, o activeJobID será um GUID com todos os valores zero. O intervalo de heartbeat pode ser ajustado usando a propriedade heartbeatInterval em KitHeartbeatResponse. Os heartbeats subsequentes são enviados nesse intervalo, a menos que ele seja alterado novamente no servidor ou quando o agente for reiniciado. Após qualquer reinicialização do console, o intervalo é redefinido para o valor padrão de 10 segundos.O agente não armazena seu estado, além do último jobID processado, mas informa a data e a hora em que foi iniciado e o tempo de atividade do console.
Traga seu próprio serviço
O DevKit Agent foi projetado com base na premissa de trazer seu próprio serviço. As definições de configuração no console fornecem ao agente o URI do seu serviço. Seu servidor escuta solicitações de heartbeat do agente, inspeciona a mensagem de heartbeat para determinar o próximo trabalho apropriado para o agente executar e, em seguida, envia o trabalho ao agente. Seu servidor está no controle; o agente não executa nenhuma operação lógica que interfira no fluxo de trabalho pretendido. O Microsoft Game Development Kit (GDK) fornece o DevKitAgentAPI.yaml. É um documento compatível com OpenApi v3.0.3 que descreve o contrato entre o DevKit Agent e o seu servidor. Esse documento detalha os caminhos com suporte (por exemplo, /KitHeartbeat) e os esquemas de componentes (por exemplo, ExecuteCommandJob, KitHeartbeatResponse, FileUpload etc.). A partir do GDK de junho de 2023, o arquivo será instalado em %SDK_ROOT%\toolKit\include\DevKitAgentAPI.yaml. O agente funcionará com qualquer implementação de serviço que siga o contrato OpenAPI. Para obter mais informações sobre o contrato OpenAPI, veja o seguinte:- https://spec.openapis.org/oas/v3.0.3.html
- https://openapi-generator.tech/docs/usage
- https://openapi-generator.tech/docs/generators/
- Documentação da API web do ASP.NET Core com Swagger / OpenAPI
Solicitação de heartbeat do agente
Veja a seguir um exemplo de solicitação de heartbeat após um executeCommandJob, formatado em JSON. O heartbeat contém detalhes sobre o agente (versão do esquema, tempo de atividade etc.), o console (ipAddress, runningApplication etc.) e o status do trabalho do agente (activeJobId, lastProcessedJobResult etc.). Para ver o esquema completo, você pode carregar o DevKitAgentAPI.yaml em vários geradores, como o Swagger.Trabalhos
Os trabalhos são operações únicas para o agente processar. Atualmente, há quatro tipos de trabalhos:- executeCommandJob: executa um comando no console. O conjunto completo de comandos wd* está disponível para execução. Você pode encontrar mais informações sobre as ferramentas de linha de comando do console wd* aqui.
- downloadFilesJob: a URL de origem de onde o arquivo será obtido. Essa URL pode ser arbitrária e oferece a mesma autenticação configurada que as chamadas de heartbeat. As chamadas são feitas via GET e não precisam usar SSL.
- uploadFilesJob: a URL de destino para onde o arquivo será carregado. Essa URL pode ser arbitrária e oferece a mesma autenticação configurada que as chamadas de heartbeat. As chamadas são feitas via POST ou PUT e não precisam usar SSL
- cancelCurrentJob: esse trabalho instrui o agente a cancelar o trabalho em execução no momento.
> - Defina WaitForExit como false em um trabalho Execute Command para forçar uma execução do tipo “disparar e esquecer”. A propriedade LastProcessedJobResult não será preenchida com nenhuma saída ou código de saída, e o agente solicitará imediatamente o próximo trabalho.
Segurança e autenticação
Ao usar o agente, projetamos um sistema que permite uma comunicação segura e autenticada para o serviço de produção e flexibilidade durante o desenvolvimento. O agente requer comunicação com o servidor por HTTPS e se autentica no servidor usando um Xtoken. Por isso, o URI do agente precisa ser configurado como uma Relying Party no Partner Center.- O HTTPS permite que o dispositivo saiba que está se comunicando com um serviço confiável, mas não permite que o serviço saiba que o dispositivo é confiável.
- Os Xtokens são usados para que o serviço possa autenticar o dispositivo com a declaração Developer Device ID (ddi), a fim de identificar exclusivamente o kit de desenvolvimento.
XBOX-AGENT-XTOKEN da solicitação de heartbeat. Em seguida, o servidor descriptografa e valida a assinatura do token para autenticar o agente. O servidor pode então responder com um novo trabalho ou ignorar a solicitação. Uma nova declaração foi adicionada como opção para a configuração da sua Relying Party, chamada Developer Device ID (ddi). Essa nova declaração foi criada para garantir que o dispositivo que envia heartbeats ao seu serviço seja o esperado. A declaração ddi está disponível para qualquer relying party configurada no Partner Center, mas observe que ela só será preenchida quando executada em um XBOX Developer Kit; no varejo, retornará null. A ddi retornará a XBOX Live Device ID do dispositivo, e a XBOX Live Device ID do seu DevKit está disponível no xbdiaginfo ou em Settings no shell de varejo.
O exposto acima é a prática recomendada para sua implantação de produção; certificados autoassinados podem ser usados com o DevKit Agent e seu serviço, e certificados totalmente encadeados não são necessários. Além disso, durante o desenvolvimento, ao trabalhar com kits conhecidos, não seria necessário inspecionar a ddi no servidor.
Para obter mais informações sobre XTokens, veja https://developer.microsoft.com/en-us/games/xbox/docs/gdk/live-security-token-nav.