> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# XBOX 서비스 구성

> 상태, 문서, 게시, 스키마, 도전 과제 이미지를 포함한 XBOX 서비스 구성을 관리합니다.

`xbl` 명령 패밀리는 실험적 기능입니다. CLI 인터페이스는 피드백에 따라 변경되거나
제거될 수 있습니다.

`xbox xbl`은 XBOX 서비스 구성(작업 중인 구성과 게시된 구성의 상태, 구성 문서, 게시,
구성 스키마)과 도전 과제 이미지를 관리합니다. 구성 명령이 대상으로 하는 샌드박스를 나열하려면
[`xbox sandbox list`](https://docs.xbox.com/ko/tools/xbox-cli/commands/sandbox)를 사용하세요.

이 명령은 Partner Center에서 편집하는 것과 같은 구성으로 작동합니다. 각 XBOX 서비스 기능의
역할과 구성 방법은 XBOX 개발자 문서의
[포털 구성 개요](https://devdocs.xbox.com/services/xbox-services/fundamentals/portal-config/live-portal-config-overview)를
참조하세요.

| 그룹 | 명령 | 용도 |
| - | - | - |
| `config` | `list`, `status`, `download`, `save`, `publish` | 작업 중인 구성과 게시된 구성의 상태를 검사하고, 구성 문서를 다운로드 및 저장하며, 샌드박스에 구성을 게시합니다. |
| `schema` | `list`, `get`, `download` | 구성 스키마 유형과 버전을 나열하거나, 한 버전을 가져오거나, XSD를 다운로드합니다. |
| [`achievement-image`](https://docs.xbox.com/ko/tools/xbox-cli/commands/xbl/achievement-image) | `upload`, `get`, `list`, `download` | 도전 과제 이미지를 등록, 검사 또는 다운로드합니다. |

## 공통 동작

### 판매자와 샌드박스

`schema` 명령을 제외한 모든 명령은 `--seller-id`를 사용합니다. 이 옵션이 없으면 명령은
`XBOX_SELLER_ID` 또는 [`xbox context set`](https://docs.xbox.com/ko/tools/xbox-cli/commands/context)으로 저장한 판매자를 사용하고, 그다음에는
유일한 판매자를 사용합니다. 판매자가 여러 개라면 `--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`를 사용합니다. [컨텍스트](https://docs.xbox.com/ko/tools/xbox-cli/commands/context.md)를 참조하세요. `--scid`는 둘 다 무시합니다.

* `--title-id`는 [`game get`](https://docs.xbox.com/ko/tools/xbox-cli/commands/game)이 표시하는 것처럼 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`를 사용할 때 씁니다.

다음 명령은 타이틀 ID를 저장한 다음 이를 사용하여 XDKS.1에서 해당 타이틀의 구성을 읽고,
다운로드하고, 유효성을 검사합니다. 마지막 명령은 대신 `--title-id`로 타이틀을 지정합니다.

```powershell theme={null}
xbox context set title-id 1234ABCD
xbox xbl config list --output table
xbox xbl config status --sandbox-id XDKS.1
xbox xbl config download --sandbox-id XDKS.1 --view draft --dest .\xbox-config
xbox xbl config save --sandbox-id XDKS.1 --file ".\xbox-config\*.xml" --validate-only
xbox xbl config status --title-id 1234ABCD --sandbox-id XDKS.1
```

### 출력

모든 `xbl` 명령은 `json`(기본값) 및 `json-compact`와 함께 `--output table`도
허용합니다. 각 명령의 옵션 표에 해당 테이블 열이 나와 있습니다.

### 오류

실패한 요청은 1로 종료되며, `status`, `title`, `detail`과 서비스가 보낸 경우 `code`가 포함된
JSON 오류를 stderr에 씁니다. `detail`의 문구가 아니라 `status` 또는 `code`를 기준으로
분기하세요. 429 오류에는 `retryAfterSeconds`가 포함됩니다.
[속도 제한](https://docs.xbox.com/ko/tools/xbox-cli/cli-for-agents.md#rate-limits)을 참조하세요.

XBOX 서비스 유효성 검사에서 구성이 거부되면 오류의 `validation` 아래에 각 메시지가
나열됩니다.

```json theme={null}
{
  "status": 409,
  "title": "Validation failed.",
  "detail": "The configuration failed XBOX services validation. See validation for each message. MS-CV: ...",
  "code": "validation_failed",
  "validation": [
    {
      "severity": "Error",
      "documentName": "achievements2017.xml",
      "message": "XblLimited products do not support achievements or stats2013/stats2015 configuration. Please remove the unsupported configuration. Document failing validation: achievements2017.xml."
    }
  ]
}
```

`--validate-only` 없이 실행한 `config save`와 `config publish`는 실패한 변경이 적용되었을
수 있는지 알려 줍니다.

| 종료 코드 | 의미 |
| - | - |
| 1 | 아무것도 변경되지 않았습니다. 요청이 전송되기 전에 중지되거나 실패했거나, `408` 이외의 `4xx`로 거부되었습니다. |
| 3 | 결과를 알 수 없습니다. 요청이 전송된 후 Ctrl+C, 시간 초과 또는 연결 끊김이 발생했거나, 그 밖의 오류 상태 또는 CLI가 읽을 수 없는 성공 응답을 받았습니다. |

종료 코드 3이면 다시 제출하지 마세요. stderr에 확인용 읽기 전용 명령이 출력됩니다. 저장의
경우 저장한 파일과 비교할 수 있는 `config download --view draft`이고, 게시의 경우
`config status`입니다.

***

## config

하나의 SCID에 대한 XBOX 서비스 구성을 검사, 다운로드, 저장 및 게시합니다. 샌드박스에는
`config save`가 변경하는 작업 구성과, `config publish`가 작업 구성을 라이브로 만들면
플레이어와 테스트 계정에 표시되는 게시된 구성이 있습니다.

| 명령 | 설명 |
| - | - |
| `config list` | 액세스 가능한 모든 샌드박스의 작업 상태와 게시 상태를 나열합니다. |
| `config status` | 한 샌드박스의 작업 상태와 게시 상태, 그리고 마지막 게시를 가져옵니다. |
| `config download` | 문서 세트를 다운로드하고 추출합니다. |
| `config save` | 작업 문서 세트의 유효성을 검사하거나 저장합니다. |
| `config publish` | 하나의 구성 세트의 유효성을 검사하거나 게시를 시작합니다. |

### `config list` 및 `config status`

두 명령 모두 최신 작업 버전과 게시된 버전, 각 버전의 커밋 시간, 작업 버전에 게시되지 않은
변경 내용이 있는지 여부를 보고합니다. 게시된 커밋 시간은 게시가 완료된 시간이 아니라
게시된 버전의 커밋 시간입니다.

`config list`는 샌드박스마다 개체 하나가 있는 배열을 반환합니다. `config status`는 한
샌드박스에 대한 개체 하나를 반환하며, 마지막 게시를 `lastPublish` 아래에 추가하거나 보고할
게시가 없으면 `null`을 추가합니다. `--sandbox-id ALL`의 경우 `ALL`의 타이틀 전체 구성은
`HIDDEN`으로의 게시를 통해 라이브가 되므로 `lastPublish`는 항상 `null`입니다.

| `lastPublish` 필드 | 설명 |
| - | - |
| `status` | `Running`, `Success` 또는 `Failed`. 서비스가 보고하지 않으면 `null`입니다. |
| `jobId` | 게시 작업의 ID입니다. |
| `message` | 게시에 대한 서비스의 메시지 또는 `null`입니다. |

```json theme={null}
{
  "sandbox": "SANDBOX1",
  "hasWorkingConfiguration": true,
  "workingVersion": 9,
  "workingCommitTime": "2026-10-29T21:40:12+00:00",
  "hasPublishedConfiguration": true,
  "publishedVersion": 9,
  "publishedCommitTime": "2026-10-29T21:40:12+00:00",
  "hasUnpublishedChanges": false,
  "lastPublish": {
    "status": "Success",
    "jobId": "11111111-2222-3333-4444-555555555555",
    "message": null
  }
}
```

#### `config list` 옵션

| 옵션 | 필수 | 설명 |
| - | - | - |
| `--scid <guid>` | 또는 타이틀 | 타이틀 구성의 SCID입니다. |
| `--title-id <hex-id>` | 또는 SCID | XBOX 타이틀 ID입니다. [타이틀 지정](#title-targeting)을 참조하세요. |
| `--seller-id <id>` | 아니요 | Partner Center 판매자 ID입니다. |
| `--output <format>` | 아니요 | `json`(기본값), `json-compact` 또는 `table`. |

#### `config status` 옵션

| 옵션 | 필수 | 설명 |
| - | - | - |
| `--scid <guid>` | 또는 타이틀 | 타이틀 구성의 SCID입니다. |
| `--title-id <hex-id>` | 또는 SCID | XBOX 타이틀 ID입니다. [타이틀 지정](#title-targeting)을 참조하세요. |
| `--sandbox-id <id>` | 예 | 대/소문자를 구분하는 샌드박스 ID입니다. 기본값은 `XBOX_SANDBOX_ID`이며, 그다음은 저장된 샌드박스 ID입니다. |
| `--seller-id <id>` | 아니요 | Partner Center 판매자 ID입니다. |
| `--output <format>` | 아니요 | `json`(기본값), `json-compact` 또는 `table`. |

두 명령의 테이블에는 `SANDBOX`, `WORKING`, `WORKING COMMIT`, `PUBLISHED`,
`PUBLISHED COMMIT`, `UNPUBLISHED` 열이 있습니다. `config status`는 마지막 게시의
`status`인 `PUBLISH STATUS`를 추가합니다.

#### `config list` 및 `config status` 예제

```bash theme={null}
# Every accessible sandbox for one title
xbox xbl config list \
  --scid aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee --output table

# One sandbox, single JSON object
xbox xbl config status \
  --scid aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee --sandbox-id SANDBOX1

# Compact output for scripting
xbox xbl config status \
  --scid aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee --sandbox-id SANDBOX1 --output json-compact
```

### `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` 옵션

| 옵션 | 필수 | 설명 |
| - | - | - |
| `--view <draft\|published>` | 예 | `config save`가 변경하는 작업 구성인 `draft` 또는 플레이어와 테스트 계정에 표시되는 라이브 구성인 `published`. Partner Center도 같은 두 이름을 사용합니다. |
| `--dest <directory>` | 예 | 문서와 ETag 파일을 저장할 디렉터리입니다. |
| `--type <sandbox\|account>` | 아니요 | 문서 범위입니다. 기본값은 `sandbox`입니다. |
| `--scid <guid>` | `sandbox`의 경우 또는 타이틀 | 타이틀 구성의 SCID입니다. |
| `--title-id <hex-id>` | `sandbox`의 경우 또는 SCID | XBOX 타이틀 ID입니다. [타이틀 지정](#title-targeting)을 참조하세요. |
| `--sandbox-id <id>` | `sandbox`의 경우 | 대/소문자를 구분하는 샌드박스 ID입니다. |
| `--version <number>` | 아니요 | 양수인 과거 문서 세트 버전입니다. 기본값은 최신 버전입니다. |
| `--document <filename>` | 아니요 | 다운로드할 문서 파일 이름입니다. 더 추가하려면 반복합니다. 기본값은 모든 문서입니다. |
| `--seller-id <id>` | 아니요 | Partner Center 판매자 ID입니다. |
| `--output <format>` | 아니요 | `json`(기본값), `json-compact` 또는 `TYPE`, `SANDBOX`, `VIEW`, `VERSION`, `FILES`, `DESTINATION` 열이 있는 `table`. |

#### `config save` 옵션

| 옵션 | 필수 | 설명 |
| - | - | - |
| `--file <path-or-glob>` | 예 | 로컬 파일 또는 따옴표로 묶은 파일 이름 glob입니다. 더 추가하려면 `--file`을 반복하며, 각각 하나의 경로나 패턴을 지정합니다(`--file a.xml --file b.xml`). 각 파일의 이름이 문서 이름이 됩니다. 일치하는 파일이 없는 값이 있으면 명령이 실패합니다. |
| `--type <sandbox\|account>` | 아니요 | 문서 범위입니다. 기본값은 `sandbox`입니다. |
| `--scid <guid>` | `sandbox`의 경우 또는 타이틀 | 타이틀 구성의 SCID입니다. |
| `--title-id <hex-id>` | `sandbox`의 경우 또는 SCID | XBOX 타이틀 ID입니다. [타이틀 지정](#title-targeting)을 참조하세요. |
| `--sandbox-id <id>` | `sandbox`의 경우 | 대/소문자를 구분하는 샌드박스 ID입니다. |
| `--validate-only` | 아니요 | 저장하지 않고 유효성만 검사합니다. |
| `--allow-shared-configuration` | 아니요 | 다른 타이틀이 바인딩된 구성에 묻지 않고 `--title-id`로 저장합니다. [타이틀 지정](#title-targeting)을 참조하세요. |
| `--etag <value>` | 아니요 | 저장 기준으로 사용할 ETag입니다. 기본값은 저장된 ETag 파일입니다. |
| `--force` | 아니요 | 저장된 ETag 이후의 변경 내용을 덮어쓰고 저장합니다. |
| `--message <text>` | 아니요 | 저장 메시지입니다. |
| `--seller-id <id>` | 아니요 | Partner Center 판매자 ID입니다. |
| `--output <format>` | 아니요 | `json`(기본값), `json-compact` 또는 `TYPE`, `SANDBOX`, `VALIDATE ONLY`, `CAN COMMIT`, `COMMITTED`, `FILES`, `ETAG FILE` 열이 있는 `table`. |

XBOX 서비스가 문서를 저장할 수 없는 경우(`--validate-only`를 사용하면 `CanCommit`이 false,
그렇지 않으면 `Committed`가 false), 명령은 여전히 결과를 stdout에 쓰고, 각 유효성 검사
메시지를 stderr에 쓰고, ETag 파일을 변경하지 않은 채로 두고, 1로 종료합니다.

```text theme={null}
XBOX services can't save these documents:
Error: achievements2017.xml: The root namespace doesn't match the document type. (NamespaceDocTypeMismatch)
```

최신 작업 문서와 일치하는 문서는 실패가 아닙니다. 아무것도 저장되지 않고,
`ValidationInfo`가 `FilesNotChangedCommit`을 보고하며, 명령은 0으로 종료합니다.

#### `config download` 및 `config save` 예제

최신 초안 샌드박스 문서를 `xbox-config`에 다운로드합니다.

```bash theme={null}
xbox xbl config download \
  --scid aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee --sandbox-id SANDBOX1 --view draft --dest xbox-config
```

문서를 편집한 후 모든 문서 또는 변경한 두 문서만 유효성을 검사합니다.

```bash theme={null}
xbox xbl config save \
  --scid aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee --sandbox-id SANDBOX1 \
  --file "xbox-config/*.xml" --validate-only

xbox xbl config save \
  --scid aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee --sandbox-id SANDBOX1 \
  --file xbox-config/achievements2017.xml --file xbox-config/localization.xml --validate-only
```

메시지와 함께 저장합니다.

```bash theme={null}
xbox xbl config save \
  --scid aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee --sandbox-id SANDBOX1 \
  --file "xbox-config/*.xml" --message "Update achievements"
```

게시된 버전 7 당시의 문서 하나를 다운로드합니다.

```bash theme={null}
xbox xbl config download \
  --scid aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee --sandbox-id SANDBOX1 \
  --view published --version 7 --document achievements.xml --dest xbox-config
```

계정의 초안 문서를 다운로드합니다.

```bash theme={null}
xbox xbl config download --type account --view draft --dest xbox-config --output table
```

### `config publish`

XBOX 서비스 구성의 작업 버전을 샌드박스의 게시된 구성에 게시합니다. 게시는 비동기적입니다.
`config publish`로 게시를 시작한 다음, `lastPublish.status`가 `Success` 또는 `Failed`가 될
때까지 대상 샌드박스에 대해 [`config status`](#config-list-and-config-status)를 실행하세요.

#### 원본 선택

`--sandbox-id`는 대상입니다. 원본은 원본 샌드박스의 작업 버전이며, 원본 샌드박스의
기본값은 대상입니다.

| 시나리오 | 효과 |
| - | - |
| `--source-sandbox-id`를 생략했거나 `--sandbox-id`와 같음 | 샌드박스의 최신 작업 버전을 게시합니다. |
| `--source-sandbox-id`가 `--sandbox-id`와 다름 | 원본 샌드박스의 최신 작업 버전을 대상에 게시하고, [대상의 글로벌 타이틀 스토리지 파일을 대체합니다](#cross-sandbox-publishing-replaces-global-title-storage-files). |
| `--configset <number>` | 원본 샌드박스의 해당 작업 버전을 게시합니다. |

원본 샌드박스에 게시되지 않은 변경 내용이 있으면 최신 작업 버전은 그곳에서 라이브 상태인
버전이 아닙니다. 이 경우 `--configset` 없이 샌드박스 간 게시를 하면 경고가 표시되고,
라이브 상태인 버전이 표시됩니다.

```text theme={null}
Warning: XDKS.1 has unpublished changes. This publish uses its latest working version, 53; what's live in XDKS.1 is working version 52. To publish that instead, add --configset 52.
```

원본에서 라이브 상태인 버전을 정확히 승격하려면 먼저 `--validate-only`로 실행하고 제안된
`--configset`을 추가하세요. JSON 출력에서 `SourceVersion`은 사용된 작업 버전이고,
`sourceHasUnpublishedChanges`는 그 버전이 원본에서 라이브 상태인 버전과 다른지 여부를
나타내며, `sourceLiveVersion`은 라이브 상태인 버전을 찾은 경우 그 버전입니다.

타이틀 전체 게시인 `--sandbox-id HIDDEN`은 항상 `ALL`의 최신 작업 구성을 게시하므로
`--source-sandbox-id`나 `--configset`을 사용하지 않습니다. 어떤 버전이 라이브가 되는지
확인하려면 먼저 `config status --sandbox-id ALL`을 실행하고 `workingVersion`을 확인하세요.

#### 확인

`config publish`는 다음 경우에 게시하기 전에 묻습니다.

| 게시 | 묻는 이유 |
| - | - |
| `--sandbox-id RETAIL` | 게시가 완료되면 플레이어에게 변경 내용이 표시됩니다. |
| `--sandbox-id CERT` 또는 `CERT.DEBUG` | 이 샌드박스에서 XBOX 인증 테스트가 진행됩니다. |
| `--sandbox-id HIDDEN` | RETAIL을 포함한 모든 샌드박스가 사용하는 타이틀 전체 구성을 게시합니다. |
| `--source-sandbox-id`가 `--sandbox-id`와 다름 | 먼저 이름이 같은 대상의 작업 문서와 대상의 [글로벌 타이틀 스토리지 파일](#cross-sandbox-publishing-replaces-global-title-storage-files)을 대체합니다. |

터미널에서는 게시 내용을 설명하고 묻습니다. 터미널이 없으면 거부하고 1로 종료합니다.
`--confirm`(`--yes`, `-y`)은 질문을 건너뛰며, `--validate-only`는 절대 묻지 않습니다.
[안전 및 파괴적 작업](https://docs.xbox.com/ko/tools/xbox-cli/safety.md)을 참조하세요.

RETAIL 게시에 대해 묻기 전에 게시의 유효성을 검사하고
[게시로 추가되는 도전 과제](#achievements-a-retail-publish-adds)를 나열합니다. 예라고
답하면 유효성을 검사한 작업 버전을 게시하므로, 나열된 내용이 그대로 라이브가 됩니다.

```console theme={null}
$ xbox xbl config publish --scid aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee --source-sandbox-id CERT --sandbox-id RETAIL
This publish adds 2 achievements to RETAIL: 1, 2. Once they're live in RETAIL, achievements can't be removed, and their unlock rules and gamerscore can't change.
This publishes working version 52 of CERT's configuration to RETAIL for SCID aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee.
RETAIL is live: players see the change when the publish finishes.
Publishing from CERT first replaces RETAIL's working documents that have the same names.
Warning: publishing from CERT to RETAIL replaces RETAIL's global title storage files with CERT's. Files with the same path are overwritten, files only CERT holds are added, and files only RETAIL holds are deleted. Deleted files can't be recovered.

Publish to RETAIL? [y/N]:
```

이 유효성 검사가 실패하면 아무것도 게시하지 않고 묻지도 않습니다. 따라서 터미널에서 다른
타이틀이 바인딩된 구성에 `--title-id`로 RETAIL 게시를 하려면
`--allow-shared-configuration`이 필요합니다. `--confirm`을 사용하면 목록이 표시되지 않으므로
먼저 `--validate-only`를 실행하여 확인하세요.

#### RETAIL 게시로 추가되는 도전 과제

도전 과제가 RETAIL에서 라이브가 되면 제거할 수 없고, 잠금 해제 규칙과 게이머 점수도
변경할 수 없습니다. 따라서 RETAIL 게시는 RETAIL에 아직 없는 도전 과제 중 추가되는 도전 과제 ID를
알려 줍니다.

* `--validate-only`를 사용하면 목록이 stderr로 출력되고, JSON 출력의
  `achievementChanges.added`에 포함됩니다.
* 터미널에서 `--validate-only` 없이 실행하면 [확인](#confirmation)에 나온 것처럼 질문
  앞에 목록이 표시됩니다.

```console theme={null}
$ xbox xbl config publish --scid aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee --source-sandbox-id CERT --sandbox-id RETAIL --validate-only
This publish would add 2 achievements to RETAIL: 1, 2. Once they're live in RETAIL, achievements can't be removed, and their unlock rules and gamerscore can't change.
```

도전 과제를 추가하지 않는 게시는 그렇다고 알려 줍니다. 다른 샌드박스에서는 도전 과제를
나열하지 않습니다.

#### 다시 게시

`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`에 보관합니다.

```text theme={null}
XBOX services warning (FirstRetailPublishWithoutEffectiveEmbargo): This is the first time these Xbox Gameplay Settings will be published to RETAIL, and no embargo is configured.
```

유효성 검사가 실패하면 `config publish`는 1로 종료하고, [오류](#errors)에 나온 것처럼
`validation` 아래에 각 메시지를 나열합니다.

#### 샌드박스 간 게시는 글로벌 타이틀 스토리지 파일을 대체함

> [!CAUTION]
>
> 한 샌드박스에서 다른 샌드박스로 게시하면 대상의 글로벌 타이틀 스토리지 파일이 원본의
> 파일과 정확히 같아집니다. 대상에만 있는 파일은 삭제되며 복구할 수 없습니다.

글로벌 파일은 뉴스 피드와 맵처럼 게임의 모든 플레이어가 읽는 파일입니다.

| 파일 | 원본 | 게시 전 대상 | 게시 후 대상 |
| - | - | - | - |
| `news.json` | 있음 | 있음 | 원본의 사본으로 덮어씀 |
| `tuning.cfg` | 있음 | — | 추가됨 |
| `maps.bin` | — | 있음 | **삭제됨** |

복사는 게시가 실행될 때 원본에 있는 내용을 그대로 가져옵니다. 플레이어 자신의 데이터는
변경되지 않으며, 같은 샌드박스 내 게시는 글로벌 파일을 그대로 둡니다. 대상 파일을
유지하려면 게시 전에 원본 샌드박스에 해당 파일을 추가하세요.

모든 샌드박스 간 게시는 `--validate-only`를 사용하더라도 이 경고를 stderr에 쓰며,
[확인](#confirmation) 질문에도 포함합니다.

```text theme={null}
Warning: publishing from SANDBOX1 to SANDBOX2 replaces SANDBOX2's global title storage files with SANDBOX1's. Files with the same path are overwritten, files only SANDBOX1 holds are added, and files only SANDBOX2 holds are deleted. Deleted files can't be recovered.
```

#### `config publish` 옵션

| 옵션 | 별칭 | 필수 | 설명 |
| - | - | - | - |
| `--scid <guid>` | — | 또는 타이틀 | 타이틀 구성의 SCID입니다. |
| `--title-id <hex-id>` | — | 또는 SCID | XBOX 타이틀 ID입니다. [타이틀 지정](#title-targeting)을 참조하세요. |
| `--sandbox-id <id>` | — | 예 | 대상 샌드박스 ID입니다. 기본값은 `XBOX_SANDBOX_ID`이며, 그다음은 저장된 샌드박스 ID입니다. |
| `--source-sandbox-id <id>` | — | 아니요 | 원본 샌드박스 ID입니다. 기본값은 `--sandbox-id`입니다. `--sandbox-id HIDDEN`과 함께 사용할 수 없습니다. |
| `--validate-only` | — | 아니요 | 게시하지 않고 유효성만 검사합니다. RETAIL의 경우 [게시로 추가되는 도전 과제](#achievements-a-retail-publish-adds)도 나열합니다. |
| `--allow-shared-configuration` | — | 아니요 | 다른 타이틀이 바인딩된 구성에 묻지 않고 `--title-id`로 게시합니다. [타이틀 지정](#title-targeting)을 참조하세요. |
| `--configset <number>` | — | 아니요 | 원본 샌드박스의 양수 작업 버전입니다. 기본값은 최신 버전입니다. `--sandbox-id HIDDEN`과 함께 사용할 수 없습니다. |
| `--republish` | — | 아니요 | 변경된 내용이 없거나 마이그레이션 후 RETAIL이 잠긴 경우에도 전체를 게시합니다. [다시 게시](#republishing)를 참조하세요. |
| `--confirm` | `--yes`, `-y` | 아니요 | 묻지 않고 게시합니다. [확인](#confirmation)을 참조하세요. |
| `--seller-id <id>` | — | 아니요 | Partner Center 판매자 ID입니다. |
| `--output <format>` | `-o` | 아니요 | `json`(기본값), `json-compact` 또는 `STATUS`, `SOURCE`, `DESTINATION`, `VALIDATE ONLY`, `SOURCE VERSION` 열이 있는 `table`. |

#### `config publish` 예제

게시하지 않고 SANDBOX1에 대한 게시의 유효성을 검사합니다.

```bash theme={null}
xbox xbl config publish \
  --scid aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee --sandbox-id SANDBOX1 --validate-only
```

SANDBOX1의 최신 작업 구성을 게시하여 SANDBOX1에서 라이브가 되게 합니다.

```bash theme={null}
xbox xbl config publish \
  --scid aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee --sandbox-id SANDBOX1
```

SANDBOX1의 최신 작업 버전을 SANDBOX2에 게시합니다. 이 작업은 SANDBOX2의 글로벌 타이틀
스토리지 파일도 SANDBOX1의 파일로 대체합니다.

```bash theme={null}
xbox xbl config publish \
  --scid aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee --source-sandbox-id SANDBOX1 --sandbox-id SANDBOX2
```

SANDBOX1의 작업 버전 42를 SANDBOX2에 게시합니다.

```bash theme={null}
xbox xbl config publish \
  --scid aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee \
  --source-sandbox-id SANDBOX1 --sandbox-id SANDBOX2 --configset 42
```

CERT에서 RETAIL로의 게시 유효성을 검사합니다. 이때 추가되는 도전 과제가 나열됩니다.

```bash theme={null}
xbox xbl config publish \
  --scid aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee --source-sandbox-id CERT --sandbox-id RETAIL --validate-only
```

그런 다음 출력의 `SourceVersion`을 `--configset`으로 전달하여, 유효성을 검사한 버전을
프롬프트 없이 게시합니다.

```bash theme={null}
xbox xbl config publish \
  --scid aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee --source-sandbox-id CERT --sandbox-id RETAIL --configset 52 --confirm
```

변경된 내용이 없어도 SANDBOX1을 다시 게시합니다.

```bash theme={null}
xbox xbl config publish \
  --scid aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee --sandbox-id SANDBOX1 --republish
```

SANDBOX2에 대한 게시를 확인합니다.

```bash theme={null}
xbox xbl config status \
  --scid aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee --sandbox-id SANDBOX2 --output table
```

***

## schema

XBOX 서비스 구성 문서 스키마를 검색하고 다운로드합니다.

| 명령 | 설명 |
| - | - |
| `schema list` | 모든 스키마 유형을 나열합니다. |
| `schema list --type <type>` | 한 스키마 유형의 버전을 나열합니다. |
| `schema get --type <type>` | 스키마 유형의 한 버전(유형, 버전, 네임스페이스)을 가져옵니다. 기본값은 최신 버전입니다. |
| `schema download --dest <directory>` | 한 버전, 한 유형의 모든 버전 또는 모든 유형의 모든 버전의 XSD를 디렉터리에 저장합니다. |
| `schema download --type <type> --version <n> --dest -` | XSD 하나를 stdout에 씁니다. |

### `schema list` 옵션

| 옵션 | 필수 | 설명 |
| - | - | - |
| `--type <type>` | 아니요 | 버전을 나열할 스키마 유형입니다. 모든 유형을 나열하려면 생략합니다. |
| `--output <format>` | 아니요 | `json`(기본값), `json-compact` 또는 `TYPE`, `VERSION`, `NAMESPACE`, `PATH`, `BYTES` 열이 있는 `table`. |

### `schema get` 옵션

| 옵션 | 필수 | 설명 |
| - | - | - |
| `--type <type>` | 예 | 스키마 유형입니다. |
| `--version <number>` | 아니요 | 양수인 스키마 버전입니다. 기본값은 해당 유형의 최신 버전입니다. |
| `--output <format>` | 아니요 | `json`(기본값), `json-compact` 또는 `TYPE`, `VERSION`, `NAMESPACE` 열이 있는 `table`. |

`schema get`은 JSON 개체 하나를 씁니다.

```json theme={null}
{
  "type": "achievements2017",
  "version": 1,
  "namespace": "http://config.mgt.xboxlive.com/schema/achievements2017/1"
}
```

### `schema download` 옵션

| 옵션 | 필수 | 설명 |
| - | - | - |
| `--dest <directory>` | 예 | 저장할 XSD 파일의 디렉터리 또는 XSD 하나를 stdout에 쓰기 위한 `-`. `-`에는 `--type`과 `--version`이 모두 필요합니다. |
| `--type <type>` | 아니요 | 스키마 유형입니다. 모든 유형을 다운로드하려면 생략합니다. |
| `--version <number>` | 아니요 | 양수인 스키마 버전입니다. `--type`이 필요합니다. 모든 버전을 다운로드하려면 생략합니다. |
| `--output <format>` | 아니요 | `json`(기본값), `json-compact` 또는 `TYPE`, `VERSION`, `NAMESPACE`, `PATH`, `BYTES` 열이 있는 `table`. |

각 스키마는 유형을 소문자로 하여 `<type>_<version>.xsd`로 저장되며, 명령은 저장된 경로를
출력합니다. `--dest -`를 사용하면 대신 원시 XSD를 stdout에 쓰며, `--output`은 적용되지
않습니다.

### `schema` 예제

```bash theme={null}
# List every schema type
xbox xbl schema list

# List versions of one type, as a table
xbox xbl schema list --type achievements2017 --output table

# Get the latest version of one type
xbox xbl schema get --type achievements2017

# Redirect one XSD straight to a file
xbox xbl schema download --type achievements2017 --version 1 --dest - > achievements2017_1.xsd

# Save one XSD into a directory
xbox xbl schema download --type achievements2017 --version 1 --dest schemas

# Download every version of one schema type
xbox xbl schema download --type achievements2017 --dest schemas

# Download every version of every schema type
xbox xbl schema download --dest schemas
```

***

## 일반적인 구성 왕복 작업

1. 접근할 수 있는 샌드박스를 찾습니다.

   ```bash theme={null}
   xbox sandbox list --output table
   ```

2. 작업 구성과 게시된 구성의 현재 상태를 확인합니다.

   ```bash theme={null}
   xbox xbl config list \
     --scid aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee --output table
   ```

3. 초안 문서 세트를 다운로드합니다. 이때 `SANDBOX1.etag`도 저장됩니다.

   ```bash theme={null}
   xbox xbl config download \
     --scid aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee --sandbox-id SANDBOX1 --view draft --dest xbox-config
   ```

4. `xbox-config`의 문서를 편집한 다음 유효성을 검사합니다.

   ```bash theme={null}
   xbox xbl config save \
     --scid aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee --sandbox-id SANDBOX1 \
     --file "xbox-config/*.xml" --validate-only
   ```

5. 문서를 저장합니다.

   ```bash theme={null}
   xbox xbl config save \
     --scid aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee --sandbox-id SANDBOX1 \
     --file "xbox-config/*.xml" --message "Update configuration"
   ```

6. SANDBOX1에 게시합니다.

   ```bash theme={null}
   xbox xbl config publish \
     --scid aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee --sandbox-id SANDBOX1
   ```

7. 게시를 확인하고, 상태가 `Success` 또는 `Failed`가 될 때까지 반복합니다.

   ```bash theme={null}
   xbox xbl config status \
     --scid aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee --sandbox-id SANDBOX1 --output table
   ```


## Related topics

- [XBOX 서비스 구성](https://docs.xbox.com/ko/publishing/game-publishing/concepts/xbox-services.md)
- [게임의 XBOX 서비스 구성](https://docs.xbox.com/ko/publishing/game-publishing/tutorial-xbox-managed/how-to-configure-xbox-services.md)
- [XBOX 서비스 구성 요약 페이지](https://docs.xbox.com/ko/services/xbox-services/fundamentals/portal-config/live-portal-summary-tab.md)
- [Partner Center에서 XBOX 서비스 설정 구성](https://docs.xbox.com/ko/services/xbox-services/fundamentals/portal-config/live-config-xbl-setup.md)
- [포털 구성](https://docs.xbox.com/ko/services/xbox-services/fundamentals/portal-config/index.md)
