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: função do Lambda inexistente com campos adicionais
aws: [ERROR]: An error occurred (ResourceNotFoundException) when calling the GetFunction operation: Function not found: arn:aws:lambda:us-west-2:123456789012:function:nonexistent-function-12345 Additional error details: Type: User
A seção “Detalhes adicionais do erro” exibe apenas os campos definidos no modelo de estrutura de erro do serviço. Campos não modelados da resposta de erro não são exibidos.
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: função do Lambda inexistente
{ "Code": "ResourceNotFoundException", "Message": "Function not found: arn:aws:lambda:us-west-2:123456789012:function:nonexistent-function-12345", "Type": "User" }
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: função do Lambda inexistente
Code: ResourceNotFoundException Message: "Function not found: arn:aws:lambda:us-west-2:123456789012:function:nonexistent-function-12345" Type: User
Formato de texto
O formato de texto usa o mesmo formatador usado para uma saída bem-sucedida do comando.
Exemplo: função do Lambda inexistente
ResourceNotFoundException Function not found: arn:aws:lambda:us-west-2:123456789012:function:nonexistent-function-12345 User
Formato da tabela
O formato de tabela usa o mesmo formatador usado para uma saída bem-sucedida do comando.
Exemplo: função do Lambda inexistente
------------------------------------------------------------------------------------------------------------------------------------| | error | +----------------------------+--------------------------------------------------------------------------------------------------+------+ | Code | Message | Type | +----------------------------+--------------------------------------------------------------------------------------------------+------+ | ResourceNotFoundException | Function not found: arn:aws:lambda:us-west-2:123456789012:function:nonexistent-function-12345 | User | +----------------------------+--------------------------------------------------------------------------------------------------+------+
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: função do Lambda inexistente
An error occurred (ResourceNotFoundException) when calling the GetFunction operation: Function not found: arn:aws:lambda:us-west-2:123456789012:function:nonexistent-function-12345
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 lambda get-function \ --function-name nonexistent-function-12345 \ --cli-error-format json
Saída (stderr):
{ "Code": "ResourceNotFoundException", "Message": "Function not found: arn:aws:lambda:us-west-2:123456789012:function:nonexistent-function-12345", "Type": "User" }
O campo Type é um membro de erro modelado, definido na estrutura de erro do serviço Lambda. Apenas os campos definidos no modelo de erro do serviço são incluídos na saída de erro estruturada.
