> ## 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 achievement-image`는 타이틀의 도전 과제용 PNG 이미지를 업로드하고, 타이틀에
등록된 이미지를 다시 읽어 옵니다. `--scid`는 타이틀의 서비스 구성 식별자(SCID)를 받습니다.
`upload`는 타이틀의 도전 과제 구성에 넣을 `iconImageId`를 반환합니다.

| 명령 | 효과 |
| - | - |
| `achievement-image upload` | 새 이미지를 업로드하고 SCID에 등록합니다. |
| `achievement-image get` | 등록된 이미지 하나를 조회합니다. |
| `achievement-image list` | SCID에 등록된 이미지를 나열합니다. |
| `achievement-image download` | 전체 이미지와 썸네일을 `--dest` 아래에 저장합니다. |

## 옵션

| 옵션 | 명령 | 필수 | 설명 |
| - | - | - | - |
| `--scid <guid>` | 모두 | 예 | XBOX 타이틀의 SCID입니다. |
| `--seller-id <id>` | 모두 | 아니요 | Partner Center 판매자 ID입니다. 기본값은 [컨텍스트](https://docs.xbox.com/ko/tools/xbox-cli/commands/context.md)에 설명된 대로 정해지며, 그다음은 유일한 판매자입니다. |
| `--file <path>` | `upload` | 예 | 정확히 **1920 × 1080픽셀**이고 최대 **20MiB**인 로컬 `.png` 파일입니다. |
| `--asset-id <guid>` | `get`, `download` | `get`의 경우 필수, `download`의 경우 `--asset-id` 또는 `--all` 중 하나 | `upload`가 반환하거나 `list`로 찾은 자산 ID입니다. |
| `--all` | `download` | `--asset-id`의 대안 | SCID에 등록된 모든 이미지를 다운로드합니다. |
| `--dest <directory>` | `download` | 예 | 각 이미지와 썸네일을 자산 ID 이름의 하위 폴더에 저장합니다. |
| `--output <format>` | 모두 | 아니요 | `json`(기본값), `json-compact` 또는 `table`. |

## 예제

이미지를 업로드합니다.

```bash theme={null}
xbox xbl achievement-image upload \
  --scid aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee --seller-id 1234567 \
  --file achievement-1920x1080.png
```

`upload`가 반환한 `assetId`를 전달하여 이미지를 확인하고, 이미지와 썸네일을
`achievement-images/<assetId>/`에 다운로드합니다.

```bash theme={null}
xbox xbl achievement-image get \
  --scid aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee --seller-id 1234567 \
  --asset-id 11111111-2222-3333-4444-555555555555 --output json-compact

xbox xbl achievement-image download \
  --scid aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee --seller-id 1234567 \
  --asset-id 11111111-2222-3333-4444-555555555555 --dest achievement-images
```

SCID에 등록된 모든 이미지를 나열하고 모두 다운로드합니다.

```bash theme={null}
xbox xbl achievement-image list \
  --scid aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee --seller-id 1234567 \
  --output table

xbox xbl achievement-image download \
  --scid aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee --seller-id 1234567 \
  --all --dest achievement-images --output table
```

## 출력

`upload`와 `get`은 이미지 개체 하나를 반환하고, `list`는 이미지 개체의 배열 또는 `[]`를
반환합니다. 각 개체에는 `assetId`, `cdnUrl`, `thumbnailCdnUrl`, `widthInPixels`,
`heightInPixels` 같은 서비스의 필드와 함께, `assetId`와 같은 값인 `iconImageId`가 있습니다.

```json theme={null}
{
  "assetId": "11111111-2222-3333-4444-555555555555",
  "iconImageId": "11111111-2222-3333-4444-555555555555"
}
```

`iconImageId`를 타이틀의 `achievements2017.xml` 구성에 복사합니다.

```xml theme={null}
<IconImageId>11111111-2222-3333-4444-555555555555</IconImageId>
```

이 명령의 테이블에는 `ASSET ID`, `CDN FILENAME`, `WIDTH`, `HEIGHT`, `IMAGE TYPE`, `PUBLIC`이 표시됩니다.
전체 CDN URL과 기타 필드를 보려면 JSON을 사용하세요.

`download`는 매니페스트를 반환합니다. `--asset-id`의 경우 `assetId`, `destination`,
`imagePath`, `thumbnailPath`, `imageBytes`, `thumbnailBytes`가 있는 개체이고, `--all`의
경우 그러한 개체의 배열입니다. 테이블에는 `ASSET ID`와 `DESTINATION`이 표시됩니다. 이름이
같은 파일은 대체되고, 자산 폴더의 다른 파일은 유지됩니다. 다운로드가 실패하면 해당 자산의
기존 파일은 그대로 남습니다. `--all`을 사용한 경우 이미 다운로드된 폴더는 유지됩니다.

실패한 명령은 1로 종료하고 오류를 stderr에 씁니다. 서비스가 이미지를 거부하면 오류에 각
유효성 검사 메시지가 나열됩니다.

## 프로덕션 안전 및 업로드 복구

모든 업로드는 같은 파일이라도 새 이미지를 등록하며, CLI는 업로드를 절대 다시 시도하지
않습니다. `upload`가 `Upload outcome unknown`을 보고하면 이미지가 등록되었을 수 있습니다.
다시 업로드하기 전에 stderr에 출력된 `get` 또는 `list` 명령을 실행하고, 이미지를 찾으면 기존
자산 ID를 사용하세요. 등록 요청이 전송되기 전에 Ctrl+C를 누르면 아무것도 등록되지 않습니다.

전체 이미지와 썸네일을 검사하려면 다운로드하세요.

```bash theme={null}
xbox xbl achievement-image download \
  --scid aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee --seller-id 1234567 \
  --asset-id 11111111-2222-3333-4444-555555555555 --dest achievement-images
```

`upload`는 이미지를 등록하기 전에 묻지 않으며, `--confirm`은 이 명령에 적용되지 않습니다.
[안전 및 파괴적 작업](https://docs.xbox.com/ko/tools/xbox-cli/safety.md)을 참조하세요.


## Related topics

- [XBOX 서비스 구성](https://docs.xbox.com/ko/tools/xbox-cli/commands/xbl.md)
- [Partner Center에서 도전 과제 구성](https://docs.xbox.com/ko/publishing/game-publishing/how-to/data-platform-2013/how-to-configure-achievements-2013.md)
- [XblAchievementUnlockEvent](https://docs.xbox.com/ko/reference/live/xsapi-c/achievements_c/structs/xblachievementunlockevent.md)
- [XblAchievement](https://docs.xbox.com/ko/reference/live/xsapi-c/achievements_c/structs/xblachievement.md)
- [컨테이너 이미지 나열](https://docs.xbox.com/ko/services/playfab/api-references/rest/multiplayer/multiplayer-server/list-container-images.md)
