Player Data Reset 도구 (XblPlayerDataReset.exe) - XBOX Game Development Documentation

2026년 8월에 올바른 Partner Center 권한이 부여된 계정에서도 XUID로 플레이어 데이터를 재설정할 때 권한 오류(HTTP 401)가 발생하던 문제를 수정했습니다. 이 수정은 XBOX services 백 엔드에서 이루어졌으므로 자동으로 적용됩니다. GDK, XBOX services 도구 패키지 또는 도구 자체의 새 버전을 설치할 필요가 없습니다. 이전에 이 오류를 겪고 임시 방편으로 해결했거나 Partner Center 권한이 잘못 구성되었다는 안내를 받은 경우, 아래 단계에 따라 도구를 다시 시도할 수 있습니다. XUID로 재설정에 설명된 “Tools Access” 권한은 여전히 필요합니다.

Player Data Reset 도구는 테스트 샌드박스에서 플레이어 또는 플레이어 그룹의 데이터를 재설정하는 데 사용할 수 있습니다. 업적, 리더보드, 통계 및 타이틀 기록과 같은 데이터를 재설정할 수 있습니다. 개별 계정은 이메일 주소나 XUID로 재설정할 수 있습니다. XUID로 재설정하려면 먼저 XblDevAccount.exe 도구를 실행하여 재설정할 계정을 소유한 Partner Center 계정으로 로그인해야 합니다. 테스트 계정의 이메일 주소로 재설정하려면 테스트 계정의 암호를 알아야 합니다. 이 도구는 플레이어의 커넥티드 스토리지(게임 저장 데이터)는 재설정하지 않습니다. 커넥티드 스토리지를 관리하려면 Connected Storage 도구 (XblConnectedStorage.exe)를 참조하세요. 이 명령줄 도구는 GDK와 별도로 XBOX services 도구 패키지의 일부입니다. XblPlayerDataReset.exe 도구를 가져오는 방법을 알아보려면 XBOX services용 개발 도구를 참조하세요. --xuid, --user, --file 옵션은 상호 배타적입니다. --scid 및 --sandbox와 함께 이 중 정확히 하나만 지정하세요.

XUID로 재설정

Player Data Reset 도구를 사용하여 XUID로 사용자를 재설정하려면 (XblDevAccount.exe로) 로그인하는 데 사용된 개발자 계정이 특정 제품에 대한 적절한 권한을 가지고 있어야 합니다. “Tools Access”는 계정 수준 권한이 아니라 제품 수준 권한입니다. 따라서 플레이어 데이터를 재설정하려는 모든 제품에 대해 “Tools Access” 권한을 부여해야 합니다.

관리 권한이 있는 개발자 계정으로 Partner Center에 로그인합니다.
계정 설정 => 사용자 페이지로 이동합니다.
“Tools Access” 권한이 필요한 사용자 또는 그룹을 클릭합니다.
사용자 또는 그룹이 현재 표준 역할(예: Developer)에 할당되어 있는 경우 “Customize permissions”로 전환해야 합니다.
다음 페이지에서 “Product-level” 권한 테이블로 이동하여 “XBOX Live” 테이블 헤더를 확장하고 “Tools access” 열을 찾습니다.
“Tools Access” 권한을 부여하려는 제품 또는 제품 그룹에 대해 명시적으로 해당 상자를 선택합니다.

권한이 설정되면 다음과 같이 테스트 계정 데이터를 재설정할 수 있습니다.

XblPlayerDataReset.exe --scid <SCID> --sandbox <SNDBOX.0> --xuid <XUID1,XUID2,XUID3,...>

이메일 주소로 재설정

테스트 계정 이메일 주소로 재설정하려면 각 테스트 계정의 암호를 알아야 합니다. 아래 명령을 사용하면 테스트 사용자로 로그인할 수 있는 창이 팝업됩니다.

XblPlayerDataReset.exe --scid <SCID> --sandbox <SNDBOX.0> --user <XXXXXX-aaa@xboxtest.com,XXXXXX-bbb@xboxtest.com,...>

파일로 재설정

파일로 재설정하려면 XUID의 구분된 파일, 이메일의 구분된 파일 또는 Partner Center 계정 내보내기의 파일 위치를 전달할 수 있습니다.

