XBOX 개발 키트 관리용 DevKit Agent - XBOX Game Development Documentation

DevKit Agent는 모든 XBOX 개발 키트에서 실행되는 프로세스입니다. 이 프로세스를 사용하면 로컬 및 원격 시나리오에서 호스팅된 서비스로부터 개발 키트를 관리할 수 있습니다. 에이전트는 규칙적이고 구성 가능한 주기로 구성된 서비스에 하트비트 요청을 보내며, 서비스는 콘솔에서 실행되는 작업을 발급할 수 있습니다. 작업은 파일 및 콘솔 관리 시나리오에 대한 원자적 작업입니다. 일반적인 시나리오에는 여기에 설명된 것처럼 wd* 도구를 사용한 콘솔 구성, 타이틀 실행, 파일 복사 작업이 포함됩니다.

DevKit Agent

DevKit Agent는 작동에서 간단한 상태 머신입니다. 10초마다 또는 작업을 처리한 직후 에이전트는 서버에서 단일 작업을 요청하는 하트비트를 보냅니다. 그런 다음 작업이 즉시 처리되고 activeJobId가 다음 하트비트에서 다시 전송됩니다. 처리 중인 작업이 없으면 activeJobID는 모두 0인 GUID입니다. 하트비트 간격은 KitHeartbeatResponse의 heartbeatInterval 속성을 사용하여 조정할 수 있습니다. 서버에서 다시 변경되거나 에이전트가 다시 시작되지 않는 한 후속 하트비트는 해당 간격으로 전송됩니다. 콘솔이 다시 시작되면 간격이 기본값인 10초로 재설정됩니다.

에이전트는 마지막으로 처리된 jobID를 넘어 상태를 저장하지 않지만 시작된 날짜와 시간, 콘솔의 가동 시간을 보고합니다.

자체 서비스 가져오기

DevKit Agent는 자체 서비스를 가져오는 전제를 중심으로 설계되었습니다. 콘솔의 구성 설정은 에이전트에 서비스의 URI를 제공합니다. 서버는 에이전트의 하트비트 요청을 수신 대기하고, 하트비트 메시지를 검사하여 에이전트가 실행할 다음 적절한 작업을 결정한 다음 작업을 에이전트에 보냅니다. 서버가 제어권을 갖고 있으며 에이전트는 의도된 워크플로에 방해가 되는 논리 작업을 수행하지 않습니다. Microsoft Game Development Kit(GDK)는 DevKitAgentAPI.yaml을 제공합니다. 이는 DevKit Agent와 서버 간의 계약을 설명하는 OpenApi v3.0.3 규격 문서입니다. 이 문서는 지원되는 경로(예: /KitHeartbeat) 및 구성 요소 스키마(예: ExecuteCommandJob, KitHeartbeatResponse, FileUpload 등)에 대해 자세히 설명합니다. 2023년 6월 GDK부터 파일은 %SDK_ROOT%\toolKit\include\DevKitAgentAPI.yaml에 설치됩니다. 에이전트는 OpenAPI 계약을 준수하는 모든 서비스 구현과 인터페이스합니다. OpenAPI 계약에 대한 자세한 내용은 다음을 참조하십시오.

에이전트 하트비트 요청

다음은 executeCommandJob에 이은 하트비트 요청의 예이며 JSON 형식입니다. 하트비트에는 에이전트(스키마 버전, 가동 시간 등), 콘솔(ipAddress, runningApplication 등) 및 에이전트의 작업 상태(activeJobId, lastProcessedJobResult 등)에 대한 세부 정보가 포함되어 있습니다. 전체 스키마를 보려면 Swagger와 같은 다양한 생성기로 DevKitAgentAPI.yaml을 로드할 수 있습니다.

  "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"
}

작업

작업은 에이전트가 처리할 단일 작업입니다. 현재 네 가지 유형의 작업이 있습니다:

executeCommandJob: 콘솔에서 명령을 실행합니다. 실행할 wd* 명령의 전체 세트가 사용 가능합니다. wd* 콘솔 명령줄 도구에 대한 자세한 내용은 여기를 참조하십시오.
downloadFilesJob: 파일을 검색할 원본 URL입니다. 이 URL은 임의적일 수 있으며 하트비트 호출과 동일하게 구성된 인증을 제공합니다. 호출은 GET을 통해 수행되며 SSL을 사용할 필요가 없습니다.
uploadFilesJob: 파일을 업로드할 대상 URL입니다. 이 URL은 임의적일 수 있으며 하트비트 호출과 동일하게 구성된 인증을 제공합니다. 호출은 POST 또는 PUT을 통해 수행되며 SSL을 사용할 필요가 없습니다
cancelCurrentJob: 이 작업은 에이전트에게 현재 실행 중인 작업을 취소하도록 지시합니다.

