> ## 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 샌드박스는 Microsoft Store 제품과 XBOX 서비스를 위한 Partner Center 계정의 격리된 환경입니다.
`RETAIL` 같은 글로벌 샌드박스는 Microsoft가 관리하며, `ABCDEF.1` 같은 개발 샌드박스는 사용자의 계정에
속합니다. 게임 게시 가이드의
[샌드박스](https://learn.microsoft.com/gaming/game-publishing/concepts/sandboxes)를 참조하세요. Windows
PC가 사용하는 샌드박스를 전환하려면 [PC](https://docs.xbox.com/ko/tools/xbox-cli/commands/pc.md)를 참조하세요.

각 명령은 `--seller-id` 또는 저장된 판매자에서 가져온 판매자 하나에 대해 작동합니다.
[컨텍스트](https://docs.xbox.com/ko/tools/xbox-cli/commands/context.md)를 참조하세요. 그 판매자가 Partner Center에서 마지막으로
선택한 판매자가 아니라면
[이 알려진 문제](https://docs.xbox.com/ko/tools/xbox-cli/known-issues.md#xbox-sandbox-commands-show-only-global-sandboxes)를 참조하세요.

## 명령

| 명령 | 설명 |
| - | - |
| `sandbox list` | Partner Center의 샌드박스 페이지에 표시되는 대로 판매자의 샌드박스와 글로벌 샌드박스를 나열합니다. |
| `sandbox get <sandbox-id>` | 글로벌 또는 격리된 샌드박스를 포함하여 샌드박스 하나의 ID, 유형, 소유 판매자 및 글로벌 여부를 가져옵니다. |
| `sandbox create <sandbox-id>` | 공유 개발 샌드박스를 생성한 다음 생성 작업을 기다립니다. |

## 인수 및 옵션

| 인수 또는 옵션 | 적용 대상 | 필수 | 설명 |
| - | - | - | - |
| `<sandbox-id>` | `get`, `create` | 예 | 샌드박스 ID이며, 예를 들면 `ABCDEF.1`입니다. 대/소문자는 구분하지 않습니다. [샌드박스 ID](#sandbox-ids)를 참조하세요. |
| `--seller-id <id>` | 모두 | 저장되지 않은 경우 | Partner Center 판매자 ID입니다. |
| `--base-url <url>` | 모두 | 아니요 | 요청의 기본 URL이며, `XboxPartner:BaseUrl` 구성 키를 재정의합니다. |
| `--confirm`, `--yes`, `-y` | `create` | 아니요 | 확인 프롬프트 없이 샌드박스를 생성합니다. |
| `--output <format>` | 모두 | 아니요 | `json`(기본값) 또는 `json-compact`이며, `table`은 `list`와 `get`에서만 사용할 수 있습니다. |

`list`에서 얻은 `sandboxId`를 [`xbl`](https://docs.xbox.com/ko/tools/xbox-cli/commands/xbl) 명령의 `--sandbox-id` 옵션 같은 다른
명령에 전달하세요.

### 샌드박스 ID

샌드박스 ID는 문자와 숫자로 구성되며, 마침표로 구분된 접미사를 선택적으로 붙일 수 있고, 최대 64자입니다.
CLI는 이를 대문자로 변환합니다.

* `get`은 `RETAIL`, `CERT.DEBUG` 같은 글로벌 샌드박스 ID를 포함하여 모든 샌드박스 ID를 허용합니다.
* `create`에는 4~~60자의 문자 또는 숫자, 마침표, 그리고 앞에 0이 없는 `0`~~`999`의 숫자가 필요하며, 예를
  들면 `ABCDEF.1`입니다. 접미사 `.58`은 격리된 샌드박스용으로 예약되어 있으며, `UNDEFINED`와 글로벌
  샌드박스 이름은 사용할 수 없습니다.

## 출력

`sandbox get`은 샌드박스 하나를 씁니다.

```json theme={null}
{ "sandboxId": "ABCDEF.58", "type": "Isolated", "sellerId": "1234567", "global": false }
```

| 필드 | 설명 |
| - | - |
| `sandboxId` | 샌드박스 ID입니다. |
| `type` | `Shared`, `Isolated` 또는 `Unknown`. `create`는 공유 샌드박스만 만듭니다. |
| `sellerId` | 소유 판매자이며, 글로벌 샌드박스의 경우 `null`입니다. |
| `global` | `RETAIL` 같은 글로벌 샌드박스의 경우 `true`입니다. |

`sandbox list`는 같은 개체의 `sandboxes` 배열을 씁니다.

```json theme={null}
{
  "sandboxes": [
    { "sandboxId": "RETAIL", "type": "Shared", "sellerId": null, "global": true },
    { "sandboxId": "ABCDEF.1", "type": "Shared", "sellerId": "1234567", "global": false }
  ]
}
```

`list --output table`에는 `SANDBOX`, `TYPE`, `GLOBAL` 열이 있고, `get --output table`에는 `SANDBOX ID`,
`TYPE`, `SELLER ID` 열이 있습니다. `create`는 `--output table`을 거부합니다.

## 샌드박스 생성

```bash theme={null}
xbox sandbox create ABCDEF.1 --seller-id 1234567 --confirm
```

`sandbox create`는 샌드박스를 생성하기 전에 묻습니다. 터미널이 없으면 `--confirm`이 필요합니다. CLI는
샌드박스를 삭제할 수 없습니다. 여러 판매자에 속해 있다면 먼저
[알려진 문제](https://docs.xbox.com/ko/tools/xbox-cli/known-issues.md#xbox-sandbox-commands-show-only-global-sandboxes)를 확인하세요.
샌드박스가 다른 판매자에 생성될 수 있습니다.

이 명령은 요청을 한 번 보내고 생성 작업을 최대 2분 동안 기다립니다. 작업이 성공하면 `sandbox get`과 같은
형식으로 새 샌드박스를 씁니다. 작업 ID, 상관 관계 ID 및 다음에 확인할 사항은 stderr로 출력됩니다. 종료
코드가 `3` 또는 `4`이면 `sandbox get <sandbox-id>`로 확인하고, 샌드박스를 다시 생성하지 마세요.

| 종료 코드 | 의미 |
| - | - |
| `0` | 샌드박스가 생성되었습니다. |
| `1` | 샌드박스가 생성되지 않았습니다. 입력 또는 확인이 거부되었거나, 요청이 전송되지 않았거나, 서비스가 요청을 거부했습니다(예: 샌드박스가 이미 있을 때 `409`). 문제를 해결하고 명령을 다시 실행하세요. |
| `2` | 생성 작업이 실패했습니다. `errors`가 포함된 작업이 stdout에 기록됩니다. |
| `3` | 요청이 전송되었지만 결과를 알 수 없습니다. `sandbox get`으로 확인하세요. |
| `4` | 작업이 수락되었지만 샌드박스가 확인되기 전에 대기가 끝났습니다. stdout에는 아무것도 기록되지 않습니다. `sandbox get`으로 확인하세요. |

## 오류

실패하면 `--output`과 관계없이 상관 관계 ID, HTTP 상태에 대한 안내, 그리고 있는 경우 서비스의 오류 세부
정보가 텍스트로 stderr에 기록됩니다. `--verbose`는 응답 본문을 추가합니다. 스크립트는 문구가 아니라 종료
코드에 따라 분기해야 합니다.

## 예제

샌드박스를 나열하고 그중 두 개를 가져옵니다.

```bash theme={null}
xbox sandbox list --output table
xbox sandbox get ABCDEF.1
xbox sandbox get RETAIL
```

확인 프롬프트 없이 샌드박스를 생성합니다.

```bash theme={null}
xbox sandbox create ABCDEF.2 --seller-id 1234567 --confirm --output json-compact
```


## Related topics

- [샌드박스](https://docs.xbox.com/ko/publishing/game-publishing/concepts/sandboxes.md)
- [샌드박스 설정](https://docs.xbox.com/ko/services/xbox-services/fundamentals/sandboxes/live-setting-up-sandboxes.md)
- [고급 XBOX services 샌드박스](https://docs.xbox.com/ko/services/xbox-services/fundamentals/sandboxes/live-advanced-sandboxes.md)
- [XBOX 서비스 샌드박스 개요](https://docs.xbox.com/ko/services/xbox-services/fundamentals/sandboxes/live-setup-sandbox.md)
- [개발 샌드박스 만들기 및 관리](https://docs.xbox.com/ko/publishing/game-publishing/how-to/how-to-create-and-manage-sandboxes.md)