XblPlayerDataReset.exe --scid <SCID> --sandbox <SNDBOX.0> --file </path/to/file>

구분된 파일의 경우 도구는 첫 번째 줄을 검사하여 파일을 읽는 방법을 결정합니다. 해당 줄에 @ 문자가 포함되어 있으면 파일 전체가 이메일 주소 목록으로 처리되고, 그렇지 않으면 XUID 목록으로 처리됩니다. 구분된 파일에는 헤더 행을 포함하지 마세요. 헤더 행도 계정으로 구문 분석됩니다. Partner Center 계정 내보내기는 자동으로 감지되지만, 원래 헤더 행이 수정 없이 그대로 있는 경우에만 감지됩니다.

Xuid,Email,Gamertag,IsDeleted,AccountId,Etag,Subscriptions,Keywords

스프레드시트 응용 프로그램에서 내보내기 파일을 열어 열 순서를 바꾸거나 열 이름을 변경한 뒤 저장하면 헤더가 더 이상 인식되지 않으며 파일은 일반 구분된 파일로 읽힙니다.

Partner Center 계정 내보내기에서 재설정하기 전에 XblDevAccount.exe로 로그인하세요. Partner Center 계정이 로그인되어 있으면 도구가 Xuid 열을 읽어 추가 확인 없이 계정을 재설정합니다. 로그인된 계정이 없으면 도구는 Email 열로 대체하고 파일에 있는 모든 계정의 암호를 입력하라는 메시지를 표시합니다.

구분 기호 옵션

--xuid 및 --user 옵션과 --file에 전달되는 구분된 파일에 대해 사용자 지정 구분 기호를 선택적으로 설정할 수 있습니다. 기본 구분 기호는 쉼표(,)입니다.

XblPlayerDataReset.exe --scid <SCID> --sandbox <SNDBOX.0> --xuid <XUID1*XUID2*XUID3*...> --delimiter *
XblPlayerDataReset.exe --scid <SCID> --sandbox <SNDBOX.0> --user <XXXXXX-aaa@xboxtest.com$XXXXXX-bbb@xboxtest.com$...> --delimiter $
XblPlayerDataReset.exe --scid <SCID> --sandbox <SNDBOX.0> --file </path/to/file> --delimiter %

값의 첫 번째 문자만 사용됩니다. 두 문자 이상의 값을 전달하면 나머지 문자는 여러 문자 구분 기호로 처리되지 않고 무시됩니다. --file에 전달된 파일이 Partner Center 계정 내보내기인 경우 해당 형식은 항상 쉼표로 구분되므로 구분 기호가 무시됩니다.

계정 처리 방식

계정이 처리되는 방식은 사용하는 옵션에 따라 다릅니다. XUID로 재설정하거나 XUID로 확인되는 파일에서 재설정하는 경우, 계정은 최대 10개씩 일괄 처리됩니다. 일괄 처리 내의 계정은 병렬로 재설정되고, 각 일괄 처리는 순차적으로 실행됩니다. 이메일 주소로 재설정하는 경우 각 계정에 개별적으로 로그인해야 하므로 계정이 한 번에 하나씩 처리됩니다. 테스트 계정 중 하나라도 로그인에 실패하면 도구가 즉시 중지되며 목록의 나머지 계정은 시도되지 않습니다. 각 계정은 실패로 보고되기 전에 최대 5회까지 자동으로 다시 시도되며, 도구는 다음으로 넘어가기 전에 서비스가 각 재설정을 완료할 때까지 기다립니다. 따라서 단일 계정이 최종 결과를 보고하는 데 최대 약 1분이 걸릴 수 있습니다. 특히 큰 목록을 재설정할 때는 도구를 취소하지 말고 완료될 때까지 기다리세요.

출력

명령이 성공하거나 실패하면 아래에 나열된 것과 유사한 출력이 표시됩니다. 성공

Resetting player data for SCID <SCID> in sandbox <SNDBOX.0>
Using Dev account contoso@contoso.com from WindowsDevCenter
Processing batch of 2 account(s).
Resetting player 2814000000000001 result: Succeeded
Resetting player 2814000000000002 result: Succeeded
Player data has been reset successfully.

