> ## 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-CN/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-CN/tools/xbox-cli/safety.md)。


## Related topics

- [XBOX 服务配置](https://docs.xbox.com/zh-CN/tools/xbox-cli/commands/xbl.md)
- [XBOX CLI](https://docs.xbox.com/zh-CN/tools/xbox-cli/index.md)
- [成就](https://docs.xbox.com/zh-CN/services/xbox-services/player-data/achievements/index.md)
- [在 Partner Center 中配置成就](https://docs.xbox.com/zh-CN/publishing/game-publishing/how-to/data-platform-2013/how-to-configure-achievements-2013.md)
- [基于事件的成就与游戏管理的成就](https://docs.xbox.com/zh-CN/services/xbox-services/player-data/achievements/live-achievements-eb-vs-tm.md)
