> ## 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.

# Imagens de conquistas

> Carregue, obtenha, liste e baixe imagens de conquistas do XBOX.

`xbox xbl achievement-image` carrega imagens PNG para as conquistas de um título e lê de volta as
imagens registradas para ele. `--scid` recebe o identificador de configuração de serviço (SCID) do título.
`upload` retorna uma `iconImageId` para colocar na configuração de conquistas do título.

| Comando | Efeito |
| - | - |
| `achievement-image upload` | Carrega uma nova imagem e a registra para o SCID. |
| `achievement-image get` | Consulta uma imagem registrada. |
| `achievement-image list` | Lista as imagens registradas para um SCID. |
| `achievement-image download` | Salva imagens completas e miniaturas em `--dest`. |

## Opções

| Opção | Comando | Obrigatória | Descrição |
| - | - | - | - |
| `--scid <guid>` | todos | Sim | SCID do título do XBOX. |
| `--seller-id <id>` | todos | Não | ID do vendedor no Partner Center. O padrão é definido conforme descrito em [Contexto](https://docs.xbox.com/pt-BR/tools/xbox-cli/commands/context.md) e, em seguida, é seu único vendedor. |
| `--file <path>` | `upload` | Sim | Arquivo `.png` local, com exatamente **1920 × 1080 pixels** e no máximo **20 MiB**. |
| `--asset-id <guid>` | `get`, `download` | Para `get`; `--asset-id` ou `--all` para `download` | ID do ativo retornada por `upload` ou encontrada com `list`. |
| `--all` | `download` | Alternativa a `--asset-id` | Baixa todas as imagens registradas para o SCID. |
| `--dest <directory>` | `download` | Sim | Salva cada imagem e sua miniatura em uma subpasta nomeada com a ID do ativo. |
| `--output <format>` | todos | Não | `json` (padrão), `json-compact` ou `table`. |

## Exemplos

Carregue uma imagem:

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

Passe o `assetId` que `upload` retorna para verificar a imagem e para baixá-la, junto com sua
miniatura, em `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
```

Liste todas as imagens registradas para o SCID e baixe todas elas:

```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
```

## Saída

`upload` e `get` retornam um objeto de imagem, e `list` retorna uma matriz desses objetos, ou `[]`.
Cada objeto tem os campos do serviço, como `assetId`, `cdnUrl`, `thumbnailCdnUrl`,
`widthInPixels` e `heightInPixels`, além de `iconImageId`, que é igual a `assetId`:

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

Copie `iconImageId` para a configuração `achievements2017.xml` do título:

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

As tabelas desses comandos mostram `ASSET ID`, `CDN FILENAME`, `WIDTH`, `HEIGHT`, `IMAGE TYPE` e `PUBLIC`.
Use JSON para obter as URLs completas da CDN e os outros campos.

`download` retorna um manifesto: um objeto com `assetId`, `destination`, `imagePath`,
`thumbnailPath`, `imageBytes` e `thumbnailBytes` para `--asset-id`, ou uma matriz desses objetos para
`--all`. Sua tabela mostra `ASSET ID` e `DESTINATION`. Arquivos com os mesmos nomes são substituídos,
e os outros arquivos da pasta do ativo são mantidos. Se um download falhar, os arquivos existentes desse ativo
permanecem como estavam; com `--all`, as pastas já baixadas permanecem.

Um comando com falha sai com o código 1 e grava o erro em stderr. Quando o serviço rejeita a imagem,
o erro lista cada mensagem de validação.

## Segurança em produção e recuperação de carregamentos

Cada carregamento registra uma nova imagem, mesmo que seja do mesmo arquivo, e a CLI nunca repete um carregamento. Se
`upload` relatar `Upload outcome unknown`, a imagem pode ter sido registrada: execute o comando `get`
ou `list` que ele imprime em stderr antes de carregar novamente e use a ID do ativo existente se
encontrar sua imagem. Pressionar Ctrl+C antes de o registro ser enviado não registra nada.

Para inspecionar a imagem completa e a miniatura, baixe-as:

```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` não pede confirmação antes de registrar uma imagem, e `--confirm` não se aplica a ele. Consulte
[Segurança e operações destrutivas](https://docs.xbox.com/pt-BR/tools/xbox-cli/safety.md).


## Related topics

- [Configuração dos serviços do XBOX](https://docs.xbox.com/pt-BR/tools/xbox-cli/commands/xbl.md)
- [Conquistas baseadas em eventos vs. gerenciadas pelo título](https://docs.xbox.com/pt-BR/services/xbox-services/player-data/achievements/live-achievements-eb-vs-tm.md)
- [Configurar recompensas de conquistas do XBOX](https://docs.xbox.com/pt-BR/services/xbox-services/player-data/achievements/title-managed/concepts/live-achievement-rewards.md)
- [URIs de conquistas](https://docs.xbox.com/pt-BR/reference/live/rest/uri/achievements/atoc-reference-achievementsv2.md)
- [Sistemas de conquistas de usuário](https://docs.xbox.com/pt-BR/services/xbox-services/player-data/achievements/live-achievements-nav.md)