오류

Resetting player data for SCID <SCID> in sandbox <SNDBOX.0>
Using Dev account contoso@contoso.com from WindowsDevCenter
Processing batch of 1 account(s).
Resetting player 2814000000000001 result: CompletedError. Will retry.
Retrying 1 accounts. 4 more attempt(s).
Failed to reset 1 account(s): 2814000000000001
An error occurred while resetting player data:

재설정은 시간 초과될 수도 있습니다. 시간 초과는 도구가 결과 대기를 중지했다는 의미이며, 재설정이 확실히 실패했다는 의미는 아닙니다. 작업은 서비스에서 계속 완료될 수 있습니다.

Player data reset has timed out:

종료 코드

도구는 성공하면 0을, 실패하면 -1을 반환합니다. 스크립트 또는 자동화된 테스트 단계에서 도구를 호출할 때는 콘솔 텍스트에 의존하지 말고 종료 코드를 확인하세요.

도구는 아무것도 재설정되지 않는 두 가지 경우에도 0을 반환합니다. --xuid, --user, --file 중 어느 것도 지정되지 않은 경우와 --file에 전달된 파일을 읽을 수 없는 경우입니다. 자동화가 종료 코드만 확인하는 경우 이러한 경우가 성공적인 실행처럼 보일 수 있습니다. 재설정하려던 모든 계정에 대한 결과 줄이 출력에 포함되어 있는지 확인하세요.

문제 해결

Unable to authorize the account with XBOX Live

Unable to authorize the account with XBOX Live and scid : <SCID> and sandbox : <SNDBOX.0>, please contact your administrator.

이 메시지는 HTTP 401 오류와 함께 표시됩니다. 2026년 8월 이전에는 서비스 측 문제로 인해 Partner Center 권한이 올바르게 구성된 개발자를 포함하여 XUID로 재설정하는 모든 개발자에게 이 오류가 발생했습니다. 이 문제는 수정되었으며, 이 수정에는 도구 또는 GDK 업데이트가 필요하지 않았습니다. 이 오류가 여전히 표시되는 경우 XUID로 재설정에 설명된 대로 로그인된 계정에 해당 제품에 대한 “Tools Access” 권한이 있는지, 그리고 SCID와 샌드박스가 대상 제품과 일치하는지 확인하세요. 최근 Partner Center에서 권한을 변경한 경우 새 토큰이 발급되도록 XblDevAccount.exe로 로그아웃했다가 다시 로그인하세요.

Your account doesn’t have access to perform the operation

Your account doesn't have access to perform the operation, please contact your administrator.

이 메시지는 HTTP 403 오류와 함께 표시됩니다. XUID로 재설정에 설명된 대로 해당 제품에 대한 “Tools Access” 권한을 부여하세요.

Resetting by XUID requires a signed in Partner Center account

Resetting by XUID requires a signed in Partner Center account. Please use "XblDevAccount.exe signin" to log in.

XUID로 재설정하기 전이나 Partner Center 계정 내보내기에서 재설정하기 전에 XblDevAccount.exe signin을 실행하세요.

Failed to log in to test account

Failed to log in to test account <XXXXXX-aaa@xboxtest.com>.

도구가 테스트 계정에 로그인할 수 없습니다. 이메일 주소와 암호를 확인하고 해당 계정이 --sandbox에 전달한 샌드박스에 속하는지 확인하세요. 이 문제가 발생하면 도구가 중지되므로 목록의 나머지 계정은 재설정되지 않습니다.

​XUID로 재설정

​이메일 주소로 재설정

​파일로 재설정

​구분 기호 옵션

​계정 처리 방식

​출력

​종료 코드

​문제 해결

​Unable to authorize the account with XBOX Live

​Your account doesn’t have access to perform the operation

​Resetting by XUID requires a signed in Partner Center account

​Failed to log in to test account

XUID로 재설정

이메일 주소로 재설정

파일로 재설정

구분 기호 옵션

계정 처리 방식

출력

종료 코드

문제 해결

Unable to authorize the account with XBOX Live

Your account doesn’t have access to perform the operation

Resetting by XUID requires a signed in Partner Center account

Failed to log in to test account