> - Execute Command 작업에서 WaitForExit를 false로 설정하여 실행 후 잊기(fire-and-forget) 실행을 강제합니다. LastProcessedJobResult 속성은 어떤 출력이나 종료 코드로도 채워지지 않으며 에이전트는 즉시 다음 작업을 요청합니다.

보안 및 인증

에이전트를 사용할 때 프로덕션 서비스에 대한 안전하고 인증된 통신과 개발 중의 편의를 허용하는 시스템을 설계했습니다. 에이전트는 HTTPS를 통해 서버와 통신해야 하며 Xtoken을 사용하여 서버에 인증합니다. 결과적으로 에이전트 URI는 파트너 센터에서 신뢰 당사자로 구성되어야 합니다.

HTTPS는 장치가 신뢰할 수 있는 서비스와 통신하고 있음을 알려주지만, HTTPS는 서비스에 장치가 신뢰할 수 있음을 알려주지는 않습니다.
Xtoken은 서비스가 Developer Device ID(ddi) 클레임으로 장치를 인증하여 개발 키트를 고유하게 식별할 수 있도록 사용됩니다.

에이전트는 하트비트 요청의 XBOX-AGENT-XTOKEN 헤더에 생성된 Xtoken을 서버로 전달합니다. 그런 다음 서버는 토큰 서명을 복호화하고 검증하여 에이전트를 인증합니다. 그런 다음 서버는 새 작업으로 응답하거나 요청을 무시할 수 있습니다. 신뢰 당사자 구성에 대한 옵션으로 Developer Device ID(ddi)라는 새 클레임이 추가되었습니다. 이 새 클레임은 서비스에 하트비트를 보내는 장치가 예상되는지 확인하는 데 사용되도록 설계되었습니다. ddi 클레임은 파트너 센터에서 구성된 모든 신뢰 당사자에서 사용할 수 있지만 이 클레임은 XBOX 개발자 키트에서 실행할 때만 채워지며 소매용에서는 null을 반환합니다. ddi는 장치의 XBOX Live 장치 ID를 반환하며 개발 키트의 XBOX Live 장치 ID는 xbdiaginfo 또는 소매 셸의 설정에서 얻을 수 있습니다. 위의 내용은 프로덕션 배포에 대한 모범 사례이며 자체 서명된 인증서를 DevKit 에이전트와 서비스에 사용할 수 있으며 완전히 체인된 인증서는 필요하지 않습니다. 또한 잘 알려진 키트로 작업할 때는 개발 중에 서버의 ddi를 검사할 필요가 없습니다. XToken에 대한 자세한 내용은 https://developer.microsoft.com/en-us/games/xbox/docs/gdk/live-security-token-nav을 참조하십시오.

DevKit Agent 구성

콘솔에 두 가지 구성 값을 설정합니다: 서버의 URI(DevkitAgentServiceUri) 및 신뢰 당사자(DevKitAgentRelyingParty) 이러한 값을 설정하려면 Microsoft Game Development Kit(GDK) 명령줄로 이동하고 대상 콘솔에 연결한 다음 다음 명령을 실행합니다.

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

Agent 시작 및 중지

Agent는 DevKitAgentServiceUri 구성 설정의 존재 여부에 따라 자동으로 시작 및 중지됩니다. 에이전트를 중지하려면 XBOX 명령 프롬프트에서 다음 명령을 실행하십시오

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

또는 에이전트 서버를 통해 동등한 wdConfig 명령을 보냅니다:

wdconfig DevKitAgentServiceUri=""

참고 항목

콘솔 명령줄 도구

​DevKit Agent

​자체 서비스 가져오기

​에이전트 하트비트 요청

​작업

​보안 및 인증

​DevKit Agent 구성

​Agent 시작 및 중지

​참고 항목

DevKit Agent

자체 서비스 가져오기

에이전트 하트비트 요청

작업

보안 및 인증

DevKit Agent 구성

Agent 시작 및 중지

참고 항목