Saída de erro estruturada na AWS CLI - AWS Command Line Interface
Configurar o formato do erroFormato de saída de erroExemplo completo

Saída de erro estruturada na AWS CLI

Este tópico descreve os formatos de saída de erro estruturada para a AWS Command Line Interface (AWS CLI). A CLI grava erros em stderr e aceita os seguintes formatos:

  • enhanced (padrão): mensagem de erro com detalhes adicionais exibidos em linha. Use para depuração legível por humanos.

  • json: a saída é formatada como uma string JSON com todos os campos de erro. Use para automação e criação de scripts.

  • yaml: a saída é formatada como uma string YAML com todos os campos de erro. Use para automação e criação de scripts.

  • text: formata erros usando o formatador de texto. Use para verificação visual rápida.

  • table: formata erros usando o formatador de tabela. Use para verificação visual rápida.

  • legacy: formato de erro original sem detalhes estruturados. Use para compatibilidade com versões anteriores.

Configurar o formato do erro

É possível configurar o formato do erro usando qualquer um dos seguintes métodos:

Sinalizador da linha de comandos
$ aws <command> --cli-error-format json
Arquivo de configuração: (~/.aws/config)
[default]
cli_error_format = json
Variável de ambiente
$ export AWS_CLI_ERROR_FORMAT=yaml

Formato de saída de erro

As seguintes seções descrevem cada formato.

Formato aprimorado (padrão)

O formato aprimorado exibe mensagens de erro com detalhes adicionais em linha para valores simples. Para estruturas complexas, o formato fornece uma dica para usar JSON ou YAML.

Exemplo: configuração de região ausente

aws: [ERROR]: An error occurred (NoRegion): You must specify a region. You can also configure your region by running "aws configure".

Exemplo: bucket do S3 inexistente com campos adicionais


aws: [ERROR]: An error occurred (NoSuchBucket) when calling the GetObject operation: The specified bucket does not exist

Additional error details:
BucketName: amzn-s3-demo-bucket

Exemplo: campos de erro complexos


An error occurred (TransactionCanceledException) when calling the TransactWriteItems operation: Transaction cancelled, please refer cancellation reasons for specific reasons [ConditionalCheckFailed, None]

Additional error details:
CancellationReasons: <complex value>
Use "--cli-error-format json" or another error format to see the full details.

Formato JSON

O formato JSON fornece uma representação estruturada com todos os campos de erro.

Exemplo: configuração de região ausente

{
    "Code": "NoRegion",
    "Message": "You must specify a region. You can also configure your region by running \"aws configure\"."
}

Exemplo: bucket do S3 inexistente

{
    "Code": "NoSuchBucket",
    "Message": "The specified bucket does not exist",
    "BucketName": "amzn-s3-demo-bucket"
}

Formato YAML

O formato YAML fornece uma representação estruturada com todos os campos de erro.

Exemplo: configuração de região ausente

Code: NoRegion
Message: You must specify a region. You can also configure your region by running "aws configure".

Exemplo: bucket do S3 inexistente

Code: NoSuchBucket
Message: The specified bucket does not exist
BucketName: amzn-s3-demo-bucket

Formato de texto

O formato de texto usa o mesmo formatador usado para uma saída bem-sucedida do comando.

Exemplo: bucket do S3 inexistente

amzn-s3-demo-bucket  NoSuchBucket    The specified bucket does not exist

Formato da tabela

O formato de tabela usa o mesmo formatador usado para uma saída bem-sucedida do comando.

Exemplo: bucket do S3 inexistente

-------------------------------------------------------------------------------------|
|                                       error                                        |
+---------------------------+---------------+----------------------------------------+
|        BucketName         |     Code      |                Message                 |
+---------------------------+---------------+----------------------------------------+
|  amzn-s3-demo-bucket      |  NoSuchBucket |  The specified bucket does not exist   |
+---------------------------+---------------+----------------------------------------+

Formato legado

O formato legado fornece o formato de erro original sem detalhes estruturados. Esse formato não inclui o prefixo “An error occurred (ErrorCode):” para exceções da CLI.

Exemplo: configuração de região ausente

aws: [ERROR]: You must specify a region. You can also configure your region by running "aws configure".

Exemplo: bucket do S3 inexistente

An error occurred (NoSuchBucket) when calling the GetObject operation: The specified bucket does not exist
nota

Agora os erros incluem consistentemente o prefixo aws: [ERROR]: para exceções da CLI. As versões anteriores nem sempre incluíam esse prefixo.

As seguintes exceções sempre usam o formato legado, independentemente do formato de erro configurado:

  • UnknownArgumentError: exibe informações de uso.

  • Interrupções do teclado (KeyboardInterrupt)

Exemplo completo

O seguinte exemplo mostra um comando com a formatação de erro JSON.

$ aws s3api get-object \
    --bucket amzn-s3-demo-bucket \
    --key file.txt out.txt \
    --cli-error-format json

Saída (stderr):

{
    "Code": "NoSuchBucket",
    "Message": "The specified bucket does not exist",
    "BucketName": "amzn-s3-demo-bucket"
}

O campo BucketName é um membro de erro modelado exibido pelo serviço Amazon S3.