> ## 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` | 登録されている画像を 1 つ検索します。 |
| `achievement-image list` | SCID に登録されている画像を一覧表示します。 |
| `achievement-image download` | フルサイズの画像とサムネイルを `--dest` に保存します。 |

## オプション

| オプション | コマンド | 必須 | 説明 |
| - | - | - | - |
| `--scid <guid>` | すべて | はい | XBOX タイトルの SCID。 |
| `--seller-id <id>` | すべて | いいえ | パートナー センターの販売者 ID。既定値は [コンテキスト](https://docs.xbox.com/ja-jp/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` から返されたアセット ID、または `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` は画像オブジェクトを 1 つ返し、`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` は `upload` には適用されません。
[安全性と破壊的な操作](https://docs.xbox.com/ja-jp/tools/xbox-cli/safety.md)を参照してください。


## Related topics

- [XBOX サービスの構成](https://docs.xbox.com/ja-jp/tools/xbox-cli/commands/xbl.md)
- [イベント ベースの実績のポータル構成](https://docs.xbox.com/ja-jp/services/xbox-services/player-data/achievements/event-based/config/live-achievements-eb-portal.md)
- [イベント ベース vs. タイトル管理の実績](https://docs.xbox.com/ja-jp/services/xbox-services/player-data/achievements/live-achievements-eb-vs-tm.md)
- [実績](https://docs.xbox.com/ja-jp/services/xbox-services/player-data/achievements/index.md)
- [Steam 実績の付与](https://docs.xbox.com/ja-jp/services/playfab/api-references/rest/server/platform-specific-methods/award-steam-achievement.md)
