> ## 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/zh-TW/tools/xbox-cli/commands/context.md)所述，其次為您唯一的賣方。 |
| `--file <path>` | `upload` | 是 | 本機 `.png` 檔案，大小必須正好是 **1920 × 1080 像素**，且最多 **20 MiB**。 |
| `--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/zh-TW/tools/xbox-cli/safety.md)。


## Related topics

- [XBOX services 設定](https://docs.xbox.com/zh-TW/tools/xbox-cli/commands/xbl.md)
- [成就](https://docs.xbox.com/zh-TW/services/xbox-services/player-data/achievements/index.md)
- [成就 URI](https://docs.xbox.com/zh-TW/reference/live/rest/uri/achievements/atoc-reference-achievementsv2.md)
- [MediaAsset (JSON)](https://docs.xbox.com/zh-TW/reference/live/rest/json/json-mediaasset.md)
- [在 Partner Center 中設定成就](https://docs.xbox.com/zh-TW/publishing/game-publishing/how-to/data-platform-2013/how-to-configure-achievements-2013.md)
