xbl 명령 패밀리는 실험적 기능입니다. CLI 인터페이스는 피드백에 따라 변경되거나
제거될 수 있습니다.
xbox xbl은 XBOX 서비스 구성(작업 중인 구성과 게시된 구성의 상태, 구성 문서, 게시,
구성 스키마)과 도전 과제 이미지를 관리합니다. 구성 명령이 대상으로 하는 샌드박스를 나열하려면
xbox sandbox list를 사용하세요.
이 명령은 Partner Center에서 편집하는 것과 같은 구성으로 작동합니다. 각 XBOX 서비스 기능의
역할과 구성 방법은 XBOX 개발자 문서의
포털 구성 개요를
참조하세요.
공통 동작
판매자와 샌드박스
schema 명령을 제외한 모든 명령은 --seller-id를 사용합니다. 이 옵션이 없으면 명령은
XBOX_SELLER_ID 또는 xbox context set으로 저장한 판매자를 사용하고, 그다음에는
유일한 판매자를 사용합니다. 판매자가 여러 개라면 --seller-id를 전달하세요.
config status와 config publish는 --sandbox-id를 생략하면 XBOX_SANDBOX_ID 또는 저장된
sandbox-id에서 값을 가져옵니다. config download와 config save는 샌드박스 문서에 대해
명령줄에 --sandbox-id가 있어야 합니다.
타이틀 지정
config list, config status, config publish와 샌드박스 범위의 config download 및
config save는 --scid로 타이틀의 서비스 구성 식별자(SCID)를 받거나 --title-id로
XBOX 타이틀 ID를 받지만, 둘 다 받지는 않습니다. 둘 다 없으면 XBOX_TITLE_ID 또는
저장된 title-id를 사용합니다. 컨텍스트를 참조하세요. --scid는 둘 다 무시합니다.
--title-id는game get이 표시하는 것처럼 16진수이며,00000001부터7FFFFFFF까지이고0x접두사는 선택 사항입니다. 그 밖의 타이틀 ID에는 SCID를 전달하세요.- 다른 타이틀의 구성에 바인딩된 타이틀을 읽으면 기본 타이틀의 SCID를 사용합니다.
- 바인딩된 타이틀의 ID로 실행하는
config save와config publish는--validate-only를 사용하더라도 거부됩니다(bound_title_requires_scid). 오류에 기본 타이틀과 SCID가 표시되므로 해당--scid로 다시 실행하세요. - 다른 타이틀이 바인딩된 구성에
--title-id로 저장하거나 게시하면 해당 타이틀 모두의 구성이 변경됩니다. 터미널에서는 CLI가 바인딩된 타이틀을 나열하고 먼저 묻습니다. 터미널이 없으면 실패합니다.--allow-shared-configuration을 사용하면 질문을 건너뜁니다.--scid로 하는 쓰기는 묻지 않습니다. config save와config publish는 사용한 판매자와 SCID를 stderr에 씁니다. 읽기 명령은--verbose를 사용할 때 씁니다.
--title-id로 타이틀을 지정합니다.
출력
모든xbl 명령은 json(기본값) 및 json-compact와 함께 --output table도
허용합니다. 각 명령의 옵션 표에 해당 테이블 열이 나와 있습니다.
오류
실패한 요청은 1로 종료되며,status, title, detail과 서비스가 보낸 경우 code가 포함된
JSON 오류를 stderr에 씁니다. detail의 문구가 아니라 status 또는 code를 기준으로
분기하세요. 429 오류에는 retryAfterSeconds가 포함됩니다.
속도 제한을 참조하세요.
XBOX 서비스 유효성 검사에서 구성이 거부되면 오류의 validation 아래에 각 메시지가
나열됩니다.
--validate-only 없이 실행한 config save와 config publish는 실패한 변경이 적용되었을
수 있는지 알려 줍니다.
종료 코드 3이면 다시 제출하지 마세요. stderr에 확인용 읽기 전용 명령이 출력됩니다. 저장의
경우 저장한 파일과 비교할 수 있는
config download --view draft이고, 게시의 경우
config status입니다.
config
하나의 SCID에 대한 XBOX 서비스 구성을 검사, 다운로드, 저장 및 게시합니다. 샌드박스에는config save가 변경하는 작업 구성과, config publish가 작업 구성을 라이브로 만들면
플레이어와 테스트 계정에 표시되는 게시된 구성이 있습니다.
config list 및 config status
두 명령 모두 최신 작업 버전과 게시된 버전, 각 버전의 커밋 시간, 작업 버전에 게시되지 않은
변경 내용이 있는지 여부를 보고합니다. 게시된 커밋 시간은 게시가 완료된 시간이 아니라
게시된 버전의 커밋 시간입니다.
config list는 샌드박스마다 개체 하나가 있는 배열을 반환합니다. config status는 한
샌드박스에 대한 개체 하나를 반환하며, 마지막 게시를 lastPublish 아래에 추가하거나 보고할
게시가 없으면 null을 추가합니다. --sandbox-id ALL의 경우 ALL의 타이틀 전체 구성은
HIDDEN으로의 게시를 통해 라이브가 되므로 lastPublish는 항상 null입니다.
config list 옵션
config status 옵션
두 명령의 테이블에는
SANDBOX, WORKING, WORKING COMMIT, PUBLISHED,
PUBLISHED COMMIT, UNPUBLISHED 열이 있습니다. config status는 마지막 게시의
status인 PUBLISH STATUS를 추가합니다.
config list 및 config status 예제
config download 및 config save
XBOX 서비스 구성 문서 세트를 다운로드하고, 유효성을 검사하고, 저장합니다. 문서 세트는
샌드박스(기본값이며 SCID 또는 타이틀과 --sandbox-id가 필요함) 또는 계정(--type account이며
SCID, 타이틀, 샌드박스를 사용하지 않음)에 속합니다.
config download는 문서 세트의 ETag를 문서 옆에 <sandbox>.etag로 저장하며, 계정 범위의
경우 Account.etag로 저장합니다. Windows에서는 이 파일이 숨겨집니다. config save는
--file이 일치하는 첫 번째 파일 옆의 ETag 파일을 읽고, 저장 후 이 파일을 다시 씁니다.
다운로드한 이후 구성이 변경되었다면 저장이 실패합니다. 해당 변경 내용을 덮어쓰고 저장하려면
--force를 전달하고, ETag를 직접 제공하려면 --etag를 전달하세요.
config save는 저장하기 전에 묻지 않으며, --confirm은 이 명령에 적용되지 않습니다.
먼저 --validate-only로 실행하세요.
config download 옵션
config save 옵션
XBOX 서비스가 문서를 저장할 수 없는 경우(
--validate-only를 사용하면 CanCommit이 false,
그렇지 않으면 Committed가 false), 명령은 여전히 결과를 stdout에 쓰고, 각 유효성 검사
메시지를 stderr에 쓰고, ETag 파일을 변경하지 않은 채로 두고, 1로 종료합니다.
ValidationInfo가 FilesNotChangedCommit을 보고하며, 명령은 0으로 종료합니다.
config download 및 config save 예제
최신 초안 샌드박스 문서를 xbox-config에 다운로드합니다.
config publish
XBOX 서비스 구성의 작업 버전을 샌드박스의 게시된 구성에 게시합니다. 게시는 비동기적입니다.
config publish로 게시를 시작한 다음, lastPublish.status가 Success 또는 Failed가 될
때까지 대상 샌드박스에 대해 config status를 실행하세요.
원본 선택
--sandbox-id는 대상입니다. 원본은 원본 샌드박스의 작업 버전이며, 원본 샌드박스의
기본값은 대상입니다.
원본 샌드박스에 게시되지 않은 변경 내용이 있으면 최신 작업 버전은 그곳에서 라이브 상태인
버전이 아닙니다. 이 경우
--configset 없이 샌드박스 간 게시를 하면 경고가 표시되고,
라이브 상태인 버전이 표시됩니다.
--validate-only로 실행하고 제안된
--configset을 추가하세요. JSON 출력에서 SourceVersion은 사용된 작업 버전이고,
sourceHasUnpublishedChanges는 그 버전이 원본에서 라이브 상태인 버전과 다른지 여부를
나타내며, sourceLiveVersion은 라이브 상태인 버전을 찾은 경우 그 버전입니다.
타이틀 전체 게시인 --sandbox-id HIDDEN은 항상 ALL의 최신 작업 구성을 게시하므로
--source-sandbox-id나 --configset을 사용하지 않습니다. 어떤 버전이 라이브가 되는지
확인하려면 먼저 config status --sandbox-id ALL을 실행하고 workingVersion을 확인하세요.
확인
config publish는 다음 경우에 게시하기 전에 묻습니다.
터미널에서는 게시 내용을 설명하고 묻습니다. 터미널이 없으면 거부하고 1로 종료합니다.
--confirm(--yes, -y)은 질문을 건너뛰며, --validate-only는 절대 묻지 않습니다.
안전 및 파괴적 작업을 참조하세요.
RETAIL 게시에 대해 묻기 전에 게시의 유효성을 검사하고
게시로 추가되는 도전 과제를 나열합니다. 예라고
답하면 유효성을 검사한 작업 버전을 게시하므로, 나열된 내용이 그대로 라이브가 됩니다.
--title-id로 RETAIL 게시를 하려면
--allow-shared-configuration이 필요합니다. --confirm을 사용하면 목록이 표시되지 않으므로
먼저 --validate-only를 실행하여 확인하세요.
RETAIL 게시로 추가되는 도전 과제
도전 과제가 RETAIL에서 라이브가 되면 제거할 수 없고, 잠금 해제 규칙과 게이머 점수도 변경할 수 없습니다. 따라서 RETAIL 게시는 RETAIL에 아직 없는 도전 과제 중 추가되는 도전 과제 ID를 알려 줍니다.--validate-only를 사용하면 목록이 stderr로 출력되고, JSON 출력의achievementChanges.added에 포함됩니다.- 터미널에서
--validate-only없이 실행하면 확인에 나온 것처럼 질문 앞에 목록이 표시됩니다.
다시 게시
config publish는 변경 내용만 게시합니다. 대상의 마지막 성공한 게시 이후 변경된 내용이
없으면 게시가 시작되지 않으며, 결과의 Status는 AlreadyPublished입니다. 게시가 실패한
후에 config publish를 다시 실행하면 게시를 다시 시도합니다.
XBOX가 제품의 RETAIL을 잠그는 경우가 있으며, 이 경우 RETAIL에서 RETAIL로의 게시는
retail_locked로 실패합니다. 그래도 게시하려면 --republish를 추가하세요. 그러면 선택한
구성(기본적으로 RETAIL의 최신 작업 구성)을 RETAIL에 강제로 게시합니다. CERT 같은 다른
샌드박스에서 RETAIL로 게시해도 잠금이 해제되지만, RETAIL의 작업 문서가 해당 샌드박스의
문서로 대체됩니다.
--republish는 변경된 내용이 없어도 전체를 게시합니다. --validate-only와 함께 사용할 수
없습니다.
진단
엠바고 없이 처음 RETAIL에 게시할 때의 경고와 같은 XBOX 서비스의 유효성 검사 진단은 한 줄에 하나씩 stderr로 출력됩니다. JSON 출력은 이를ValidationResult에 보관합니다.
config publish는 1로 종료하고, 오류에 나온 것처럼
validation 아래에 각 메시지를 나열합니다.
샌드박스 간 게시는 글로벌 타이틀 스토리지 파일을 대체함
한 샌드박스에서 다른 샌드박스로 게시하면 대상의 글로벌 타이틀 스토리지 파일이 원본의
파일과 정확히 같아집니다. 대상에만 있는 파일은 삭제되며 복구할 수 없습니다.
복사는 게시가 실행될 때 원본에 있는 내용을 그대로 가져옵니다. 플레이어 자신의 데이터는
변경되지 않으며, 같은 샌드박스 내 게시는 글로벌 파일을 그대로 둡니다. 대상 파일을
유지하려면 게시 전에 원본 샌드박스에 해당 파일을 추가하세요.
모든 샌드박스 간 게시는
--validate-only를 사용하더라도 이 경고를 stderr에 쓰며,
확인 질문에도 포함합니다.
config publish 옵션
config publish 예제
게시하지 않고 SANDBOX1에 대한 게시의 유효성을 검사합니다.
SourceVersion을 --configset으로 전달하여, 유효성을 검사한 버전을
프롬프트 없이 게시합니다.
schema
XBOX 서비스 구성 문서 스키마를 검색하고 다운로드합니다.schema list 옵션
schema get 옵션
schema get은 JSON 개체 하나를 씁니다.
schema download 옵션
각 스키마는 유형을 소문자로 하여
<type>_<version>.xsd로 저장되며, 명령은 저장된 경로를
출력합니다. --dest -를 사용하면 대신 원시 XSD를 stdout에 쓰며, --output은 적용되지
않습니다.
schema 예제
일반적인 구성 왕복 작업
-
접근할 수 있는 샌드박스를 찾습니다.
-
작업 구성과 게시된 구성의 현재 상태를 확인합니다.
-
초안 문서 세트를 다운로드합니다. 이때
SANDBOX1.etag도 저장됩니다. -
xbox-config의 문서를 편집한 다음 유효성을 검사합니다. -
문서를 저장합니다.
-
SANDBOX1에 게시합니다.
-
게시를 확인하고, 상태가
Success또는Failed가 될 때까지 반복합니다.
