# Uso de AWS CLI En esta sección se proporciona una descripción general completa del uso general, las características comunes y las opciones disponibles en la AWS Command Line Interface (AWS CLI), además de lo que figura en la sección de configuración [Uso de puntos de conexión en la AWS CLI](cli-configure-endpoints.md). Esta guía profundiza en los aspectos fundamentales de la escritura de comandos de la AWS CLI, incluida su estructura básica, el formato y las capacidades de filtrado. Al conocer estos elementos básicos, podrá crear comandos que se dirijan con precisión a los recursos y las acciones que necesita, sin necesidad de navegar por complejas consolas basadas en la web. Además, aquí se destacan el contenido de ayuda y la documentación disponibles para la AWS CLI. Desde la ayuda de línea de comandos integrada hasta la completa [guía de referencia de la versión 2 de la AWS CLI](https://docs.aws.amazon.com/cli/latest/reference/), tendrá acceso a información que le ayudará a explorar las características y capacidades de la AWS CLI. Para ver ejemplos específicos del Servicio de AWS, consulte [Ejemplos para la AWS CLI](cli-chap-code-examples.md) en la [guía de referencia de la versión 2 de la AWS CLI](https://docs.aws.amazon.com/cli/latest/reference/). Proporcionan información específica sobre los comandos y muestran ejemplos sobre cómo aprovechar la AWS CLI para varios Servicios de AWS. **nota** De forma predeterminada, la AWS CLI envía solicitudes a Servicios de AWS mediante HTTPS en el puerto TCP 443. Para utilizar la AWS CLI correctamente, debe poder realizar conexiones salientes en este puerto. **Topics** + [Acceso a la ayuda y a los recursos para la AWS CLI](cli-usage-help.md) + [Estructura de comandos en la AWS CLI](cli-usage-commandstructure.md) + [Especificación de valores de parámetros en la AWS CLI](cli-usage-parameters.md) + [Activación y uso de los símbolos del sistema en la AWS CLI](cli-usage-parameters-prompting.md) + [Control de la salida de comandos en la AWS CLI](cli-usage-output.md) + [Códigos de retorno de la línea de comandos en la AWS CLI](cli-usage-returncodes.md) + [Uso de asistentes personalizados para ejecutar comandos interactivos en la AWS CLI](cli-usage-wizard.md) + [Creación y uso de alias en la AWS CLI](cli-usage-alias.md) + [Solución de errores para la AWS CLI](cli-chap-troubleshooting.md) # Acceso a la ayuda y a los recursos para la AWS CLI En este tema, se describe cómo acceder al contenido de ayuda de AWS Command Line Interface (AWS CLI). **Topics** + [El comando de ayuda de AWS CLI integrado](#cli-usage-help-command) + [Guía de referencia de AWS CLI](#cli-reference) + [Documentación de la API](#api-reference) + [Solución de errores](#help-tshoot) + [Ayuda adicional](#help-additional) ## El comando de ayuda de AWS CLI integrado Puede obtener ayuda para cualquier comando cuando utiliza la AWS Command Line Interface (AWS CLI). Para ello, simplemente escriba `help` al final del nombre de un comando. Por ejemplo, el siguiente comando muestra la ayuda de las opciones generales de la AWS CLI generales y los comandos de nivel superior. ``` $ aws help ``` El comando siguiente muestra los comandos específicos de Amazon Elastic Compute Cloud (Amazon EC2) disponibles. ``` $ aws ec2 help ``` En el siguiente ejemplo se muestra información de ayuda detallada de la operación `DescribeInstances` de Amazon EC2. La ayuda incluye descripciones de los parámetros de entrada, los filtros disponibles y qué se incluye como salida. También incluye ejemplos que muestran cómo escribir variaciones comunes del comando. ``` $ aws ec2 describe-instances help ``` A partir de la versión `2.31.0` La visualización del comando `help` se configura mediante el ajuste `cli_help_output` y tiene los siguientes valores: + **(predeterminado)** `terminal`: abra la página principal en el terminal. + `browser`: abra la página principal como un archivo HTML local en el navegador predeterminado. Se imprime un aviso en el terminal cuando se abre el navegador predeterminado y un mensaje de error si la AWS CLI no puede abrir el navegador. + `url`: imprima la URL de la guía de referencia de AWS CLI en línea de la versión de la AWS CLI que ha instalado. Se respetan los ajustes de la paginación del cliente, como la variable de entorno `AWS_PAGER`. El contenido de ayuda de cada comando se divide en seis secciones: Nombre El nombre del comando. ``` NAME describe-instances - ``` Descripción Una descripción de la operación de la API que el comando invoca. ``` DESCRIPTION Describes one or more of your instances. If you specify one or more instance IDs, Amazon EC2 returns information for those instances. If you do not specify instance IDs, Amazon EC2 returns information for all relevant instances. If you specify an instance ID that is not valid, an error is returned. If you specify an instance that you do not own, it is not included in the returned results. ... ``` Sinopsis La sintaxis básica para utilizar el comando y sus opciones. Si una opción aparece entre corchetes, significa que es opcional, que tiene un valor predeterminado o que existe una opción alternativa que puede utilizarse en su lugar. ``` SYNOPSIS describe-instances [--dry-run | --no-dry-run] [--instance-ids ] [--filters ] [--cli-input-json ] [--starting-token ] [--page-size ] [--max-items ] [--generate-cli-skeleton] ``` Por ejemplo, `describe-instances` tiene un comportamiento predeterminado que describe ***todas*** las instancias de la cuenta y la región de AWS actuales. Si lo desea, puede especificar una lista de `instance-ids` para describir una o varias instancias. `dry-run` es un indicador booleano opcional que no adopta ningún valor. Para utilizar un indicador booleano, especifique el valor aparece; en este caso, `--dry-run` o `--no-dry-run`. Del mismo modo, `--generate-cli-skeleton` no adopta un valor. Si existen condiciones para usar una opción, aparecen descritas en la sección `OPTIONS` o se muestran en los ejemplos. Opciones Una descripción de cada una de las opciones que aparecen en el resumen. ``` OPTIONS --dry-run | --no-dry-run (boolean) Checks whether you have the required permissions for the action, without actually making the request, and provides an error response. If you have the required permissions, the error response is DryRun- Operation . Otherwise, it is UnauthorizedOperation . --instance-ids (list) One or more instance IDs. Default: Describes all your instances. ... ``` Ejemplos Ejemplos que ilustran el uso del comando y sus opciones. Si no se proporciona un ejemplo de un comando o un caso de uso que necesite, solicítelo a través del enlace de comentarios de esta página o de la referencia de comandos de la AWS CLI en la página de ayuda del comando. ``` EXAMPLES To describe an Amazon EC2 instance Command: aws ec2 describe-instances --instance-ids i-5203422c To describe all instances with the instance type m1.small Command: aws ec2 describe-instances --filters "Name=instance-type,Values=m1.small" To describe all instances with an Owner tag Command: aws ec2 describe-instances --filters "Name=tag-key,Values=Owner" ... ``` Output Descripciones de cada uno de los campos y tipos de datos incluidos en la respuesta de AWS. Para `describe-instances`, la salida es una lista de objetos de reserva, cada uno de los cuales contiene varios campos y objetos con información acerca de las instancias asociadas al mismo. Esta información procede de la [documentación de la API para el tipo de datos de reserva](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_Reservation.html) que utiliza Amazon EC2. ``` OUTPUT Reservations -> (list) One or more reservations. (structure) Describes a reservation. ReservationId -> (string) The ID of the reservation. OwnerId -> (string) The ID of the AWS account that owns the reservation. RequesterId -> (string) The ID of the requester that launched the instances on your behalf (for example, AWS Management Console or Auto Scaling). Groups -> (list) One or more security groups. (structure) Describes a security group. GroupName -> (string) The name of the security group. GroupId -> (string) The ID of the security group. Instances -> (list) One or more instances. (structure) Describes an instance. InstanceId -> (string) The ID of the instance. ImageId -> (string) The ID of the AMI used to launch the instance. State -> (structure) The current state of the instance. Code -> (integer) The low byte represents the state. The high byte is an opaque internal value and should be ignored. ... ``` Cuando la AWS CLI proporciona la salida en formato JSON, se convierte en una matriz de objetos de reserva, similar a la del siguiente ejemplo. ``` { "Reservations": [ { "OwnerId": "012345678901", "ReservationId": "r-4c58f8a0", "Groups": [], "RequesterId": "012345678901", "Instances": [ { "Monitoring": { "State": "disabled" }, "PublicDnsName": "ec2-52-74-16-12.us-west-2.compute.amazonaws.com", "State": { "Code": 16, "Name": "running" }, ... ``` Cada objeto de reserva tiene campos que describen la reserva y una matriz de objetos de instancia, cada uno de ellos con sus propios campos (por ejemplo, `PublicDnsName`) y objetos (por ejemplo `State`) que los describen. **Usuarios de Windows** Puede *añadir una barra vertical* (\$1) a la salida del comando de ayuda al comando `more` para ver las páginas del archivo de ayuda una a una. Pulse la barra espaciadora o **AvPág** para avanzar por el documento y **q** para salir. ``` C:\> aws ec2 describe-instances help | more ``` ## Guía de referencia de AWS CLI Los archivos de ayuda contienen enlaces que no se pueden ver o visitar desde la línea de comandos. Puede consultar e interactuar con estos enlac‎es mediante la [versión 2 de la guía de referencia de AWS CLI](https://docs.aws.amazon.com/cli/latest/reference/index.html) en línea. La referencia también tiene el contenido de la ayuda de todos los comandos de AWS CLI. Las descripciones se presentan para facilitar la navegación y la consulta en móviles, tabletas o equipos de escritorio. ## Documentación de la API Todos los comandos de la AWS CLI corresponden a solicitudes realizadas a la API pública de un servicio de AWS. Todos los servicios con una API pública tienen una referencia de API que puede encontrarse en la página de inicio del servicio en el [AWSsitio web Documentación de ](https://docs.aws.amazon.com/). El contenido de una referencia de API varía en función de cómo se construye la API y del protocolo utilizado. Normalmente, las referencias de API contienen información detallada sobre las acciones compatibles con la API, los datos enviados al servicio y desde este, y cualquier posible situación de error que pueda detectar el sistema. **Secciones de documentación de la API** + **Acciones**: información detallada de cada operación y sus parámetros (incluidas las restricciones de longitud o contenido, y valores predeterminados). Muestra los errores que pueden ocurrir con esta operación. Cada operación se corresponde con un subcomando de la AWS CLI. + **Tipos de datos**: información detallada sobre las estructuras que un comando puede requerir como parámetro, o devolver en respuesta a una solicitud. + **Parámetros comunes**: información detallada sobre los parámetros que utilizan todas las acciones de un servicio. + **Errores comunes**: información detallada sobre los errores que cualquiera de las operaciones del servicio puede devolver. El nombre y la disponibilidad de cada sección puede variar en función del servicio. **CLI específicas de los servicios** Algunos servicios tienen una CLI distinta que existía antes de que se creara una única AWS CLI para funcionar con todos los servicios. Las CLI específicas de los servicios tienen documentación aparte, a la que se accede con un enlace a la página de documentación del servicio. La documentación de las CLI específicas de los servicios no se aplica a AWS CLI. ## Solución de errores Para obtener ayuda a fin de diagnosticar y corregir errores de AWS CLI, consulte [Solución de errores para la AWS CLI](cli-chap-troubleshooting.md). ## Ayuda adicional Para obtener ayuda adicional con sus problemas de AWS CLI, visite la [Comunidad de AWS CLI](https://github.com/aws/aws-cli/issues) en *GitHub*. # Estructura de comandos en la AWS CLI En este tema se abordan cómo está estructurado el comando de la AWS Command Line Interface (AWS CLI) y cómo usar comandos de espera. **Topics** + [Estructura de comandos](#cli-usage-commandstructure-structure.title) + [Comandos de espera](#cli-usage-commandstructure-wait) ## Estructura de comandos La AWS CLI utiliza una estructura de multiparte en la línea de comandos que deben especificarse en el siguiente orden: 1. La llamada base al programa de `aws`. 1. El *comando* de nivel superior, que normalmente corresponde a un servicio de AWS compatible con la AWS CLI. 1. El *subcomando* que especifica qué operación realizar. 1. Opciones o parámetros generales de la AWS CLI necesarios por la operación. Puede especificarlos en cualquier orden siempre que vayan detrás de las tres primeras partes. Si se especifica un parámetro exclusivo varias veces, solo se aplica el *último valor*. ``` $ aws [options and parameters] ``` Los parámetros pueden tomar varios tipos de valores de entrada, como números, cadenas, listas, mapas y estructuras JSON. Los valores admitidos dependen del comando y los subcomandos que especifique. ### Ejemplos **Amazon S3** En el siguiente ejemplo se enumeran todos los buckets de Amazon S3. ``` $ aws s3 ls 2018-12-11 17:08:50 amzn-s3-demo-bucket1 2018-12-14 14:55:44 amzn-s3-demo-bucket2 ``` Para obtener más información acerca de los comandos de Simple Storage Service (Amazon S3), consulte [https://docs.aws.amazon.com/cli/latest/reference/s3/index.html](https://docs.aws.amazon.com/cli/latest/reference/s3/index.html) en la *Referencia de comandos de AWS CLI*. **AWS CloudFormation** El siguiente ejemplo de comando [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/create-change-set.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/create-change-set.html) ‎cambia el nombre de la pila de ‎cloudformation a *my-change-set*. ``` $ aws cloudformation create-change-set --stack-name my-stack --change-set-name my-change-set ``` Para obtener más información acerca de los comandos de AWS CloudFormation, consulte [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/index.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/index.html) en la *Referencia de comandos de AWS CLI*. ## Comandos de espera Algunos servicios de AWS tienen comandos `wait` disponibles. Cualquier comando que use `aws wait` por lo general espera hasta que se completa un comando antes de ir al siguiente paso. Esto es especialmente útil para comandos multiparte o scripting, ya que puede utilizar un comando de espera para evitar pasar a pasos posteriores si el comando de espera falla. La AWS CLI utiliza una estructura multiparte en la línea de comandos para el comando `wait` que debe especificarse en el siguiente orden: 1. La llamada base al programa de `aws`. 1. El *comando* de nivel superior, que normalmente corresponde a un servicio de AWS compatible con la AWS CLI. 1. El comando `wait` 1. El *subcomando* que especifica qué operación realizar. 1. Opciones o parámetros generales de la CLI necesarios por la operación. Puede especificarlos en cualquier orden siempre que vayan detrás de las tres primeras partes. Si se especifica un parámetro exclusivo varias veces, solo se aplica el *último valor*. ``` $ aws wait [options and parameters] ``` Los parámetros pueden tomar varios tipos de valores de entrada, como números, cadenas, listas, mapas y estructuras JSON. Los valores admitidos dependen del comando y los subcomandos que especifique. **nota** No todos los servicios de AWS admiten comandos `wait`. Consulte la [AWS CLIversión 2 de la guía de referencia de ](https://docs.aws.amazon.com/cli/latest/reference/index.html) para ver si el servicio admite comandos `wait`. ### Ejemplos **AWS CloudFormation** Los siguientes ejemplos de comandos [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/wait/change-set-create-complete.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/wait/change-set-create-complete.html)‎ se detienen y se reanudan solo después de que pueda confirmar que el conjunto de cambios *my-change-set*‎ de la pila *my-stack* está listo para ejecutarse. ``` $ aws cloudformation wait change-set-create-complete --stack-name my-stack --change-set-name my-change-set ``` ‎Para obtener más información acerca de los comandos `wait` de AWS CloudFormation‎, consulte [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/wait/index.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/wait/index.html)‎ en la *Referencia de comandos de AWS CLI*. **AWS CodeDeploy** ‎Los ejemplos de comandos [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/wait/change-set-create-complete.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/wait/change-set-create-complete.html) que se muestran a continuación se detienen hasta que se complete satisfactoriamente la implementación de ‎*d-A1B2C3111*. ``` $ aws deploy wait deployment-successful --deployment-id d-A1B2C3111 ``` ‎Para obtener más información acerca de los comandos `wait` de AWS CodeDeploy‎, consulte [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/wait/index.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/wait/index.html)‎ en la *Referencia de los comandos de AWS CLI*. # Especificación de valores de parámetros en la AWS CLI Muchos de los parámetros que se utilizan en AWS Command Line Interface (AWS CLI) son simples valores numéricos o de cadena, como el nombre del par de claves `my-key-pair` en el siguiente ejemplo de comando `aws ec2 create-key-pair`. ``` $ aws ec2 create-key-pair --key-name my-key-pair ``` El formato del comando puede variar entre terminales. Por ejemplo, la mayoría de los terminales distinguen entre mayúsculas y minúsculas, pero Powershell no distingue entre mayúsculas y minúsculas. Esto significa que los dos ejemplos de comandos siguientes arrojarían resultados diferentes para los terminales que distinguen entre mayúsculas y minúsculas, ya que ven `MyFile*.txt` y `myfile*.txt` como parámetros **diferentes**. Sin embargo, PowerShell procesaría estas solicitudes de la misma manera que ve `MyFile*.txt` y `myfile*.txt` como los **mismos** parámetros. En el siguiente ejemplo de comando se muestran estos parámetros con el comando `aws s3 cp`: ``` $ aws s3 cp . s3://amzn-s3-demo-bucket/path --include "MyFile*.txt" $ aws s3 cp . s3://amzn-s3-demo-bucket/path --include "myfile*.txt" ``` Para obtener más información sobre no distinguir entre mayúsculas y minúsculas de casos en PowerShell, consulte [about\$1Case-Sensitivity](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_case-sensitivity) en la *documentación de PowerShell*. A veces es necesario utilizar comillas o literales en las cadenas que incluyen caracteres especiales o de espacio. Las reglas en torno a este formato también pueden variar entre terminales. Para obtener más información sobre el uso de las comillas alrededor de parámetros complejos, consulte [Entrecomillado de cadenas y uso de literales en la AWS CLI](cli-usage-parameters-quoting-strings.md). En estos temas se tratan las reglas de formato de terminal más habituales. Si tiene problemas para que su terminal reconozca los valores de los parámetros, asegúrese de revisar los temas de esta sección y también de consultar la documentación del terminal para conocer sus reglas de sintaxis específicas. **Topics** + [Tipos de parámetros comunes en la AWS CLI](cli-usage-parameters-types.md) + [Entrecomillado de cadenas y uso de literales en la AWS CLI](cli-usage-parameters-quoting-strings.md) + [Carga de un parámetro de un archivo en la AWS CLI](cli-usage-parameters-file.md) + [Esqueletos de la AWS CLI y archivos de entrada en la AWS CLI](cli-usage-skeleton.md) + [Uso de la sintaxis abreviada en la AWS CLI](cli-usage-shorthand.md) # Tipos de parámetros comunes en la AWS CLI En esta sección, se describen algunos de los tipos de parámetros comunes y el formato requerido típico. Si tiene problemas con el formato de un parámetro para un comando específico, compruebe la ayuda escribiendo **help** después del nombre del comando. La ayuda de cada subcomando incluye el nombre y la descripción de una opción. El tipo de parámetro de la opción se muestra entre paréntesis. Para obtener más información acerca de obtener ayuda, consulte [Acceso a la ayuda y a los recursos para la AWS CLI](cli-usage-help.md). **Topics** + [Cadena](#parameter-type-string) + [Marca de tiempo](#parameter-type-timestamp) + [Enumeración](#parameter-type-list) + [Booleano](#parameter-type-boolean) + [Entero](#parameter-type-integer) + [Binario/blob (objeto binario grande) y blob en streaming](#parameter-type-blobs) + [Asignación](#parameter-type-map) + [Documento](#parameter-type-document) ## Cadena Los parámetros de cadena pueden contener caracteres alfanuméricos, símbolos y espacios en blanco del conjunto de caracteres [ASCII](https://wikipedia.org/wiki/ASCII). Las cadenas que contienen espacios en blanco se deben entrecomillar. Le recomendamos que no utilice símbolos ni espacios en blanco diferentes del carácter de espacio estándar, y que observe las [reglas de entrecomillado](cli-usage-parameters-quoting-strings.md) del terminal para evitar resultados inesperados. Algunos parámetros de cadena pueden aceptar datos binarios de un archivo. Consulte [Archivos binarios](cli-usage-parameters-file.md#cli-usage-parameters-file-binary) para ver un ejemplo. ## Marca de tiempo Las marcas temporales tienen un formato conforme a la norma [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html). A menudo se conocen como parámetros "`DateTime`" o "`Date`". ``` $ aws ec2 describe-spot-price-history --start-time 2014-10-13T19:00:00Z ``` Los formatos aceptados son: + *AAAA*-*MM*-*DD*T*hh*:*mm*:*ss.sss**TZD (UTC)*, por ejemplo, 2014-10-01T20:30:00.000Z + *AAAA*-*MM*-*DD*T*hh*:*mm*:*ss.sss**TZD (con compensación)*, por ejemplo, 2014-10-01T12:30:00.000-08:00 + *AAAA*:*MM*:*DD*, por ejemplo, 2014-10-01 + Hora Unix en segundos; por ejemplo, 1412195400. Esto es lo que a veces se denomina [fecha de inicio UNIX](https://wikipedia.org/wiki/Unix_time) y representa el número de segundos desde la medianoche del 1 de enero de 1970 UTC. De forma predeterminada, la versión 2 de la AWS CLI convierte todos los valores DateTime ***response*** al formato ISO 8601. Puede establecer el formato de la marca de tiempo con el ajuste de archivo `cli\$1timestamp\$1format`. ## Enumeración Una o varias cadenas separadas por espacios. Si cualquiera de los elementos de cadena contiene un espacio, debe escribir dicho elemento entre comillas. Observe las [normas de entrecomillado](cli-usage-parameters-quoting-strings.md) del terminal para evitar resultados inesperados ``` $ aws ec2 describe-spot-price-history --instance-types m1.xlarge m1.medium ``` ## Booleano Marcador binario que activa o desactiva una opción. Por ejemplo, `ec2 describe-spot-price-history` tiene con un parámetro `--dry-run` booleano que, cuando se especifica, valida la consulta con el servicio sin ejecutar realmente una consulta. ``` $ aws ec2 describe-spot-price-history --dry-run ``` El resultado indica si el comando tenía el formato correcto o no. Este comando también incluye una versión `--no-dry-run` del parámetro que puede utilizarse para indicar de forma explícita que el comando debe ejecutarse con normalidad, aunque no es necesario incluirlo, ya que este es el comportamiento predeterminado. ## Entero Un número entero sin firma. ``` $ aws ec2 describe-spot-price-history --max-items 5 ``` ## Binario/blob (objeto binario grande) y blob en streaming En la AWS CLI, puede pasar un valor binario como una cadena directamente en la línea de comandos. Existen dos tipos de blobs: + [Blob](#parameter-type-blob) + [Blob de streaming](#parameter-type-streaming-blob) ### Blob Para pasar un valor a un parámetro con el tipo `blob`, debe especificar una ruta a un archivo local que contenga los datos binarios mediante el prefijo `fileb://`. Los archivos a los que se hace referencia mediante el prefijo `fileb://` siempre se tratan como binarios sin codificar. La ruta especificada se interpreta como una ruta relativa al directorio de trabajo actual. Por ejemplo, el parámetro `--plaintext` para `aws kms encrypt` es un blob. ``` $ aws kms encrypt \ --key-id 1234abcd-12ab-34cd-56ef-1234567890ab \ --plaintext fileb://ExamplePlaintextFile \ --output text \ --query CiphertextBlob | base64 \ --decode > ExampleEncryptedFile ``` **nota** Por compatibilidad con versiones anteriores, puede utilizar el prefijo `file://`. Se utilizan dos formatos en función de la configuración de archivo `cli\$1binary\$1format` o de la opción de la línea de comandos `--cli-binary-format`: Predeterminado para la AWS CLI versión 2. Si el valor de la configuración es `base64`, los archivos a los que se hace referencia mediante el prefijo `file://` se tratan como texto codificado en base64. Predeterminado para la AWS CLI versión 1. Si el valor de la configuración es `raw-in-base64-out`, los archivos a los que se hace referencia mediante el prefijo `file://` se leen como texto y, a continuación, la AWS CLI intenta codificarlo en binario. Para obtener más información, consulte la configuración de archivo `cli\$1binary\$1format` o la opción de la línea de comandos `--cli-binary-format`. ### Blob de streaming Los blobs de streaming como `aws cloudsearchdomain upload-documents` no utilizan prefijos. En cambio, los parámetros de blob de streaming se formatean mediante la ruta de archivo directa. En el siguiente ejemplo se utiliza la ruta de archivo directa `document-batch.json` para el comando `aws cloudsearchdomain upload-documents`: ``` $ aws cloudsearchdomain upload-documents \ --endpoint-url https://doc-my-domain.us-west-1.cloudsearch.amazonaws.com \ --content-type application/json \ --documents document-batch.json ``` ## Asignación Un conjunto de pares de clave-valor especificado en JSON o mediante la [sintaxis abreviada](cli-usage-shorthand.md) de la CLI. En el siguiente ejemplo de JSON, se lee un elemento de una tabla de Amazon DynamoDB denominada *my-table* con un parámetro de mapa, `--key`. El parámetro especifica la clave principal denominada *id* con un valor numérico de *1* en una estructura JSON anidada. Para conocer un uso más avanzado de JSON en una línea de comandos, considere usar un procesador JSON de línea de comandos, como`jq`, para crear cadenas JSON. Para obtener más información sobre `jq`, consulte el [repositorio jq](http://stedolan.github.io/jq/) en *GitHub*. ``` $ aws dynamodb get-item --table-name my-table --key '{"id": {"N":"1"}}' { "Item": { "name": { "S": "John" }, "id": { "N": "1" } } } ``` ## Documento **nota** La [sintaxis abreviada](cli-usage-shorthand.md) no es compatible con los tipos de documento. Los tipos de documento se utilizan para enviar datos sin necesidad de integrar JSON‎ dentro de cadenas. El tipo de documento permite a los servicios proporcionar esquemas arbitrarios para que utilice tipos de datos más flexibles. Esto permite enviar datos JSON sin necesidad de valores de escape. Por ejemplo, en lugar de utilizar la siguiente entrada JSON de escape: ``` {"document": "{\"key\":true}"} ``` Puede utilizar el tipo de documento que se muestra a continuación: ``` {"document": {"key": true}} ``` ### Valores válidos para tipos de documentos Debido a la naturaleza flexible de los tipos de documentos, existen varios tipos de valores válidos. Entre los valores válidos se incluyen los siguientes: **Cadena** ``` --option '"value"' ``` **Número** ``` --option 123 --option 123.456 ``` **Booleano** ``` --option true ``` **Nulo** ``` --option null ``` **Matriz** ``` --option '["value1", "value2", "value3"]' --option '["value", 1, true, null, ["key1", 2.34], {"key2": "value2"}]' ``` **Objeto** ``` --option '{"key": "value"}' --option '{"key1": "value1", "key2": 123, "key3": true, "key4": null, "key5": ["value3", "value4"], "key6": {"value5": "value6"}' ``` # Entrecomillado de cadenas y uso de literales en la AWS CLI Hay dos maneras principales en las que se usan comillas simples y dobles en el AWS CLI. + [Usar comillas alrededor de cadenas que contienen espacios en blanco](#cli-usage-parameters-quoting-strings-around) + [Uso de comillas dentro de cadenas](#cli-usage-parameters-quoting-strings-containing) ## Usar comillas alrededor de cadenas que contienen espacios en blanco Los nombres de los parámetros y sus valores están separados por espacios en la línea de comandos. Si un valor de cadena contiene un espacio incrustado, debe rodear toda la cadena con comillas para evitar que la AWS CLI malinterprete el espacio como un divisor entre el valor y el siguiente nombre del parámetro. El tipo de comillas que utilice depende del sistema operativo en el que esté ejecutando la AWS CLI. ------ #### [ Linux and macOS ] Uso de comillas simples `' '` ``` $ aws ec2 create-key-pair --key-name 'my key pair' ``` Para obtener más información sobre el uso de las comillas, consulte documentación del usuario de su shell preferido. ------ #### [ PowerShell ] **Comillas simples (recomendadas)** Las marcas de comillas simples `' '` se llaman cadenas `verbatim`. La cadena se pasa al comando exactamente como se escribe, lo que significa que las variables de PowerShell no pasarán. ``` PS C:\> aws ec2 create-key-pair --key-name 'my key pair' ``` **Comillas dobles** Las marcas de comillas dobles `" "` se llaman cadenas `expandable`. Las variables se pueden pasar en cadenas expandibles. ``` PS C:\> aws ec2 create-key-pair --key-name "my key pair" ``` Para obtener más información sobre el uso de las comillas, consulte [Acerca de las reglas de entrecomillado](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_quoting_rules?view=powershell-7) en los *Documentos de Microsoft PowerShell*. ------ #### [ Windows command prompt ] Uso de comillas dobles `" "` . ``` C:\> aws ec2 create-key-pair --key-name "my key pair" ``` ------ Si lo desea, puede separar el nombre del parámetro del valor con un signo de igual `=` en lugar de un espacio. Normalmente, esto solo es necesario si el valor del parámetro comienza con un guion. ``` $ aws ec2 delete-key-pair --key-name=-mykey ``` ## Uso de comillas dentro de cadenas Las cadenas pueden contener comillas y el shell puede requerir comillas de cierre para que funcionen correctamente. Uno de los tipos de valor de parámetro comunes es una cadena JSON. Esto es complejo, ya que incluye espacios y comillas dobles `" "` alrededor de cada nombre de elemento y valor en la estructura JSON. El modo en que introduzca parámetros con formato JSON en la línea de comandos varía en función de su sistema operativo. Para conocer un uso más avanzado de JSON en la línea de comandos, considere usar un procesador JSON de línea de comandos, como`jq`, para crear cadenas JSON. Para obtener más información sobre `jq`, consulte el [repositorio jq](http://stedolan.github.io/jq/) en *GitHub*. ------ #### [ Linux and macOS ] Para que Linux y macOS interpreten cadenas en forma literal, use comillas simples `' '` para entrecomillar la estructura de datos JSON, como en el siguiente ejemplo. No necesita cerrar las comillas dobles incrustadas en la cadena JSON, ya que se las trata de manera literal. Dado que la cadena JSON está encerrada entre comillas simples, se deberá cerrar cualquier comilla simple en la cadena. Esto generalmente se logra usando una barra diagonal inversa antes de la comilla simple `\'`. ``` $ aws ec2 run-instances \ --image-id ami-12345678 \ --block-device-mappings '[{"DeviceName":"/dev/sdb","Ebs":{"VolumeSize":20,"DeleteOnTermination":false,"VolumeType":"standard"}}]' ``` Para obtener más información sobre el uso de las comillas, consulte documentación del usuario de su shell preferido. ------ #### [ PowerShell ] Utilice comillas simples `' '` o comillas dobles `" "`. **Comillas simples (recomendadas)** Las marcas de comillas simples `' '` se llaman cadenas `verbatim`. La cadena se pasa al comando exactamente como se escribe, lo que significa que las variables de PowerShell no pasarán. Dado que las estructuras de datos JSON incluyen comillas dobles, sugerimos comillas **simples** `' '` para encerrarlas. Si usa comillas **simples**, no necesita cerrar las comillas **dobles** incrustadas en la cadena JSON. Sin embargo, debe cerrar cada comilla **simple** con una tilde invertido ``` dentro de la estructura JSON. ``` PS C:\> aws ec2 run-instances ` --image-id ami-12345678 ` --block-device-mappings '[{"DeviceName":"/dev/sdb","Ebs":{"VolumeSize":20,"DeleteOnTermination":false,"VolumeType":"standard"}}]' ``` **Comillas dobles** Las marcas de comillas dobles `" "` se llaman cadenas `expandable`. Las variables se pueden pasar en cadenas expandibles. Si usa comillas **dobles**, no necesita cerrar las comillas **simples** incrustadas en la cadena JSON. Sin embargo, debe cerrar cada comilla **doble** con un acento grave ``` dentro de la estructura JSON, como con el siguiente ejemplo. ``` PS C:\> aws ec2 run-instances ` --image-id ami-12345678 ` --block-device-mappings "[{`"DeviceName`":`"/dev/sdb`",`"Ebs`":{`"VolumeSize`":20,`"DeleteOnTermination`":false,`"VolumeType`":`"standard`"}}]" ``` Para obtener más información sobre el uso de las comillas, consulte [Acerca de las reglas de entrecomillado](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_quoting_rules?view=powershell-7) en los *Documentos de Microsoft PowerShell*. **aviso** Antes de que PowerShell envíe un comando a la AWS CLI, determina si su comando se interpreta usando PowerShell típico o reglas de entrecomillado de `CommandLineToArgvW`. Cuando PowerShell procesa mediante `CommandLineToArgvW`, deben escaparse los caracteres con una barra invertida `\`. Para obtener más información sobre `CommandLineToArgvW` en PowerShell, consulte [¿Qué pasa con el extraño tratamiento de comillas y barras invertidas por CommandLineToArgVW?](https://devblogs.microsoft.com/oldnewthing/20100917-00/?p=12833) en *Microsoft DevBlogs*, [Todos citan los argumentos de la línea de comandos de forma incorrecta](https://docs.microsoft.com/en-us/archive/blogs/twistylittlepassagesallalike/everyone-quotes-command-line-arguments-the-wrong-way) en *Microsoft Docs Blog* y[Función CommandLineToArgVW](https://docs.microsoft.com/en-us/windows/win32/api/shellapi/nf-shellapi-commandlinetoargvw#remarks) en los *Documentos de Microsoft*. **Comillas simples** Las marcas de comillas simples `' '` se llaman cadenas `verbatim`. La cadena se pasa al comando exactamente como se escribe, lo que significa que las variables de PowerShell no pasarán. Los caracteres se escapan con una barra invertida`\`. ``` PS C:\> aws ec2 run-instances ` --image-id ami-12345678 ` --block-device-mappings '[{\"DeviceName\":\"/dev/sdb\",\"Ebs\":{\"VolumeSize\":20,\"DeleteOnTermination\":false,\"VolumeType\":\"standard\"}}]' ``` **Comillas dobles** Las marcas de comillas dobles `" "` se llaman cadenas `expandable`. Las variables se pueden pasar en cadenas `expandable`. Para cadenas con comillas dobles, tiene que escapar dos veces usando *`\$1* para cada comilla en lugar de usar solo un signo de acento. La barra invertida escapa la barra invertida y, a continuación, la barra invertida se utiliza como un carácter de escape para proceso `CommandLineToArgvW`. ``` PS C:\> aws ec2 run-instances ` --image-id ami-12345678 ` --block-device-mappings "[{`\"DeviceName`\":`\"/dev/sdb`\",`\"Ebs`\":{`\"VolumeSize`\":20,`\"DeleteOnTermination`\":false,`\"VolumeType`\":`\"standard`\"}}]" ``` **Blobs (recomendado)** Para omitir las reglas de entrecomillado de PowerShell para la entrada de datos JSON, use Blobs para pasar los datos JSON directamente a la AWS CLI. Para obtener más información acerca de Blobs, consulte o [Blob](cli-usage-parameters-types.md#parameter-type-blob). ------ #### [ Windows command prompt ] El símbolo del sistema de Windows requiere comillas dobles `" "` para entrecomillar la estructura de datos JSON. Además, para evitar que el procesador de comandos malinterprete las comillas dobles incrustadas en el JSON, también debe cerrar (precedido por un carácter de barra invertida `\`) cada comilla doble `"` dentro de la propia estructura de datos JSON, como en el siguiente ejemplo. ``` C:\> aws ec2 run-instances ^ --image-id ami-12345678 ^ --block-device-mappings "[{\"DeviceName\":\"/dev/sdb\",\"Ebs\":{\"VolumeSize\":20,\"DeleteOnTermination\":false,\"VolumeType\":\"standard\"}}]" ``` El único caso en el que no se utiliza el carácter de cierre es con las comillas dobles de los extremos. ------ # Carga de un parámetro de un archivo en la AWS CLI Algunos parámetros esperan nombres de archivo como argumentos, desde los que la AWS CLI carga los datos. Otros parámetros le permiten especificar el valor del parámetro como texto escrito en la línea de comandos o leído de un archivo. Tanto si un archivo es obligatorio como si es opcional, debe codificarlo correctamente para que la AWS CLI pueda entenderlo. La codificación del archivo debe coincidir con la configuración regional predeterminada del sistema de lectura. Esto se puede determinar utilizando el método Python `locale.getpreferredencoding()`. Este método sirve para cargar un archivo para un único parámetro. Para obtener información sobre la carga de varios parámetros con un único archivo, consulte [Esqueletos de la AWS CLI y archivos de entrada en la AWS CLI](cli-usage-skeleton.md). **nota** De forma predeterminada, Windows PowerShell genera texto como UTF-16, lo que está en conflicto con la codificación UTF-8 utilizada por archivos JSON y muchos sistemas Linux. Le recomendamos que utilice `-Encoding ascii` con los comandos `Out-File` de PowerShell para asegurarse de que la AWS CLI puede leer el archivo resultante. **Topics** + [Cómo cargar un parámetro de un archivo](#cli-usage-parameters-file-how) + [Archivos binarios](#cli-usage-parameters-file-binary) + [Carga de un archivo como un valor sintáctico abreviado](#cli-usage-parameters-file-shorthand) ## Cómo cargar un parámetro de un archivo En ocasiones, resulta conveniente cargar el valor de un parámetro desde un archivo en lugar de intentar escribirlo como un valor de parámetro de la línea de comandos, como, por ejemplo, cuando el parámetro es una cadena JSON compleja. Para especificar un archivo que contenga el valor, especifique la URL del archivo con el siguiente formato. ``` file://complete/path/to/file ``` + Los dos primeros caracteres de barra inclinada "/" forman parte de la especificación. Si la ruta requerida comienza con '/', el resultado será tres caracteres de barra inclinada: `file:///folder/file`. + La dirección URL proporciona la ruta al archivo que incluye el contenido del parámetro real. + Cuando se utilizan archivos con espacios o caracteres especiales, siga las [normas de escape y entrecomillado](cli-usage-parameters-quoting-strings.md) para el terminal. Las rutas de archivo en los siguientes ejemplos se interpretan como rutas relativas al directorio de trabajo actual. ------ #### [ Linux or macOS ] ``` // Read from a file in the current directory $ aws ec2 describe-instances --filters file://filter.json // Read from a file in /tmp $ aws ec2 describe-instances --filters file:///tmp/filter.json // Read from a file with a filename with whitespaces $ aws ec2 describe-instances --filters 'file://filter content.json' ``` ------ #### [ Windows command prompt ] ``` // Read from a file in C:\temp C:\> aws ec2 describe-instances --filters file://C:\temp\filter.json // Read from a file with a filename with whitespaces C:\> aws ec2 describe-instances --filters "file://C:\temp\filter content.json" ``` ------ La opción de prefijo `file://` admite ampliaciones tipo Unix, incluidas "`~/`", "`./`" y "`../`". En Windows, la expresión "`~/`" se amplía a su directorio de usuarios, guardado en la variable de entorno `%USERPROFILE%`. Por ejemplo, en Windows 10 normalmente tendría un directorio de usuarios en `%USERPROFILE%`. Debe añadir el carácter de escape a los documentos JSON que están integrados como valor de otro documento JSON. ``` $ aws sqs create-queue --queue-name my-queue --attributes file://attributes.json ``` **attributes.json** ``` { "RedrivePolicy": "{\"deadLetterTargetArn\":\"arn:aws:sqs:us-west-2:0123456789012:deadletter\", \"maxReceiveCount\":\"5\"}" } ``` ## Archivos binarios Para los comandos que toman datos binarios como un parámetro, especifique que los datos son contenido binario utilizando el prefijo `fileb://`. Los comandos que aceptan datos binarios son: + **`aws ec2 run-instances:`** `--user-data` parámetro . + **`aws s3api put-object:`** `--sse-customer-key` parámetro . + **`aws kms decrypt:`** `--ciphertext-blob` parámetro . En el siguiente ejemplo, se genera una clave AES binaria de 256 bits utilizando una herramienta de línea de comandos de Linux y después se proporciona dicha clave a Amazon S3 para cifrar un archivo cargado en el lado del servidor. ``` $ dd if=/dev/urandom bs=1 count=32 > sse.key 32+0 records in 32+0 records out 32 bytes (32 B) copied, 0.000164441 s, 195 kB/s $ aws s3api put-object \ --bucket amzn-s3-demo-bucket \ --key test.txt \ --body test.txt \ --sse-customer-key fileb://sse.key \ --sse-customer-algorithm AES256 { "SSECustomerKeyMD5": "iVg8oWa8sy714+FjtesrJg==", "SSECustomerAlgorithm": "AES256", "ETag": "\"a6118e84b76cf98bf04bbe14b6045c6c\"" } ``` Por ver otro ejemplo que haga referencia a un archivo que contenga parámetros con formato JSON, consulte [Asociación de una política administrada de IAM a un usuario](cli-services-iam.md#cli-services-iam-policy). ## Carga de un archivo como un valor sintáctico abreviado Cuando se utiliza una sintaxis abreviada en la que un valor es grande o complejo, suele ser más fácil cargarlo en un archivo como un valor. Para cargar un archivo como un valor sintáctico abreviado, el formato cambiará ligeramente. En lugar de `key=value`, usará el operador `@=`, en lugar del operador `=`. El valor `@=` se refiere a la AWS CLI que el valor se debe leer como una ruta de archivo y no como una cadena. En el siguiente ejemplo se muestra un par clave-valor que carga un archivo por su valor. ------ #### [ Linux or macOS ] ``` --option key@=file://template.txt ``` ------ #### [ Windows ] ``` --option "key1@=file://template.txt" ``` ------ En el siguiente ejemplo, se muestra la carga de un archivo de certificado para el comando `aws rolesanywhere create-trust-anchor`. ``` $ aws rolesanywhere create-trust-anchor --name TrustAnchor \ --source sourceData={x509CertificateData@=file://root-ca.crt},sourceType="CERTIFICATE_BUNDLE" \ --enabled ``` Para obtener más información sobre la sintaxis abreviada, consulte [Uso de la sintaxis abreviada en la AWS CLI](cli-usage-shorthand.md). # Esqueletos de la AWS CLI y archivos de entrada en la AWS CLI La mayoría de los comandos de la AWS CLI aceptan la importación de las entradas de parámetros de un archivo. Estas plantillas se pueden generar con la opción `generate-cli-skeleton` y, a continuación, se pueden importar con los parámetros `--cli-input-json` y `--cli-input-yaml`. **Topics** + [Sobre esqueletos y archivos de ‎entrada de AWS CLI](#cli-usage-skeleton-about) + [Generación e importación de un esqueleto de comandos](#cli-usage-skeleton-generate) + [Combinación de archivos de entrada y parámetros de línea de comandos](#cli-usage-skeleton-combine) ## Sobre esqueletos y archivos de ‎entrada de AWS CLI ‎La mayoría de los comandos de AWS Command Line Interface (AWS CLI) pueden aceptar las entradas de parámetros desde un archivo con los parámetros ‎`--cli-input-json` y `--cli-input-yaml`. Esos mismos comandos usan el parámetro `--generate-cli-skeleton` para generar un archivo en formato JSON o YAML con todos los parámetros que pueda editar y completar. ‎A continuación, puede ejecutar el comando con el parámetro `--cli-input-json` o `--cli-input-yaml` y apuntar al archivo cumplimentado. **importante** Los comandos de la AWS CLI personalizados, como los [comandos `aws s3`](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3/index.html) no admiten los parámetros `--generate-cli-skeleton` o `--cli-input-json` y `--cli-input-yaml` descritos en este tema. Para comprobar si un comando específico admite estos parámetros, ejecute el [comando `help`](cli-usage-help.md#cli-usage-help-command) correspondiente al comando que desee utilizar o consulte la [guía de referencia de la versión 2 de AWS CLI](https://docs.aws.amazon.com/cli/latest/reference/index.html). `--generate-cli-skeleton` genera y muestra una plantilla de parámetros que puede personalizar y utilizar como entrada en un comando. La plantilla generada incluye todos los parámetros que admite el comando. El parámetro `--generate-cli-skeleton` acepta uno de los siguientes valores: + `input`: la plantilla generada incluye todos los parámetros de entrada formateados como JSON. Este es el valor predeterminado. + `yaml-input`: la plantilla generada incluye todos los parámetros de entrada formateados como YAML. + `output` – la plantilla generada incluye todos los parámetros de salida formateados como JSON. Actualmente, no puede solicitar los parámetros de salida en formato YAML. Como la AWS CLI es esencialmente un "encapsulador" de la API del servicio, el archivo de esqueleto espera que el usuario haga referencia a todos los parámetros utilizando los nombres de parámetro de la API subyacente. Es probable que este nombre sea distinto al nombre del parámetro de la AWS CLI. Por ejemplo, un parámetro de la AWS CLI llamado `user-name` podría corresponderse con un parámetro de la API de servicio de AWS llamado `UserName` (observe cómo se usan las mayúsculas y que falta un guion). Le recomendamos que utilice la opción `--generate-cli-skeleton` para generar la plantilla con los nombres de parámetros "correctos" con el fin de evitar errores. Puede hacer referencia a la Guía de referencia de la API del servicio para ver los nombres de los parámetros esperados. Puede eliminar cualquier parámetro de la plantilla que no sea necesario y para el que no desee proporcionar un valor. Por ejemplo, si ejecuta el siguiente comando, se genera la plantilla de parámetros para el comando Amazon Elastic Compute Cloud (Amazon EC2) **run-instances**. ------ #### [ JSON ] En el siguiente ejemplo, se muestra cómo se genera una plantilla con formato JSON utilizando el valor predeterminado (`input`) en el parámetro `--generate-cli-skeleton`. ``` $ aws ec2 run-instances --generate-cli-skeleton ``` ``` { "DryRun": true, "ImageId": "", "MinCount": 0, "MaxCount": 0, "KeyName": "", "SecurityGroups": [ "" ], "SecurityGroupIds": [ "" ], "UserData": "", "InstanceType": "", "Placement": { "AvailabilityZone": "", "GroupName": "", "Tenancy": "" }, "KernelId": "", "RamdiskId": "", "BlockDeviceMappings": [ { "VirtualName": "", "DeviceName": "", "Ebs": { "SnapshotId": "", "VolumeSize": 0, "DeleteOnTermination": true, "VolumeType": "", "Iops": 0, "Encrypted": true }, "NoDevice": "" } ], "Monitoring": { "Enabled": true }, "SubnetId": "", "DisableApiTermination": true, "InstanceInitiatedShutdownBehavior": "", "PrivateIpAddress": "", "ClientToken": "", "AdditionalInfo": "", "NetworkInterfaces": [ { "NetworkInterfaceId": "", "DeviceIndex": 0, "SubnetId": "", "Description": "", "PrivateIpAddress": "", "Groups": [ "" ], "DeleteOnTermination": true, "PrivateIpAddresses": [ { "PrivateIpAddress": "", "Primary": true } ], "SecondaryPrivateIpAddressCount": 0, "AssociatePublicIpAddress": true } ], "IamInstanceProfile": { "Arn": "", "Name": "" }, "EbsOptimized": true } ``` ------ #### [ YAML ] En el ejemplo siguiente, se muestra cómo se genera una plantilla con formato YAML utilizando el valor `yaml-input` en el parámetro `--generate-cli-skeleton`. ``` $ aws ec2 run-instances --generate-cli-skeleton yaml-input ``` ``` BlockDeviceMappings: # The block device mapping entries. - DeviceName: '' # The device name (for example, /dev/sdh or xvdh). VirtualName: '' # The virtual device name (ephemeralN). Ebs: # Parameters used to automatically set up Amazon EBS volumes when the instance is launched. DeleteOnTermination: true # Indicates whether the EBS volume is deleted on instance termination. Iops: 0 # The number of I/O operations per second (IOPS) that the volume supports. SnapshotId: '' # The ID of the snapshot. VolumeSize: 0 # The size of the volume, in GiB. VolumeType: st1 # The volume type. Valid values are: standard, io1, gp2, sc1, st1. Encrypted: true # Indicates whether the encryption state of an EBS volume is changed while being restored from a backing snapshot. KmsKeyId: '' # Identifier (key ID, key alias, ID ARN, or alias ARN) for a customer managed KMS key under which the EBS volume is encrypted. NoDevice: '' # Suppresses the specified device included in the block device mapping of the AMI. ImageId: '' # The ID of the AMI. InstanceType: c4.4xlarge # The instance type. Valid values are: t1.micro, t2.nano, t2.micro, t2.small, t2.medium, t2.large, t2.xlarge, t2.2xlarge, t3.nano, t3.micro, t3.small, t3.medium, t3.large, t3.xlarge, t3.2xlarge, t3a.nano, t3a.micro, t3a.small, t3a.medium, t3a.large, t3a.xlarge, t3a.2xlarge, m1.small, m1.medium, m1.large, m1.xlarge, m3.medium, m3.large, m3.xlarge, m3.2xlarge, m4.large, m4.xlarge, m4.2xlarge, m4.4xlarge, m4.10xlarge, m4.16xlarge, m2.xlarge, m2.2xlarge, m2.4xlarge, cr1.8xlarge, r3.large, r3.xlarge, r3.2xlarge, r3.4xlarge, r3.8xlarge, r4.large, r4.xlarge, r4.2xlarge, r4.4xlarge, r4.8xlarge, r4.16xlarge, r5.large, r5.xlarge, r5.2xlarge, r5.4xlarge, r5.8xlarge, r5.12xlarge, r5.16xlarge, r5.24xlarge, r5.metal, r5a.large, r5a.xlarge, r5a.2xlarge, r5a.4xlarge, r5a.8xlarge, r5a.12xlarge, r5a.16xlarge, r5a.24xlarge, r5d.large, r5d.xlarge, r5d.2xlarge, r5d.4xlarge, r5d.8xlarge, r5d.12xlarge, r5d.16xlarge, r5d.24xlarge, r5d.metal, r5ad.large, r5ad.xlarge, r5ad.2xlarge, r5ad.4xlarge, r5ad.8xlarge, r5ad.12xlarge, r5ad.16xlarge, r5ad.24xlarge, x1.16xlarge, x1.32xlarge, x1e.xlarge, x1e.2xlarge, x1e.4xlarge, x1e.8xlarge, x1e.16xlarge, x1e.32xlarge, i2.xlarge, i2.2xlarge, i2.4xlarge, i2.8xlarge, i3.large, i3.xlarge, i3.2xlarge, i3.4xlarge, i3.8xlarge, i3.16xlarge, i3.metal, i3en.large, i3en.xlarge, i3en.2xlarge, i3en.3xlarge, i3en.6xlarge, i3en.12xlarge, i3en.24xlarge, i3en.metal, hi1.4xlarge, hs1.8xlarge, c1.medium, c1.xlarge, c3.large, c3.xlarge, c3.2xlarge, c3.4xlarge, c3.8xlarge, c4.large, c4.xlarge, c4.2xlarge, c4.4xlarge, c4.8xlarge, c5.large, c5.xlarge, c5.2xlarge, c5.4xlarge, c5.9xlarge, c5.12xlarge, c5.18xlarge, c5.24xlarge, c5.metal, c5d.large, c5d.xlarge, c5d.2xlarge, c5d.4xlarge, c5d.9xlarge, c5d.18xlarge, c5n.large, c5n.xlarge, c5n.2xlarge, c5n.4xlarge, c5n.9xlarge, c5n.18xlarge, cc1.4xlarge, cc2.8xlarge, g2.2xlarge, g2.8xlarge, g3.4xlarge, g3.8xlarge, g3.16xlarge, g3s.xlarge, g4dn.xlarge, g4dn.2xlarge, g4dn.4xlarge, g4dn.8xlarge, g4dn.12xlarge, g4dn.16xlarge, cg1.4xlarge, p2.xlarge, p2.8xlarge, p2.16xlarge, p3.2xlarge, p3.8xlarge, p3.16xlarge, p3dn.24xlarge, d2.xlarge, d2.2xlarge, d2.4xlarge, d2.8xlarge, f1.2xlarge, f1.4xlarge, f1.16xlarge, m5.large, m5.xlarge, m5.2xlarge, m5.4xlarge, m5.8xlarge, m5.12xlarge, m5.16xlarge, m5.24xlarge, m5.metal, m5a.large, m5a.xlarge, m5a.2xlarge, m5a.4xlarge, m5a.8xlarge, m5a.12xlarge, m5a.16xlarge, m5a.24xlarge, m5d.large, m5d.xlarge, m5d.2xlarge, m5d.4xlarge, m5d.8xlarge, m5d.12xlarge, m5d.16xlarge, m5d.24xlarge, m5d.metal, m5ad.large, m5ad.xlarge, m5ad.2xlarge, m5ad.4xlarge, m5ad.8xlarge, m5ad.12xlarge, m5ad.16xlarge, m5ad.24xlarge, h1.2xlarge, h1.4xlarge, h1.8xlarge, h1.16xlarge, z1d.large, z1d.xlarge, z1d.2xlarge, z1d.3xlarge, z1d.6xlarge, z1d.12xlarge, z1d.metal, u-6tb1.metal, u-9tb1.metal, u-12tb1.metal, u-18tb1.metal, u-24tb1.metal, a1.medium, a1.large, a1.xlarge, a1.2xlarge, a1.4xlarge, a1.metal, m5dn.large, m5dn.xlarge, m5dn.2xlarge, m5dn.4xlarge, m5dn.8xlarge, m5dn.12xlarge, m5dn.16xlarge, m5dn.24xlarge, m5n.large, m5n.xlarge, m5n.2xlarge, m5n.4xlarge, m5n.8xlarge, m5n.12xlarge, m5n.16xlarge, m5n.24xlarge, r5dn.large, r5dn.xlarge, r5dn.2xlarge, r5dn.4xlarge, r5dn.8xlarge, r5dn.12xlarge, r5dn.16xlarge, r5dn.24xlarge, r5n.large, r5n.xlarge, r5n.2xlarge, r5n.4xlarge, r5n.8xlarge, r5n.12xlarge, r5n.16xlarge, r5n.24xlarge. Ipv6AddressCount: 0 # [EC2-VPC] The number of IPv6 addresses to associate with the primary network interface. Ipv6Addresses: # [EC2-VPC] The IPv6 addresses from the range of the subnet to associate with the primary network interface. - Ipv6Address: '' # The IPv6 address. KernelId: '' # The ID of the kernel. KeyName: '' # The name of the key pair. MaxCount: 0 # [REQUIRED] The maximum number of instances to launch. MinCount: 0 # [REQUIRED] The minimum number of instances to launch. Monitoring: # Specifies whether detailed monitoring is enabled for the instance. Enabled: true # [REQUIRED] Indicates whether detailed monitoring is enabled. Placement: # The placement for the instance. AvailabilityZone: '' # The Availability Zone of the instance. Affinity: '' # The affinity setting for the instance on the Dedicated Host. GroupName: '' # The name of the placement group the instance is in. PartitionNumber: 0 # The number of the partition the instance is in. HostId: '' # The ID of the Dedicated Host on which the instance resides. Tenancy: dedicated # The tenancy of the instance (if the instance is running in a VPC). Valid values are: default, dedicated, host. SpreadDomain: '' # Reserved for future use. RamdiskId: '' # The ID of the RAM disk to select. SecurityGroupIds: # The IDs of the security groups. - '' SecurityGroups: # [default VPC] The names of the security groups. - '' SubnetId: '' # [EC2-VPC] The ID of the subnet to launch the instance into. UserData: '' # The user data to make available to the instance. AdditionalInfo: '' # Reserved. ClientToken: '' # Unique, case-sensitive identifier you provide to ensure the idempotency of the request. DisableApiTermination: true # If you set this parameter to true, you can't terminate the instance using the Amazon EC2 console, CLI, or API; otherwise, you can. DryRun: true # Checks whether you have the required permissions for the action, without actually making the request, and provides an error response. EbsOptimized: true # Indicates whether the instance is optimized for Amazon EBS I/O. IamInstanceProfile: # The IAM instance profile. Arn: '' # The Amazon Resource Name (ARN) of the instance profile. Name: '' # The name of the instance profile. InstanceInitiatedShutdownBehavior: stop # Indicates whether an instance stops or terminates when you initiate shutdown from the instance (using the operating system command for system shutdown). Valid values are: stop, terminate. NetworkInterfaces: # The network interfaces to associate with the instance. - AssociatePublicIpAddress: true # Indicates whether to assign a public IPv4 address to an instance you launch in a VPC. DeleteOnTermination: true # If set to true, the interface is deleted when the instance is terminated. Description: '' # The description of the network interface. DeviceIndex: 0 # The position of the network interface in the attachment order. Groups: # The IDs of the security groups for the network interface. - '' Ipv6AddressCount: 0 # A number of IPv6 addresses to assign to the network interface. Ipv6Addresses: # One or more IPv6 addresses to assign to the network interface. - Ipv6Address: '' # The IPv6 address. NetworkInterfaceId: '' # The ID of the network interface. PrivateIpAddress: '' # The private IPv4 address of the network interface. PrivateIpAddresses: # One or more private IPv4 addresses to assign to the network interface. - Primary: true # Indicates whether the private IPv4 address is the primary private IPv4 address. PrivateIpAddress: '' # The private IPv4 addresses. SecondaryPrivateIpAddressCount: 0 # The number of secondary private IPv4 addresses. SubnetId: '' # The ID of the subnet associated with the network interface. InterfaceType: '' # The type of network interface. PrivateIpAddress: '' # [EC2-VPC] The primary IPv4 address. ElasticGpuSpecification: # An elastic GPU to associate with the instance. - Type: '' # [REQUIRED] The type of Elastic Graphics accelerator. ElasticInferenceAccelerators: # An elastic inference accelerator to associate with the instance. - Type: '' # [REQUIRED] The type of elastic inference accelerator. TagSpecifications: # The tags to apply to the resources during launch. - ResourceType: network-interface # The type of resource to tag. Valid values are: client-vpn-endpoint, customer-gateway, dedicated-host, dhcp-options, elastic-ip, fleet, fpga-image, host-reservation, image, instance, internet-gateway, launch-template, natgateway, network-acl, network-interface, reserved-instances, route-table, security-group, snapshot, spot-instances-request, subnet, traffic-mirror-filter, traffic-mirror-session, traffic-mirror-target, transit-gateway, transit-gateway-attachment, transit-gateway-route-table, volume, vpc, vpc-peering-connection, vpn-connection, vpn-gateway. Tags: # The tags to apply to the resource. - Key: '' # The key of the tag. Value: '' # The value of the tag. LaunchTemplate: # The launch template to use to launch the instances. LaunchTemplateId: '' # The ID of the launch template. LaunchTemplateName: '' # The name of the launch template. Version: '' # The version number of the launch template. InstanceMarketOptions: # The market (purchasing) option for the instances. MarketType: spot # The market type. Valid values are: spot. SpotOptions: # The options for Spot Instances. MaxPrice: '' # The maximum hourly price you're willing to pay for the Spot Instances. SpotInstanceType: one-time # The Spot Instance request type. Valid values are: one-time, persistent. BlockDurationMinutes: 0 # The required duration for the Spot Instances (also known as Spot blocks), in minutes. ValidUntil: 1970-01-01 00:00:00 # The end date of the request. InstanceInterruptionBehavior: terminate # The behavior when a Spot Instance is interrupted. Valid values are: hibernate, stop, terminate. CreditSpecification: # The credit option for CPU usage of the T2 or T3 instance. CpuCredits: '' # [REQUIRED] The credit option for CPU usage of a T2 or T3 instance. CpuOptions: # The CPU options for the instance. CoreCount: 0 # The number of CPU cores for the instance. ThreadsPerCore: 0 # The number of threads per CPU core. CapacityReservationSpecification: # Information about the Capacity Reservation targeting option. CapacityReservationPreference: none # Indicates the instance's Capacity Reservation preferences. Valid values are: open, none. CapacityReservationTarget: # Information about the target Capacity Reservation. CapacityReservationId: '' # The ID of the Capacity Reservation. HibernationOptions: # Indicates whether an instance is enabled for hibernation. Configured: true # If you set this parameter to true, your instance is enabled for hibernation. LicenseSpecifications: # The license configurations. - LicenseConfigurationArn: '' # The Amazon Resource Name (ARN) of the license configuration. ``` ------ ## Generación e importación de un esqueleto de comandos **Para generar y utilizar un archivo de esqueleto de parámetros** 1. ‎Ejecute el comando con el pa‎rámetro `--generate-cli-skeleton` para producir la salida en formato JSON o YAML y dirigirla a un archivo para guardarla. ------ #### [ JSON ] ``` $ aws ec2 run-instances --generate-cli-skeleton input > ec2runinst.json ``` ------ #### [ YAML ] ``` $ aws ec2 run-instances --generate-cli-skeleton yaml-input > ec2runinst.yaml ``` ------ 1. Abra el archivo de esqueleto de parámetros en el editor de texto y quite todos los parámetros que no necesite. Por ejemplo, puede reducir la plantilla hasta dejarla tal y como se muestra a continuación. Confirme que el código JSON‎ o YAML del archivo sigue siendo válido después de eliminar los elementos que no necesita. ------ #### [ JSON ] ``` { "DryRun": true, "ImageId": "", "KeyName": "", "SecurityGroups": [ "" ], "InstanceType": "", "Monitoring": { "Enabled": true } } ``` ------ #### [ YAML ] ``` DryRun: true ImageId: '' KeyName: '' SecurityGroups: - '' InstanceType: Monitoring: Enabled: true ``` ------ En este ejemplo, dejamos el parámetro `DryRun` establecido en `true` para utilizar la característica “dry run” (simulacro) de Amazon EC2. Esta característica le permite probar el comando de forma segura sin crear ni modificar ningún recurso. 1. Rellene los valores restantes con valores adecuados para su escenario. En este ejemplo, proporcionamos el tipo de instancia, el nombre de la clave, el grupo de seguridad y el identificador de Amazon Machine Image (AMI) que vamos a utilizar. En este ejemplo, se asume la Región de AWS predeterminada. La AMI `ami-dfc39aef` es una imagen de Amazon Linux de 64 bits alojada en la región `us-west-2`. Si utiliza una región diferente, debe [encontrar el ID apropiado de la AMI que desea utilizar](https://aws.amazon.com/amazon-linux-ami/). ------ #### [ JSON ] ``` { "DryRun": true, "ImageId": "ami-dfc39aef", "KeyName": "mykey", "SecurityGroups": [ "my-sg" ], "InstanceType": "t2.micro", "Monitoring": { "Enabled": true } } ``` ------ #### [ YAML ] ``` DryRun: true ImageId: 'ami-dfc39aef' KeyName: 'mykey' SecurityGroups: - 'my-sg' InstanceType: 't2.micro' Monitoring: Enabled: true ``` ------ 1. Ejecute el comando con los parámetros completados pasando el archivo de plantilla relleno ya sea al parámetro `--cli-input-json` o --`cli-input-yaml` al utilizar ‎el prefijo `file://`. La AWS CLI interpreta la ruta como relativa al directorio de trabajo actual. En el siguiente ejemplo, la AWS CLI busca el archivo en el directorio de trabajo actual. ------ #### [ JSON ] ``` $ aws ec2 run-instances --cli-input-json file://ec2runinst.json ``` ``` A client error (DryRunOperation) occurred when calling the RunInstances operation: Request would have succeeded, but DryRun flag is set. ``` ------ #### [ YAML ] ``` $ aws ec2 run-instances --cli-input-yaml file://ec2runinst.yaml ``` ``` A client error (DryRunOperation) occurred when calling the RunInstances operation: Request would have succeeded, but DryRun flag is set. ``` ------ El error del simulacro indica que el código JSON ‎o YAML está formado correctament‎e y que los valores de los parámetros son válidos. Si se informa de cualquier otro problema en la salida, corríjalo y repita el paso anterior hasta que aparezca el mensaje "`Request would have succeeded`". 1. Ahora puede establecer el parámetro `DryRun` en `false` para deshabilitar el simulacro. ------ #### [ JSON ] ``` { "DryRun": false, "ImageId": "ami-dfc39aef", "KeyName": "mykey", "SecurityGroups": [ "my-sg" ], "InstanceType": "t2.micro", "Monitoring": { "Enabled": true } } ``` ------ #### [ YAML ] ``` DryRun: false ImageId: 'ami-dfc39aef' KeyName: 'mykey' SecurityGroups: - 'my-sg' InstanceType: 't2.micro' Monitoring: Enabled: true ``` ------ 1. Ejecute el comando para que `run-instances` lance una instancia de Amazon EC2 y muestre los detalles que se generan cuando el lanzamiento se realiza correctamente. El parámetro `--output` controla el formato de salida, independientemente del formato de la plantilla de parámetros de entrada. ------ #### [ JSON ] ``` $ aws ec2 run-instances --cli-input-json file://ec2runinst.json --output json ``` ``` { "OwnerId": "123456789012", "ReservationId": "r-d94a2b1", "Groups": [], "Instances": [ ... ``` ------ #### [ YAML ] ``` $ aws ec2 run-instances --cli-input-yaml file://ec2runinst.yaml --output yaml ``` ``` OwnerId: '123456789012' ReservationId: 'r-d94a2b1', Groups": - '' Instances: ... ``` ------ ## Combinación de archivos de entrada y parámetros de línea de comandos Se puede usar un archivo de entrada para todos los parámetros o se puede combinar con los parámetros especificados en la AWS CLI. Puede utilizar esta característica para los ajustes que reutiliza con frecuencia en un archivo de entrada y, al mismo tiempo, conservar los ajustes individuales en el propio comando. En los siguientes ejemplos de `aws ec2 run-instances`, se combinan el uso de un archivo de entrada y parámetros. Proporcionamos el tipo de instancia, el nombre de la clave, el grupo de seguridad y el identificador de la imagen de máquina de Amazon (AMI) que se va a utilizar y se asume la Región de AWS predeterminada. La AMI `ami-dfc39aef` es una imagen de Amazon Linux de 64 bits alojada en la región `us-west-2`. Si utiliza una región diferente, debe [encontrar el ID apropiado de la AMI que desea utilizar](https://aws.amazon.com/amazon-linux-ami/). ------ #### [ JSON ] Contenido del archivo JSON: ``` { "ImageId": "ami-dfc39aef", "KeyName": "mykey", "SecurityGroups": [ "my-sg" ], "InstanceType": "t2.micro", "Monitoring": { "Enabled": true } } ``` ------ #### [ YAML ] Contenido del archivo YAML: ``` ImageId: 'ami-dfc39aef' KeyName: 'mykey' SecurityGroups: - 'my-sg' InstanceType: 't2.micro' Monitoring: Enabled: true ``` ------ En el siguiente ejemplo, se utiliza el archivo de entrada en combinación con el parámetro `--dry-run` para realizar una actualización de prueba del comando para confirmar si tiene los permisos necesarios y si ha rellenado el archivo con valores válidos. ------ #### [ JSON ] ``` $ aws ec2 run-instances --cli-input-json file://ec2runinst.json --dry-run ``` ``` A client error (DryRunOperation) occurred when calling the RunInstances operation: Request would have succeeded, but DryRun flag is set. ``` ------ #### [ YAML ] ``` $ aws ec2 run-instances --cli-input-yaml file://ec2runinst.yaml --dry-run ``` ``` A client error (DryRunOperation) occurred when calling the RunInstances operation: Request would have succeeded, but DryRun flag is set. ``` ------ A continuación, en el siguiente ejemplo se utiliza el mismo archivo de entrada, pero con el parámetro `--no-dry-run` para ejecutar el comando en su totalidad. ------ #### [ JSON ] ``` $ aws ec2 run-instances --cli-input-json file://ec2runinst.json --no-dry-run --output json ``` ``` { "OwnerId": "123456789012", "ReservationId": "r-d94a2b1", "Groups": [], "Instances": [ ... ``` ------ #### [ YAML ] ``` $ aws ec2 run-instances --cli-input-yaml file://ec2runinst.yaml --no-dry-run --output yaml ``` ``` OwnerId: '123456789012' ReservationId: 'r-d94a2b1', Groups": - '' Instances: ... ``` ------ # Uso de la sintaxis abreviada en la AWS CLI La AWS Command Line Interface (AWS CLI) puede aceptar muchos de sus parámetros de opciones en formato JSON. Sin embargo, resultaría tedioso escribir largas listas o estructuras de JSON en la línea de comandos. Para simplificarlo, la AWS CLI también admite una sintaxis abreviada que permite una representación de los parámetros de opciones más sencilla que si se usara el formato JSON íntegro. **Topics** + [Parámetros de estructura con pares clave-valor](#shorthand-structure-parameters) + [Carga de un archivo como un valor sintáctico abreviado](#shorthand-files) + [Uso de sintaxis abreviada con la AWS CLI](#shorthand-list-parameters) ## Parámetros de estructura con pares clave-valor La sintaxis abreviada de la AWS CLI facilita a los usuarios la introducción de parámetros planos (con estructuras no anidadas). El formato consiste en una lista de pares de clave-valor separados por comas. Asegúrese de utilizar las reglas de [comillas](cli-usage-parameters-quoting-strings.md) y caracteres de escape apropiadas para el terminal como sintaxis abreviada son cadenas. ------ #### [ Linux or macOS ] ``` --option key1=value1,key2=value2,key3=value3 ``` Equivale al siguiente ejemplo con formato JSON. ``` --option '{"key1":"value1","key2":"value2","key3":"value3"}' ``` ------ #### [ Windows ] ``` --option "key1=value1,key2=value2,key3=value3" ``` Equivale al siguiente ejemplo con formato JSON. ``` --option '{"key1":"value1","key2":"value2","key3":"value3"}' ``` ------ No debe haber espacios en blanco entre cada uno de los pares de clave-valor separados por comas. A continuación, se muestra un ejemplo del comando de `update-table` de Amazon DynamoDB con la opción `--provisioned-throughput` especificada en modo abreviado. ``` $ aws dynamodb update-table \ --provisioned-throughput ReadCapacityUnits=15,WriteCapacityUnits=10 \ --table-name MyDDBTable ``` Esto equivale al siguiente ejemplo con formato JSON. ``` $ aws dynamodb update-table \ --provisioned-throughput '{"ReadCapacityUnits":15,"WriteCapacityUnits":10}' \ --table-name MyDDBTable ``` ## Carga de un archivo como un valor sintáctico abreviado Cuando un valor es grande o complejo, suele ser más fácil cargarlo en un archivo como un valor. Para cargar un archivo como un valor sintáctico abreviado, el formato cambiará ligeramente. En lugar de `key=value`, usará el operador `@=`, en lugar del operador `=`. El valor `@=` se refiere a la AWS CLI que el valor se debe leer como una ruta de archivo y no como una cadena. Al cargar archivos en una sintaxis abreviada, [se aplican las reglas de formato de archivo de la AWS CLI](cli-usage-parameters-file.md) habituales. En el siguiente ejemplo, se muestra un par clave-valor que carga un archivo por su valor. ------ #### [ Linux or macOS ] ``` --option key@=file://template.txt ``` ------ #### [ Windows ] ``` --option "key1@=file://template.txt" ``` ------ En el siguiente ejemplo, se muestra la carga de un archivo de certificado para el comando `aws rolesanywhere create-trust-anchor`. ``` $ aws rolesanywhere create-trust-anchor --name TrustAnchor \ --source sourceData={x509CertificateData@=file://root-ca.crt},sourceType="CERTIFICATE_BUNDLE" \ --enabled ``` ## Uso de sintaxis abreviada con la AWS CLI Puede especificar los parámetros de entrada en una lista de dos formas: en JSON o en sintaxis abreviada. La sintaxis abreviada de la AWS CLI ha sido diseñada para que su inserción en listas con números, cadenas o estructuras no anidadas resulte más sencilla. A continuación se muestra el formato básico, en el que los valores de la lista están separados por un único espacio. ``` --option value1 value2 value3 ``` Esto equivale al siguiente ejemplo con formato JSON. ``` --option '[value1,value2,value3]' ``` Como ya hemos mencionado anteriormente, puede especificar una lista de números, una lista de cadenas o una lista de estructuras no anidadas en formato abreviado. A continuación, se muestra un ejemplo del comando `stop-instances` para Amazon Elastic Compute Cloud (Amazon EC2), en el que el parámetro de entrada (lista de cadenas) de la opción `--instance-ids` se especifica en forma abreviada. ``` $ aws ec2 stop-instances \ --instance-ids i-1486157a i-1286157c i-ec3a7e87 ``` Esto equivale al siguiente ejemplo con formato JSON. ``` $ aws ec2 stop-instances \ --instance-ids '["i-1486157a","i-1286157c","i-ec3a7e87"]' ``` En el siguiente ejemplo se muestra el comando de `create-tags` de Amazon EC2, que toma una lista de estructuras no anidadas para la opción `--tags`. La opción `--resources` especifica el identificador de la instancia que debe etiquetarse. ``` $ aws ec2 create-tags \ --resources i-1286157c \ --tags Key=My1stTag,Value=Value1 Key=My2ndTag,Value=Value2 Key=My3rdTag,Value=Value3 ``` Esto equivale al siguiente ejemplo con formato JSON. El parámetro JSON está escrito en varias líneas para facilitar su lectura. ``` $ aws ec2 create-tags \ --resources i-1286157c \ --tags '[ {"Key": "My1stTag", "Value": "Value1"}, {"Key": "My2ndTag", "Value": "Value2"}, {"Key": "My3rdTag", "Value": "Value3"} ]' ``` # Activación y uso de los símbolos del sistema en la AWS CLI Puede hacer que la versión 2 de la AWS CLI le pida comandos, parámetros y recursos cuando ejecute un comando de `aws`. **Topics** + [Funcionamiento](#cli-usage-auto-prompt-about) + [Características del mensaje automático](#cli-usage-auto-prompt-features) + [Modos de mensaje automático](#cli-usage-auto-prompt-modes) + [Configuración del mensaje automático](#cli-usage-auto-prompt-configure) ## Funcionamiento Si está habilitado, el mensaje automático le permite utilizar la tecla **ENTER** (INTRO) para completar un comando introducido parcialmente. Después de presionar la tecla **ENTER** (INTRO), se sugieren comandos, parámetros y recursos en función de lo que siga escribiendo. Las sugerencias muestran el nombre del comando, parámetro o recurso a la izquierda y una descripción del mismo a la derecha. Para seleccionar y utilizar una sugerencia, utilice las teclas de flechas para resaltar una fila y, a continuación, presione la tecla de **SPACE** (ESPACIO). Cuando haya terminado de ingresar su comando, presione **ENTER** (INTRO) para usar el comando. En el siguiente ejemplo se muestra cómo se ve una lista sugerida de mensajes automáticos. ``` $ aws > aws a accessanalyzer Access Analyzer acm AWS Certificate Manager acm-pca AWS Certificate Manager Private Certificate Authority alexaforbusiness Alexa For Business amplify AWS Amplify ``` ## Características del mensaje automático El mensaje automático contiene las siguientes características útiles: **Panel de documentación** Proporciona la documentación de ayuda del comando actual. Para abrir la documentación, presione la tecla **F3**. **Finalización de comandos** Sugiere qué comandos de `aws` debería usar. Para ver una lista, ingrese parcialmente el comando. En el siguiente ejemplo se busca un servicio que comience con la letra `a`. ``` $ aws > aws a accessanalyzer Access Analyzer acm AWS Certificate Manager acm-pca AWS Certificate Manager Private Certificate Authority alexaforbusiness Alexa For Business amplify AWS Amplify ``` **Compleción de parámetros** Después de escribir un comando, el mensaje automático comienza a sugerir parámetros. Las descripciones de los parámetros incluyen el tipo de valor y una descripción del parámetro. Los parámetros necesarios se enumeran primero y se etiquetan según sean necesarios. En el siguiente ejemplo se muestra la lista de mensajes automáticos de parámetros para `aws dynamodb describe-table`. ``` $ aws dynamodb describe-table > aws dynamodb describe-table --table-name (required) [string] The name of the table to describe. --cli-input-json [string] Reads arguments from the JSON string provided. The JSON string follows the format provide... --cli-input-yaml [string] Reads arguments from the YAML string provided. The YAML string follows the format provide... --generate-cli-skeleton [string] Prints a JSON skeleton to standard output without sending an API request. If provided wit... ``` **Compleción de recursos** El mensaje automático realiza llamadas a la API de AWS utilizando las propiedades de recursos de AWS disponibles para sugerir valores de recursos. Esto permite que el mensaje automático sugiera posibles recursos que posee al introducir parámetros. En el siguiente ejemplo, el mensaje automático muestra los nombres de las tablas al rellenar el parámetro `--table-name` para el comando `aws dynamodb describe-table`. ``` $ aws dynamodb describe-table > aws dynamodb describe-table --table-name Table1 Table2 Table3 ``` **Compleción abreviada** Para los parámetros que utilizan sintaxis abreviada, el mensaje automático sugiere los valores a utilizar. En el siguiente ejemplo, el mensaje automático muestra los valores de sintaxis abreviada para el parámetro `--placement` en el comando `aws ec2 run-instances`. ``` $ aws ec2 run-instances > aws ec2 run-instances --placement AvailabilityZone= [string] The Availability Zone of the instance. If not specified, an Availability Zone wil... Affinity= [string] The affinity setting for the instance on the Dedicated Host. This parameter is no... GroupName= [string] The name of the placement group the instance is in. PartitionNumber= [integer] The number of the partition the instance is in. Valid only if the placement grou... ``` **Compleción del archivo** Al rellenar los parámetros de los comandos `aws`, la compleción automática sugiere nombres de archivos locales después de usar el prefijo `file://` o `fileb://`. En el siguiente ejemplo, el mensaje automático sugiere archivos locales después de ingresar `--item file://` para el comando `aws ec2 run-instances`. ``` $ aws ec2 run-instances > aws ec2 run-instances --item file:// item1.txt file1.json file2.json ``` **Compleción de la región** Cuando se utiliza el parámetro global `--region`, el mensaje automático muestra las regiones posibles para seleccionar. En el siguiente ejemplo, el mensaje automático sugiere regiones en orden alfabético después de escribir `--region` para el comando `aws dynamodb list-tables`. ``` $ aws dynamodb list-tables > aws dynamodb list-tables --region af-south-1 ap-east-1 ap-northeast-1 ap-northeast-2 ``` **Compleción del perfil** Cuando se utiliza el parámetro global `--profile`, el mensaje automático muestra una lista de sus perfiles. En el siguiente ejemplo, el mensaje automático sugiere sus perfiles después de ingresar `--profile` para el comando `aws dynamodb list-tables`. ``` $ aws dynamodb list-tables > aws dynamodb list-tables --profile profile1 profile2 profile3 ``` **Búsquedas confusas** Complete comandos y valores que contienen un conjunto específico de caracteres. En el siguiente ejemplo, el mensaje automático sugiere regiones que contienen `eu` después de ingresar `--region eu` para el comando `aws dynamodb list-tables`. ``` $ aws dynamodb list-tables > aws dynamodb list-tables --region west eu-west-1 eu-west-2 eu-west-3 us-west-1 ``` **Historial** Para ver y ejecutar los comandos utilizados anteriormente en el modo de mensaje automático, presione **CTRL \$1 R**. El historial muestra los comandos anteriores que puede seleccionar mediante las teclas de flecha. En el ejemplo siguiente, se muestra el historial del modo de mensaje automático. ``` $ aws > aws dynamodb list-tables s3 ls ``` ## Modos de mensaje automático El mensaje automático para la versión 2 de AWS CLI se puede configurar en 2 modos: + **Modo completo:** utiliza el mensaje automático cada vez que intenta ejecutar un comando `aws`, ya sea que lo llame manualmente usando el parámetro `--cli-auto-prompt` o lo habilite de forma permanente. Esto incluye presionar **ENTER** (INTRO) después de un comando completo o un comando incompleto. + **Modo parcial:** utiliza el mensaje automático si un comando está incompleto o no se puede ejecutar debido a errores de validación del lado del cliente. Este modo es especialmente útil si tiene scripts preexistentes, runbooks, o solo desea que se le pregunte automáticamente sobre los comandos con los que no está familiarizado en lugar de preguntarle sobre cada comando. ## Configuración del mensaje automático Para configurar el mensaje automático, puede utilizar los siguientes métodos en orden de prioridad: + **Las opciones de línea de comandos** habilitan o desactivan el mensaje automático para un solo comando. Use `--cli-auto-prompt` para solicitar un mensaje automático y `--no-cli-auto-prompt` para desactivarlo. + Las **variables del entorno** utilizan la variable `aws\$1cli\$1auto\$1prompt`. + Los **archivos de configuración compartida** usan la configuración`cli\$1auto\$1prompt`. # Control de la salida de comandos en la AWS CLI En esra sección se describen las diferentes formas de controlar la salida de AWS Command Line Interface (AWS CLI). La personalización de la salida de la AWS CLI de su terminal puede mejorar la legibilidad, agilizar la automatización del scripting y facilitar la navegación a través de conjuntos de datos más grandes. La AWS CLI admite varios [formatos de salida](cli-usage-output-format.md), incluidos [`json`](cli-usage-output-format.md#json-output), [`text`](cli-usage-output-format.md#text-output), [`yaml`](cli-usage-output-format.md#yaml-output), [`off`](cli-usage-output-format.md#off-output) y [`table`](cli-usage-output-format.md#table-output). Algunos servicios tienen [paginación](cli-usage-pagination.md) del servidor para sus datos y la AWS CLI proporciona sus propias características del cliente para opciones de paginación adicionales. Por último, la AWS CLI tiene [filtrado tanto del servidor como del cliente](cli-usage-filter.md) que se puede usar de forma individual o conjuntamente para filtrar la salida de la AWS CLI. **Topics** + [Salida de información confidencial](#cli-usage-output-sensitive) + [Opciones de salida del servidor frente a las del cliente](#cli-usage-output-server-client) + [Configuración del formato de salida en la AWS CLI](cli-usage-output-format.md) + [Salida de error estructurado en la AWS CLI](cli-usage-error-format.md) + [Uso de las opciones de paginación en la AWS CLI](cli-usage-pagination.md) + [Filtrado de la salida en la AWS CLI](cli-usage-filter.md) ## Salida de información confidencial Algunas operaciones de la AWS CLI pueden dar como resultado información que podría considerarse confidencial, por ejemplo, la información de las variables de entorno. La exposición de esta información puede representar un riesgo para la seguridad en ciertas situaciones; por ejemplo, la información podría incluirse en los registros de integración e implementación continuos (CI/CD). Por lo tanto, es importante que revise cuándo se incluyen dichos resultados como parte de los registros y que los suprima cuando no los necesite. Para obtener más información sobre la protección de datos confidenciales, consulte [Protección de datos en la AWS CLI](data-protection.md). Tenga en cuenta las siguientes prácticas recomendadas: + Considere la posibilidad de recuperar los secretos mediante programación de un almacén de secretos, como AWS Secrets Manager. + Revise el contenido de los registros de compilación para asegurarse de que no contienen información confidencial. Elija enfoques como canalizar a `/dev/null` o capturar la salida como una variable bash o PowerShell para suprimir las salidas de los comandos. El siguiente es un ejemplo de bash para redirigir la salida, pero no los errores, a `/dev/null`: ``` $ aws s3 ls > /dev/null ``` Para obtener información específica sobre cómo suprimir la salida del terminal, consulte la documentación del usuario del terminal que utilice. + Tenga en cuenta el acceso a los registros y determine un acceso adecuado para el caso de uso. ## Opciones de salida del servidor frente a las del cliente La AWS CLI tiene [filtrado tanto del servidor como del cliente](cli-usage-filter.md) que usted puede usar de forma individual o conjunta para filtrar la salida de la AWS CLI. El filtrado del servidor se procesa primero y devuelve su salida para el filtrado del cliente. La API del servicio admite el filtrado del servidor. El filtrado del cliente está respaldado por el cliente AWS CLI mediante el uso del parámetro `--query`. Las opciones de salida del **servidor** son características compatibles directamente con la API del servicio de Servicio de AWS. Los datos filtrados o paginados no se envían al cliente, lo que puede acelerar los tiempos de respuesta HTTP y mejorar el ancho de banda para conjuntos de datos más grandes. Las opciones de salida **del cliente** son características creadas por la AWS CLI. Todos los datos se envían al cliente y, a continuación, la AWS CLI filtra o pagina el contenido que se muestra. Las operaciones del cliente no ahorran velocidad ni ancho de banda en el caso de conjuntos de datos más grandes. Cuando las opciones del servidor y del cliente se utilizan juntas, las operaciones del servidor se completan primero y, después, se envían al cliente para las operaciones del cliente. De este modo se aprovechan los posibles ahorros de velocidad y ancho de banda de las opciones del servidor y, al mismo tiempo, se utilizan características adicionales de la AWS CLI para obtener el resultado deseado. # Configuración del formato de salida en la AWS CLI Este tema describe los diferentes formatos de salida para la AWS Command Line Interface (AWS CLI). La AWS CLI admite los siguientes formatos de salida: + **[`json`](#json-output)**: la salida se formatea como una cadena [JSON](https://json.org/). + **[`yaml`](#yaml-output)**: la salida se formatea como una cadena [YAML](https://yaml.org/). + **[`yaml-stream`](#yaml-stream-output)**: la salida se transmite y se formatea como una cadena [YAML](https://yaml.org/). La transmisión permite gestionar tipos de datos de gran tamaño de forma más rápida. + **[`text`](#text-output)** – la salida tiene el formato de varias líneas de valores de cadena separados por tabuladores. Esto puede ser útil para pasar la salida a un procesador de texto, como `grep`, `sed` o `awk`. + **[`table`](#table-output)** – el resultado tiene el formato de una tabla en la que se usan los caracteres \$1\$1- para los bordes de celda. Normalmente, la información se presenta en un formato que es más fácil de leer que los demás formatos, pero que no es útil para programar. + **[`off`](#off-output)**: la salida suprime todas las salidas de comando a stdout. Esto resulta útil en scripts de automatización y en procesos de CI/CD, en los que solo es necesario comprobar el código de salida del comando sin procesar la salida. ## Cómo seleccionar el formato de salida Tal como se explica en el tema de [configuración](cli-chap-configure.md), el formato de salida se puede especificar de tres formas diferentes: + **Uso de la opciópn `output` en un perfil con nombre en el archivo `config`**: el siguiente ejemplo establece el formato de la salida predeterminado como `text`. ``` [default] output=text ``` + **Uso de la variable de entorno de `AWS_DEFAULT_OUTPUT`**: la siguiente salida establece el formato como `table` para los comandos de esta sesión de línea de comandos hasta que se cambie la variable o finalice la sesión. Con esta variable de entorno, se invalida cualquier valor establecido en el archivo `config`. ``` $ export AWS_DEFAULT_OUTPUT="table" ``` + **Uso de la opción `--output` en la línea de comandos**: el siguiente ejemplo establece la salida únicamente de este comando como `json`. El uso de esta opción en el comando anula cualquier variable de entorno definida actualmente o el valor en el archivo `config`. ``` $ aws swf list-domains --registration-status REGISTERED --output json ``` **importante** El tipo de salida que especifique cambia cómo opera la opción `--query`: Si especifica `--output text`‎, la salida se pagina *antes‎* de que se aplique el filtro `--query`‎, y la AWS CLI‎ ejecuta la consulta una vez en *cada página* de la salida. Debido a esto, la consulta incluye el primer elemento que coincide en cada página, lo que puede dar lugar a una salida adicional inesperada. Para filtrar más la salida, puede usar otras herramientas de la línea de comandos como `head` o `tail`. Si especifica `--output json`, `--output yaml` o‎ `--output yaml-stream` la salida se procesará por completo como‎ una única estructura nativa antes de aplicar el filtro `--query`. La AWS CLI ejecuta la consulta solo una vez en toda la estructura y produce un resultado filtrado que luego se ofrece como salida. ## Formato de salida JSON [JSON](https://json.org) es el formato de salida predeterminado de la AWS CLI. La mayoría de lenguajes de programación pueden decodificar fácilmente cadenas JSON con funciones integradas o con bibliotecas disponibles públicamente. Puede combinar la salida JSON con la [opción —query](cli-usage-filter.md) de una forma eficaz para aplicar filtros y formato a la salida JSON de la AWS CLI. Para aplicar un filtrado más avanzado que el que permite `--query`, considere la posibilidad de utilizar `jq`, un procesador JSON de línea de comandos. Puede descargarlo y consultar el tutorial oficial en [http://stedolan.github.io/jq/](http://stedolan.github.io/jq/). A continuación, se muestra un ejemplo de una salida JSON: ``` $ aws iam list-users --output json ``` ``` { "Users": [ { "Path": "/", "UserName": "Admin", "UserId": "AIDA1111111111EXAMPLE", "Arn": "arn:aws:iam::123456789012:user/Admin", "CreateDate": "2014-10-16T16:03:09+00:00", "PasswordLastUsed": "2016-06-03T18:37:29+00:00" }, { "Path": "/backup/", "UserName": "backup-user", "UserId": "AIDA2222222222EXAMPLE", "Arn": "arn:aws:iam::123456789012:user/backup/backup-user", "CreateDate": "2019-09-17T19:30:40+00:00" }, { "Path": "/", "UserName": "cli-user", "UserId": "AIDA3333333333EXAMPLE", "Arn": "arn:aws:iam::123456789012:user/cli-user", "CreateDate": "2019-09-17T19:11:39+00:00" } ] } ``` ## Formato de salida YAML [YAML](https://yaml.org) es una buena opción para administrar la salida mediante programación con herramientas y servicios que emiten o consumen cadenas con formato [YAML](https://yaml.org), como CloudFormation, que admite [plantillas con formato YAML](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/template-formats.html). Para aplicar un filtrado más avanzado que el que permite `--query`, considere la posibilidad de utilizar `yq`, un procesador YAML de línea de comandos. Puede descargar `yq` en el [repositorio de yq](https://github.com/mikefarah/yq) de *GitHub*. A continuación, se muestra un ejemplo de una salida YAML. ``` $ aws iam list-users --output yaml ``` ``` Users: - Arn: arn:aws:iam::123456789012:user/Admin CreateDate: '2014-10-16T16:03:09+00:00' PasswordLastUsed: '2016-06-03T18:37:29+00:00' Path: / UserId: AIDA1111111111EXAMPLE UserName: Admin - Arn: arn:aws:iam::123456789012:user/backup/backup-user CreateDate: '2019-09-17T19:30:40+00:00' Path: /backup/ UserId: AIDA2222222222EXAMPLE UserName: arq-45EFD6D1-CE56-459B-B39F-F9C1F78FBE19 - Arn: arn:aws:iam::123456789012:user/cli-user CreateDate: '2019-09-17T19:30:40+00:00' Path: / UserId: AIDA3333333333EXAMPLE UserName: cli-user ``` ## Formato de salida de transmisión YAML‎ El formato `yaml-stream` aprovecha el formato [YAML](https://yaml.org) al tiempo que proporciona una visualización más receptiva/más rápida de los conjuntos de datos grandes mediante el streaming de datos a usted. Puede comenzar a ver y usar datos YAML antes de que se descargue toda la consulta. Para aplicar un filtrado más avanzado que el que permite `--query`, considere la posibilidad de utilizar `yq`, un procesador YAML de línea de comandos. Puede descargar `yq` en el [repositorio de yq](https://github.com/mikefarah/yq) de *GitHub*. A continuación se muestra un ejemplo de la salida de `yaml-stream`. ``` $ aws iam list-users --output yaml-stream ``` ``` - IsTruncated: false Users: - Arn: arn:aws:iam::123456789012:user/Admin CreateDate: '2014-10-16T16:03:09+00:00' PasswordLastUsed: '2016-06-03T18:37:29+00:00' Path: / UserId: AIDA1111111111EXAMPLE UserName: Admin - Arn: arn:aws:iam::123456789012:user/backup/backup-user CreateDate: '2019-09-17T19:30:40+00:00' Path: /backup/ UserId: AIDA2222222222EXAMPLE UserName: arq-45EFD6D1-CE56-459B-B39F-F9C1F78FBE19 - Arn: arn:aws:iam::123456789012:user/cli-user CreateDate: '2019-09-17T19:30:40+00:00' Path: / UserId: AIDA3333333333EXAMPLE UserName: cli-user ``` A continuación se muestra un ejemplo de salida `yaml-stream` en combinación con el uso del parámetro `--page-size` para paginar el contenido de YAML transmitido. ``` $ aws iam list-users --output yaml-stream --page-size 2 ``` ``` - IsTruncated: true Marker: ab1234cdef5ghi67jk8lmo9p/q012rs3t445uv6789w0x1y2z/345a6b78c9d00/1efgh234ij56klmno78pqrstu90vwxyx Users: - Arn: arn:aws:iam::123456789012:user/Admin CreateDate: '2014-10-16T16:03:09+00:00' PasswordLastUsed: '2016-06-03T18:37:29+00:00' Path: / UserId: AIDA1111111111EXAMPLE UserName: Admin - Arn: arn:aws:iam::123456789012:user/backup/backup-user CreateDate: '2019-09-17T19:30:40+00:00' Path: /backup/ UserId: AIDA2222222222EXAMPLE UserName: arq-45EFD6D1-CE56-459B-B39F-F9C1F78FBE19 - IsTruncated: false Users: - Arn: arn:aws:iam::123456789012:user/cli-user CreateDate: '2019-09-17T19:30:40+00:00' Path: / UserId: AIDA3333333333EXAMPLE UserName: cli-user ``` ## Formato de salida de texto El formato `text` organiza la salida de la AWS CLI en líneas delimitadas por tabulaciones. Este formato funciona bien con herramientas de texto tradicionales de Unix, como `grep`, `sed` y `awk`, así como con el procesamiento de texto que realiza PowerShell. El formato de salida de `text` sigue la estructura básica que se muestran a continuación. Las columnas se ordenan alfabéticamente según los nombres de las claves correspondientes del objeto JSON subyacente. ``` IDENTIFIER sorted-column1 sorted-column2 IDENTIFIER2 sorted-column1 sorted-column2 ``` A continuación se muestra un ejemplo de la salida de `text`. Cada campo está separado por tabulaciones de los demás, con una tabulación adicional si hay un campo vacío. ``` $ aws iam list-users --output text ``` ``` USERS arn:aws:iam::123456789012:user/Admin 2014-10-16T16:03:09+00:00 2016-06-03T18:37:29+00:00 / AIDA1111111111EXAMPLE Admin USERS arn:aws:iam::123456789012:user/backup/backup-user 2019-09-17T19:30:40+00:00 /backup/ AIDA2222222222EXAMPLE backup-user USERS arn:aws:iam::123456789012:user/cli-user 2019-09-17T19:11:39+00:00 / AIDA3333333333EXAMPLE cli-user ``` La cuarta columna es el campo `PasswordLastUsed` y está vacía en las dos últimas entradas, ya que esos usuarios nunca inician sesión en la Consola de administración de AWS. **importante** *Le recomendamos encarecidamente que si especifica una salida `text`, utilice siempre la opción [`--query`](cli-usage-filter.md) para garantizar un comportamiento coherente*. Esto se debe a que el formato de texto ordena alfabéticamente las columnas de salida por el nombre de la clave del objeto JSON subyacente que el servicio de AWS devuelve y podría haber recursos similares con distintos nombres de clave. Por ejemplo, la representación JSON de una instancia de Amazon EC2 basada en Linux podría tener elementos que no están presentes en la representación JSON de una instancia basada en Windows, o viceversa. Además, los recursos podrían tener elementos de valor de clave añadidos o eliminados en futuras actualizaciones, alterando el orden de las columnas. Aquí es donde `--query` incrementa la funcionalidad de la salida `text` para proporcionarle un control total sobre el formato de salida. En el ejemplo siguiente, el comando especifica qué elementos se van a mostrar y *define el orden* de las columnas con la notación en lista `[key1, key2, ...]`. Esto le ofrece la plena confianza de que los valores de clave correctos se mostrarán siempre en la columna prevista. Por último, tenga en cuenta que la AWS CLI devuelve el valor `None` para las claves que no existen. ``` $ aws iam list-users --output text --query 'Users[*].[UserName,Arn,CreateDate,PasswordLastUsed,UserId]' ``` ``` Admin arn:aws:iam::123456789012:user/Admin 2014-10-16T16:03:09+00:00 2016-06-03T18:37:29+00:00 AIDA1111111111EXAMPLE backup-user arn:aws:iam::123456789012:user/backup-user 2019-09-17T19:30:40+00:00 None AIDA2222222222EXAMPLE cli-user arn:aws:iam::123456789012:user/cli-backup 2019-09-17T19:11:39+00:00 None AIDA3333333333EXAMPLE ``` El siguiente ejemplo muestra cómo se puede usar `grep` y `awk` con la salida `text` del comando `aws ec2 describe-instances`. El primer comando muestra la zona de disponibilidad, el estado actual y el ID de cada instancia en la salida `text`. El segundo comando procesa esa salida para mostrar únicamente los ID de instancia de todas las instancias en ejecución en la zona de disponibilidad `us-west-2a`. ``` $ aws ec2 describe-instances --query 'Reservations[*].Instances[*].[Placement.AvailabilityZone, State.Name, InstanceId]' --output text ``` ``` us-west-2a running i-4b41a37c us-west-2a stopped i-a071c394 us-west-2b stopped i-97a217a0 us-west-2a running i-3045b007 us-west-2a running i-6fc67758 ``` ``` $ aws ec2 describe-instances --query 'Reservations[*].Instances[*].[Placement.AvailabilityZone, State.Name, InstanceId]' --output text | grep us-west-2a | grep running | awk '{print $3}' ``` ``` i-4b41a37c i-3045b007 i-6fc67758 ``` El siguiente ejemplo va un paso más allá y muestra no solo cómo filtrar el resultado, sino cómo utilizar esa salida para automatizar los tipos de instancias cambiantes para cada instancia detenida. ``` $ aws ec2 describe-instances --query 'Reservations[*].Instances[*].[State.Name, InstanceId]' --output text | > grep stopped | > awk '{print $2}' | > while read line; > do aws ec2 modify-instance-attribute --instance-id $line --instance-type '{"Value": "m1.medium"}'; > done ``` La salida `text` también puede resultar útil en PowerShell. Como las columnas de la salida `text` están delimitadas por tabulaciones, puede dividir fácilmente la salida en una matriz utilizando el delimitador ``t` de PowerShell. El siguiente comando muestra el valor de la tercera columna (`InstanceId`) si la primera columna (`AvailabilityZone`) coincide con la cadena `us-west-2a`. ``` PS C:\>aws ec2 describe-instances --query 'Reservations[*].Instances[*].[Placement.AvailabilityZone, State.Name, InstanceId]' --output text | %{if ($_.split("`t")[0] -match "us-west-2a") { $_.split("`t")[2]; } } ``` ``` -4b41a37c i-a071c394 i-3045b007 i-6fc67758 ``` Tenga en cuenta que, aunque en el ejemplo anterior se muestra cómo utilizar el parámetro `--query` para analizar los objetos JSON subyacentes y extraer la columna deseada, PowerShell dispone de una funcionalidad propia para gestionar JSON si la compatibilidad entre plataformas no es un problema. En lugar de tratar la salida como texto, como requieren la mayoría de los shells de comandos, PowerShell le permite utilizar el cmdlet `ConvertFrom-JSON` para producir un objeto estructurado jerárquicamente. A continuación, podrá acceder directamente al miembro que desee desde ese objeto. ``` (aws ec2 describe-instances --output json | ConvertFrom-Json).Reservations.Instances.InstanceId ``` **sugerencia** Si obtiene un texto en la salida y lo filtra con un solo campo utilizando el parámetro `--query`, la salida será una sola línea de valores separados por tabuladores. Para obtener cada valor en una línea independiente, puede colocar el campo de salida entre corchetes, tal y como se muestra en los siguientes ejemplos. Salida de una sola línea separada por tabuladores: ``` $ aws iam list-groups-for-user --user-name susan --output text --query "Groups[].GroupName" ``` ``` HRDepartment Developers SpreadsheetUsers LocalAdmins ``` Cada valor en su propia línea incluyendo `[GroupName]` entre corchetes: ``` $ aws iam list-groups-for-user --user-name susan --output text --query "Groups[].[GroupName]" ``` ``` HRDepartment Developers SpreadsheetUsers LocalAdmins ``` ## Formato de salida de tabla El formato `table` produce representaciones legibles para los humanos de la salida de la AWS CLI compleja en forma de tabla. ``` $ aws iam list-users --output table ``` ``` ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ListUsers | +---------------------------------------------------------------------------------------------------------------------------------------------------------------+ || Users || |+----------------------------------------------------+---------------------------+---------------------------+----------+-----------------------+-------------+| || Arn | CreateDate | PasswordLastUsed | Path | UserId | UserName || |+----------------------------------------------------+---------------------------+---------------------------+----------+-----------------------+-------------+| || arn:aws:iam::123456789012:user/Admin | 2014-10-16T16:03:09+00:00 | 2016-06-03T18:37:29+00:00 | / | AIDA1111111111EXAMPLE | Admin || || arn:aws:iam::123456789012:user/backup/backup-user | 2019-09-17T19:30:40+00:00 | | /backup/ | AIDA2222222222EXAMPLE | backup-user || || arn:aws:iam::123456789012:user/cli-user | 2019-09-17T19:11:39+00:00 | | / | AIDA3333333333EXAMPLE | cli-user || +---------------------------------------------------------------------------------------------------------------------------------------------------------------+ ``` Puede combinar la opción `--query` con el formato `table` para mostrar un conjunto de elementos preseleccionados a partir de la salida en bruto. Observe las diferencias de la salida entre las notaciones de diccionario y lista: en el primer ejemplo los nombres de columna están ordenados alfabéticamente, y en el segundo ejemplo las columnas sin nombre se ordenan según lo definido por el usuario. Para obtener más información acerca de la opción `--query`, consulte [Filtrado de la salida en la AWS CLI](cli-usage-filter.md). ``` $ aws ec2 describe-volumes --query 'Volumes[*].{ID:VolumeId,InstanceId:Attachments[0].InstanceId,AZ:AvailabilityZone,Size:Size}' --output table ``` ``` ------------------------------------------------------ | DescribeVolumes | +------------+----------------+--------------+-------+ | AZ | ID | InstanceId | Size | +------------+----------------+--------------+-------+ | us-west-2a| vol-e11a5288 | i-a071c394 | 30 | | us-west-2a| vol-2e410a47 | i-4b41a37c | 8 | +------------+----------------+--------------+-------+ ``` ``` $ aws ec2 describe-volumes --query 'Volumes[*].[VolumeId,Attachments[0].InstanceId,AvailabilityZone,Size]' --output table ``` ``` ---------------------------------------------------- | DescribeVolumes | +--------------+--------------+--------------+-----+ | vol-e11a5288| i-a071c394 | us-west-2a | 30 | | vol-2e410a47| i-4b41a37c | us-west-2a | 8 | +--------------+--------------+--------------+-----+ ``` ## Formato de salida “off” El formato `off` suprime todas las salidas de comando a stdout. Esto resulta útil en scripts de automatización y en procesos de CI/CD, en los que solo es necesario comprobar el código de salida del comando sin procesar la salida. Los mensajes de error siguen apareciendo en stderr. En el siguiente ejemplo se muestra cómo el formato `off` suprime la salida correcta. Puede comprobar el código de salida para determinar si es correcta: ``` $ aws s3api list-buckets --output off $ echo $? 0 ``` Esto resulta especialmente útil en scripts de intérprete de comandos en los que se desea comprobar si un recurso existe sin capturar la salida: ``` #!/bin/bash if aws s3api head-bucket --bucket my-bucket --output off 2>/dev/null; then echo "Bucket exists" else echo "Bucket does not exist" fi ``` **nota** El formato `off` solo suprime stdout. Los errores se siguen escribiendo en stderr. # Salida de error estructurado en la AWS CLI Este tema describe los formatos de salida de error estructurado para la AWS Command Line Interface (AWS CLI). La CLI escribe los errores en stderr y admite los siguientes formatos: + **[`enhanced`](#cli-error-format-enhanced)** (predeterminado): mensaje de error con detalles adicionales que se muestran en línea. Se utiliza para la depuración legible por el usuario. + **[`json`](#cli-error-format-json)**: la salida se formatea como una cadena [JSON](https://json.org/) con todos los campos de error. Se usa para la automatización y el scripting. + **[`yaml`](#cli-error-format-yaml)**: la salida se formatea como una cadena [YAML](https://yaml.org/) con todos los campos de error. Se usa para la automatización y el scripting. + **[`text`](#cli-error-format-text)**: formatea los errores usando el formateador de texto. Se utiliza para el escaneo visual rápido. + **[`table`](#cli-error-format-table)**: formatea los errores usando el formateador de tabla. Se utiliza para el escaneo visual rápido. + **[`legacy`](#cli-error-format-legacy)**: formato de error original sin detalles estructurados. Se usa para la retrocompatibilidad. ## Configuración del formato de error Puede configurar el formato de error utilizando cualquiera de los siguientes métodos: Indicador de línea de comandos ``` $ aws --cli-error-format json ``` Archivo de configuración: (`~/.aws/config`) ``` [default] cli_error_format = json ``` Variable de entorno ``` $ export AWS_CLI_ERROR_FORMAT=yaml ``` ## Formatos de salida de error En las secciones siguientes se describe cada formato: ### Formato mejorado (predeterminado) El formato mejorado muestra los mensajes de error con detalles adicionales en línea para valores simples. Para estructuras complejas, el formato proporciona una sugerencia para usar JSON o YAML. **Ejemplo: Ausencia de configuración de la región** ``` aws: [ERROR]: An error occurred (NoRegion): You must specify a region. You can also configure your region by running "aws configure". ``` **Ejemplo: Bucket de S3 inexistente con campos adicionales** ``` 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 ``` **Ejemplo: Campos de error complejos** ``` An error occurred (TransactionCanceledException) when calling the TransactWriteItems operation: Transaction cancelled, please refer cancellation reasons for specific reasons [ConditionalCheckFailed, None] Additional error details: CancellationReasons: Use "--cli-error-format json" or another error format to see the full details. ``` ### Formato JSON El formato JSON proporciona una representación estructurada con todos los campos de error. **Ejemplo: Ausencia de configuración de la región** ``` { "Code": "NoRegion", "Message": "You must specify a region. You can also configure your region by running \"aws configure\"." } ``` **Ejemplo: Bucket de S3 inexistente** ``` { "Code": "NoSuchBucket", "Message": "The specified bucket does not exist", "BucketName": "amzn-s3-demo-bucket" } ``` ### Formato YAML El formato YAML proporciona una representación estructurada con todos los campos de error. **Ejemplo: Ausencia de configuración de la región** ``` Code: NoRegion Message: You must specify a region. You can also configure your region by running "aws configure". ``` **Ejemplo: Bucket de S3 inexistente** ``` Code: NoSuchBucket Message: The specified bucket does not exist BucketName: amzn-s3-demo-bucket ``` ### Formato de texto El formato de texto utiliza el mismo formateador que la salida del comando que se ha ejecutado correctamente. **Ejemplo: Bucket de S3 inexistente** ``` amzn-s3-demo-bucket NoSuchBucket The specified bucket does not exist ``` ### Formato de tabla El formato de tabla utiliza el mismo formateador que la salida del comando que se ha ejecutado correctamente. **Ejemplo: Bucket de S3 inexistente** ``` -------------------------------------------------------------------------------------| | error | +---------------------------+---------------+----------------------------------------+ | BucketName | Code | Message | +---------------------------+---------------+----------------------------------------+ | amzn-s3-demo-bucket | NoSuchBucket | The specified bucket does not exist | +---------------------------+---------------+----------------------------------------+ ``` ### Formato heredado El formato heredado proporciona el formato de error original sin detalles estructurados. Este formato no incluye el prefijo “Se produjo un error (ErrorCode):” para las excepciones de la CLI. **Ejemplo: Ausencia de configuración de la región** ``` aws: [ERROR]: You must specify a region. You can also configure your region by running "aws configure". ``` **Ejemplo: Bucket de S3 inexistente** ``` An error occurred (NoSuchBucket) when calling the GetObject operation: The specified bucket does not exist ``` **nota** Los errores incluyen ahora sistemáticamente el prefijo `aws: [ERROR]:` para las excepciones de la CLI. Las versiones anteriores no siempre incluían este prefijo. Las siguientes excepciones siempre utilizan el formato heredado, independientemente del formato de error configurado: `UnknownArgumentError`: muestra la información de uso. Interrupciones del teclado (`KeyboardInterrupt`) ## Ejemplo completo En el siguiente ejemplo se muestra un comando con formato de error JSON: ``` $ aws s3api get-object \ --bucket amzn-s3-demo-bucket \ --key file.txt out.txt \ --cli-error-format json ``` Salida (stderr): ``` { "Code": "NoSuchBucket", "Message": "The specified bucket does not exist", "BucketName": "amzn-s3-demo-bucket" } ``` El campo `BucketName` es un elemento de error modelado devuelto por el servicio Amazon S3. # Uso de las opciones de paginación en la AWS CLI En este tema se describen las diferentes formas de paginar la salida de AWS Command Line Interface (AWS CLI). Hay principalmente dos formas de controlar la paginación desde AWS CLI. + [Uso de parámetros de paginación del lado del servidor.](#cli-usage-pagination-serverside) + [Uso del programa de paginación del lado del cliente de salida predeterminado](#cli-usage-pagination-clientside). Los parámetros de paginación del lado del servidor procesan primero y cualquier salida se envía a la paginación del lado del cliente. ## Paginación del lado del servidor Para la mayoría de los comandos que pueden devolver una amplia lista de elementos, la AWS CLI tiene múltiples opciones del servidor para controlar el número de elementos que se incluyen en la salida cuando la AWS CLI llame a la API de un servicio para rellenar la lista. La API de servicio de AWS habilita la paginación del servidor en la AWS CLI, por lo que estas opciones solo funcionan si la API de servicio las habilita. **Topics** + [--no-paginate](#cli-usage-pagination-nopaginate) + [--page-size](#cli-usage-pagination-pagesize) + [--max-items](#cli-usage-pagination-maxitems) + [--starting-token](#cli-usage-pagination-startingtoken) De forma predeterminada, AWS CLI utiliza un tamaño de página determinado por el servicio individual y recupera todos los elementos disponibles. Por ejemplo, Simple Storage Service (Amazon S3) tiene un tamaño de página predeterminado de 1000. Si ejecuta `aws s3api list-objects` en un bucket de Simple Storage Service (Amazon S3) que contiene 3500 objetos, AWS CLI realiza cuatro llamadas a Simple Storage Service (Amazon S3) y se encarga de administrar por usted la lógica de paginación específica del servicio en segundo plano y de devolver los 3500 objetos en la salida final. ‎Para obtener información acerca de si un comando específico tiene paginación del servidor, consulte la [Guía de referencia de la AWS CLI versión 2](https://docs.aws.amazon.com/cli/latest/reference/index.html). ### Cómo usar el parámetro —no-paginate La opción `--no-paginate` desactiva los siguientes tokens de paginación en el lado del cliente. Cuando se utiliza un comando, de forma predeterminada, la AWS CLI realiza automáticamente varias llamadas para devolver todos los resultados posibles para crear paginación. Una llamada por cada página. La desactivación de la paginación hace la única llamada de la AWS CLI una vez para la primera página de resultados de comandos. Por ejemplo, si ejecuta `aws s3api list-objects` en un bucket de Amazon S3 que contiene 3500 objetos, la AWS CLI solo realiza la primera llamada a Amazon S3, devolviendo solo los primeros 1000 objetos de la salida final. ``` $ aws s3api list-objects \ --bucket amzn-s3-demo-bucket \ --no-paginate { "Contents": [ ... ``` ### Cómo usar el parámetro —page-size Si observa algún problema al ejecutar los comandos de la lista en un gran número de recursos, el tamaño de página predeterminado puede ser demasiado grande. Esto puede provocar las llamadas a los servicios de AWS para superar el tiempo máximo permitido y generar un error de "tiempo de espera agotado". Puede utilizar la opción `--page-size` para especificar que la AWS CLI solicite un número menor de elementos de cada llamada al servicio de AWS. La AWS CLI recupera aun así la lista completa, pero realiza un mayor número de llamadas a la API en segundo plano y recupera un menor número de elementos con cada llamada. Esto ofrece a las llamadas individuales una mayor posibilidad de que tengan éxito sin que se agote el tiempo de espera. El cambio del tamaño de página no afecta a la salida; solo afecta a la cantidad de llamadas a la API que hay que realizar para generar la salida. ``` $ aws s3api list-objects \ --bucket amzn-s3-demo-bucket \ --page-size 100 { "Contents": [ ... ``` ### Cómo usar el parámetro —max-items Para incluir menos elementos a la vez en la salida de la AWS CLI, utilice la opción `--max-items`. La AWS CLI sigue administrando la paginación con el servicio tal y como se indicó anteriormente, pero solamente muestra a la vez el número de elementos especificado. ``` $ aws s3api list-objects \ --bucket amzn-s3-demo-bucket \ --max-items 100 { "NextToken": "eyJNYXJrZXIiOiBudWxsLCAiYm90b190cnVuY2F0ZV9hbW91bnQiOiAxfQ==", "Contents": [ ... ``` ### Cómo usar el parámetro —starting-token Si el número de elementos de salida (`--max-items`) es inferior al número total de elementos devueltos por las llamadas básicas a la API, la salida incluirá un `NextToken` que podrá pasar a un comando posterior para recuperar el siguiente conjunto de elementos. En el siguiente ejemplo se muestra cómo usar el valor `NextToken` devuelto por el ejemplo anterior y le permite recuperar los segundos 100 elementos. **nota** El parámetro `--starting-token` no puede ser nulo ni está vacío. Si el comando anterior no devuelve un valor `NextToken`, no hay más elementos para devolver y no es necesario llamar al comando de nuevo. ``` $ aws s3api list-objects \ --bucket amzn-s3-demo-bucket \ --max-items 100 \ --starting-token eyJNYXJrZXIiOiBudWxsLCAiYm90b190cnVuY2F0ZV9hbW91bnQiOiAxfQ== { "Contents": [ ... ``` Puede que el servicio de AWS especificado no devuelva los elementos en el mismo orden cada vez que lo llame. Si especifica diferentes valores para `--page-size` y `--max-items`, puede obtener resultados inesperados en el que faltan elementos o están duplicados. Para evitar esto, utilice el mismo número con `--page-size` y `--max-items` para sincronizar la paginación de la AWS CLI con la del servicio subyacente. También puede recuperar la lista completa y realizar las operaciones de paginación necesarias de forma local. ## Paginación del lado del cliente AWS CLILa versión 2 de la proporciona el uso de un programa de paginación del lado del cliente para la salida. De forma predeterminada, esta función devuelve todas las salidas a través del programa de paginación predeterminado del sistema operativo. En orden de prioridad, puede especificar la paginación de salida de estas dos maneras: + Uso de la configuración de‎ `cli_pager` en el archivo `config` en el perfil `default` o ‎con nombre. + Uso de la variable de entorno `AWS_PAGER`. + Uso de la variable de entorno `PAGER`. En orden de prioridad, puede deshabilitar todo el uso de un programa de paginación externo de las siguientes maneras: + Use la opción de línea de comandos `--no-cli-pager` para desactivar la paginación para un solo uso de comando. + Establezca la configuración `cli_pager` o la variable `AWS_PAGER` en una cadena vacía. **Topics** + [cli\$1pager](#cli-usage-pagination-clipager) + [AWS\$1PAGER](#cli-usage-pagination-awspager) + [—no-cli-pager](#cli-usage-pagination-noclipager) + [Marcadores de paginación](#cli-usage-pagination-flags) ### Cómo utilizar la configuración cli\$1pager Puede guardar las opciones de configuración y las credenciales que utiliza con frecuencia en archivos que son mantenidos por la AWS CLI. La configuración de un perfil de nombre tiene prioridad sobre la configuración en el perfil `default`. Para obtener más información sobre los valores de configuración, consulte [Opciones de los archivos de configuración y credenciales en la AWS CLI](cli-configure-files.md). El siguiente ejemplo establece la paginación de salida predeterminada en el programa `less`. ``` [default] cli_pager=less ``` En el ejemplo siguiente se establece el valor predeterminado para deshabilitar el uso de un paginador. ``` [default] cli_pager= ``` ### Cómo definir la variable de entorno AWS\$1PAGER El siguiente ejemplo establece la paginación de salida predeterminada en el programa `less`. Para obtener más información sobre las variables de entorno, consulte [Configuración de variables de entorno para la AWS CLI](cli-configure-envvars.md). ------ #### [ Linux and macOS ] ``` $ export AWS_PAGER="less" ``` ------ #### [ Windows ] ``` C:\> setx AWS_PAGER "less" ``` ------ ### Cómo usar la opción —no-cli-pager Para deshabilitar el uso de un paginador en un único comando, utilice la opción `--no-cli-pager`. Para obtener más información acerca de las opciones de línea de comandos, consulte [Opciones de línea de comandos en la AWS CLI](cli-configure-options.md). ``` $ aws s3api list-objects \ --bucket amzn-s3-demo-bucket \ --no-cli-pager { "Contents": [ ... ``` ### Cómo usar marcadores de paginación Puede especificar marcadores que se usarán automáticamente con el programa de paginación. Los marcadores dependen del programa de paginación que utilice. Los siguientes ejemplos son para los valores predeterminados típicos de `less` y `more`. ------ #### [ Linux and macOS ] Si no especifica lo contrario, la versión 2 de AWS CLI que usa el paginador por defecto es `less`. Si no tiene el conjunto de variables de entorno `LESS`, la versión 2 de la AWS CLI utiliza los marcadores `FRX`. Puede combinar marcadores especificándolos al establecer el paginador AWS CLI. En este ejemplo se usa el marcador `S`. Este marcador se combina con los marcadores predeterminados `FRX` para crear un marcador `FRXS`. ``` $ export AWS_PAGER="less -S" ``` Si no quiere utilizar ninguno de los marcadores `FRX`, puede negarlos. En el siguiente ejemplo se niega el marcador `F` para crear un marcador `RX` final. ``` $ export AWS_PAGER="less -+F" ``` Para obtener más información sobre los marcadores `less`, consulte [menos](http://manpages.org/less/1#options) en *manpages.org*. ------ #### [ Windows ] Si no especifica lo contrario, la versión 2 de la AWS CLI del paginador utiliza por defecto `more` sin marcadores adicionales. En el siguiente ejemplo se usa el parámetro `/c`. ``` C:\> setx AWS_PAGER "more /c" ``` Para obtener más información sobre `more` marcadores, consulte `[more](https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/more)` en *Documentos de Microsoft*. ------ # Filtrado de la salida en la AWS CLI La AWS Command Line Interface (AWS CLI) tiene filtrado tanto del servidor como del cliente que usted puede usar de forma individual o juntos para filtrar su salida AWS CLI. El filtrado del lado del servidor se procesa primero y devuelve su salida para el filtrado del lado del cliente. + El filtrado del lado del servidor es compatible con la API, y generalmente lo implementa con un parámetro `--filter`. El servicio solo devuelve resultados coincidentes que pueden acelerar los tiempos de respuesta HTTP para conjuntos de datos grandes. + El filtrado del cliente está respaldado por el cliente AWS CLI mediante el uso del parámetro `--query`. Este parámetro tiene capacidades que el filtrado del servidor puede no tener. **Topics** + [Filtrado en el servidor](#cli-usage-filter-server-side) + [Filtrado del lado del cliente](#cli-usage-filter-client-side) + [Combinación del filtrado del lado del cliente y del servidor](#cli-usage-filter-combining) + [Recursos adicionales](#cli-usage-filter-resources) ## Filtrado en el servidor El filtrado en el servidor en el AWS CLI se proporciona a través del API de servicio AWS. El servicio AWS solo devuelve los registros de la respuesta HTTP que coinciden con el filtro, lo que puede acelerar los tiempos de respuesta HTTP para conjuntos de datos grandes. Dado que el filtrado del lado del servidor está definido por la API del servicio, los nombres de los parámetros y las funciones varían entre los servicios. Algunos nombres de parámetros comunes utilizados para filtrar son: + `--filter` tales como [ses](https://docs.aws.amazon.com/cli/latest/reference/ses/create-receipt-filter.html) y [ce](https://docs.aws.amazon.com/cli/latest/reference/ce/get-cost-and-usage.html). + `--filters` tales como [ec2](https://docs.aws.amazon.com/cli/latest/reference/ec2/describe-volumes.html), [autoscaling](https://docs.aws.amazon.com/cli/latest/reference/autoscaling/describe-tags.html) y [rds](https://docs.aws.amazon.com/cli/latest/reference/rds/describe-db-instances.html). + ‎Nombres que empiezan por la palab‎ra `filter`‎,‎ por ejemplo `--filter-expression` para el comando [https://docs.aws.amazon.com/cli/latest/reference/dynamodb/scan.html](https://docs.aws.amazon.com/cli/latest/reference/dynamodb/scan.html). ‎Para obtener información acerca de si un comando específico tiene filtrado del lado del servidor y las reglas de filtrado, consulte la [Guía de referencia de la versión 2 de la AWS CLI](https://docs.aws.amazon.com/cli/latest/reference/index.html). ## Filtrado del lado del cliente La AWS CLI ofrece capacidades de filtrado de salida basadas en JSON integradas con el parámetro `--query`. El parámetro `--query` es una potente herramienta que se puede utilizar para personalizar el contenido y el estilo de la salida. El parámetro `--query` toma la respuesta HTTP que regresa del servidor y filtra los resultados antes de mostrarlos. Dado que toda la respuesta HTTP se envía al cliente antes del filtrado, el filtrado del lado del cliente puede ser más lento que el filtrado del lado del servidor para grandes conjuntos de datos. Las consultas usan [sintaxis JMESPath](https://jmespath.org/) para crear expresiones para filtrar la salida. Para obtener más información acerca de la sintaxis de JMesPath, consulte el [Tutorial](https://jmespath.org/tutorial.html) del *sitio web JMESPath*. **importante** El tipo de salida que especifique cambia cómo opera la opción `--query`: Si especifica `--output text`‎, la salida se pagina *antes‎* de que se aplique el filtro `--query`‎, y la AWS CLI‎ ejecuta la consulta una vez en *cada página* de la salida. Debido a esto, la consulta incluye el primer elemento que coincide en cada página, lo que puede dar lugar a una salida adicional inesperada. Para filtrar más la salida, puede usar otras herramientas de la línea de comandos como `head` o `tail`. Si especifica `--output json`, `--output yaml` o‎ `--output yaml-stream` la salida se procesará por completo como‎ una única estructura nativa antes de aplicar el filtro `--query`. La AWS CLI ejecuta la consulta solo una vez en toda la estructura y produce un resultado filtrado que luego se ofrece como salida. **Topics** + [Antes de comenzar](#cli-usage-filter-client-side-output) + [Identificadores](#cli-usage-filter-client-side-identifiers) + [Cómo seleccionar de una lista](#cli-usage-filter-client-side-select-list) + [Filtrado de datos anidados](#cli-usage-filter-client-side-nested) + [Aplanamiento de los resultados](#cli-usage-filter-client-side-specific-flattening) + [Filtrado para valores específicos](#cli-usage-filter-client-side-specific-values) + [Expresiones de canalización](#cli-usage-filter-client-side-pipe) + [Filtrado para varios valores de identificador](#cli-usage-filter-client-side-miltiselect-list) + [Agregado de etiquetas a valores de identificador](#cli-usage-filter-client-side-multiselect-hash) + [Funciones](#cli-usage-filter-client-side-functions) + [Ejemplos `--query` avanzados](#cli-usage-filter-client-side-advanced) ### Antes de comenzar **nota** Estos ejemplos de expresiones de filtro están escritos para intérpretes de comandos de tipo Linux básicos. Cuando utilice estos ejemplos, asegúrese de utilizar las reglas de entrecomillado correctas para el intérprete de comandos del terminal. La forma en que el terminal interpreta las entradas puede cambiar enormemente lo que se envía a la AWS CLI. La forma en que el terminal lee las comillas simples`'`, las comillas dobles `"` o las comillas inversas ``` puede cambiar la forma de leer el contenido. Para obtener más información, consulte [Entrecomillado de cadenas y uso de literales en la AWS CLI](cli-usage-parameters-quoting-strings.md). En la siguiente salida JSON se muestra un ejemplo de lo que el parámetro `--query` puede producir. La salida describe tres volúmenes de Amazon EBS conectados a instancias independientes de Amazon EC2. #### Ejemplo de resultado ``` $ aws ec2 describe-volumes { "Volumes": [ { "AvailabilityZone": "us-west-2a", "Attachments": [ { "AttachTime": "2013-09-17T00:55:03.000Z", "InstanceId": "i-a071c394", "VolumeId": "vol-e11a5288", "State": "attached", "DeleteOnTermination": true, "Device": "/dev/sda1" } ], "VolumeType": "standard", "VolumeId": "vol-e11a5288", "State": "in-use", "SnapshotId": "snap-f23ec1c8", "CreateTime": "2013-09-17T00:55:03.000Z", "Size": 30 }, { "AvailabilityZone": "us-west-2a", "Attachments": [ { "AttachTime": "2013-09-18T20:26:16.000Z", "InstanceId": "i-4b41a37c", "VolumeId": "vol-2e410a47", "State": "attached", "DeleteOnTermination": true, "Device": "/dev/sda1" } ], "VolumeType": "standard", "VolumeId": "vol-2e410a47", "State": "in-use", "SnapshotId": "snap-708e8348", "CreateTime": "2013-09-18T20:26:15.000Z", "Size": 8 }, { "AvailabilityZone": "us-west-2a", "Attachments": [ { "AttachTime": "2020-11-20T19:54:06.000Z", "InstanceId": "i-1jd73kv8", "VolumeId": "vol-a1b3c7nd", "State": "attached", "DeleteOnTermination": true, "Device": "/dev/sda1" } ], "VolumeType": "standard", "VolumeId": "vol-a1b3c7nd", "State": "in-use", "SnapshotId": "snap-234087fb", "CreateTime": "2020-11-20T19:54:05.000Z", "Size": 15 } ] } ``` ### Identificadores Los identificadores son las etiquetas de los valores de salida. Al crear filtros, se utilizan identificadores para reducir los resultados de la consulta. En el siguiente ejemplo de salida, se resaltan todos los identificadores como `Volumes`, `AvailabilityZone` y `AttachTime`. ``` $ aws ec2 describe-volumes { "Volumes": [ { "AvailabilityZone": "us-west-2a", "Attachments": [ { "AttachTime": "2013-09-17T00:55:03.000Z", "InstanceId": "i-a071c394", "VolumeId": "vol-e11a5288", "State": "attached", "DeleteOnTermination": true, "Device": "/dev/sda1" } ], "VolumeType": "standard", "VolumeId": "vol-e11a5288", "State": "in-use", "SnapshotId": "snap-f23ec1c8", "CreateTime": "2013-09-17T00:55:03.000Z", "Size": 30 }, { "AvailabilityZone": "us-west-2a", "Attachments": [ { "AttachTime": "2013-09-18T20:26:16.000Z", "InstanceId": "i-4b41a37c", "VolumeId": "vol-2e410a47", "State": "attached", "DeleteOnTermination": true, "Device": "/dev/sda1" } ], "VolumeType": "standard", "VolumeId": "vol-2e410a47", "State": "in-use", "SnapshotId": "snap-708e8348", "CreateTime": "2013-09-18T20:26:15.000Z", "Size": 8 }, { "AvailabilityZone": "us-west-2a", "Attachments": [ { "AttachTime": "2020-11-20T19:54:06.000Z", "InstanceId": "i-1jd73kv8", "VolumeId": "vol-a1b3c7nd", "State": "attached", "DeleteOnTermination": true, "Device": "/dev/sda1" } ], "VolumeType": "standard", "VolumeId": "vol-a1b3c7nd", "State": "in-use", "SnapshotId": "snap-234087fb", "CreateTime": "2020-11-20T19:54:05.000Z", "Size": 15 } ] } ``` Para obtener más información, consulte [Identificadores](https://jmespath.org/specification.html#identifiers ) en el *sitio web JMESPath*. ### Cómo seleccionar de una lista Una lista o matriz es un identificador que va seguido de un corchete “`[`” como `Volumes` y `Attachments` en la [Antes de comenzar](#cli-usage-filter-client-side-output). **Sintaxis** ``` [ ] ``` Para filtrar todos los resultados de una matriz, puede usar la notación comodín. Las expresiones [comodín](http://jmespath.org/specification.html#wildcard-expressions) son expresiones utilizadas para devolver elementos utilizando la notación `*`. En el siguiente ejemplo se consulta todo el contenido de `Volumes`. ``` $ aws ec2 describe-volumes \ --query 'Volumes[*]' [ { "AvailabilityZone": "us-west-2a", "Attachments": [ { "AttachTime": "2013-09-17T00:55:03.000Z", "InstanceId": "i-a071c394", "VolumeId": "vol-e11a5288", "State": "attached", "DeleteOnTermination": true, "Device": "/dev/sda1" } ], "VolumeType": "standard", "VolumeId": "vol-e11a5288", "State": "in-use", "SnapshotId": "snap-f23ec1c8", "CreateTime": "2013-09-17T00:55:03.000Z", "Size": 30 }, { "AvailabilityZone": "us-west-2a", "Attachments": [ { "AttachTime": "2020-11-20T19:54:06.000Z", "InstanceId": "i-1jd73kv8", "VolumeId": "vol-a1b3c7nd", "State": "attached", "DeleteOnTermination": true, "Device": "/dev/sda1" } ], "VolumeType": "standard", "VolumeId": "vol-a1b3c7nd", "State": "in-use", "SnapshotId": "snap-234087fb", "CreateTime": "2020-11-20T19:54:05.000Z", "Size": 15 } ] ``` Para ver un volumen específico en la matriz por índice, se llama al índice de matriz. Por ejemplo, el primer elemento de la matriz `Volumes` tiene un índice de 0, lo que resulta en la consulta `Volumes[0]`. Para obtener más información acerca de los índices de matriz, consulte [Expresiones de índice](http://jmespath.org/specification.html#index-expressions) en el *Sitio web JMESPath*. ``` $ aws ec2 describe-volumes \ --query 'Volumes[0]' { "AvailabilityZone": "us-west-2a", "Attachments": [ { "AttachTime": "2013-09-17T00:55:03.000Z", "InstanceId": "i-a071c394", "VolumeId": "vol-e11a5288", "State": "attached", "DeleteOnTermination": true, "Device": "/dev/sda1" } ], "VolumeType": "standard", "VolumeId": "vol-e11a5288", "State": "in-use", "SnapshotId": "snap-f23ec1c8", "CreateTime": "2013-09-17T00:55:03.000Z", "Size": 30 } ``` Para ver un rango específico de volúmenes por índice, utilice `slice` con la siguiente sintaxis, donde ‎**iniciar** es el índice de matriz inicial, **detener** es el índice en el que el filtro deja de procesarse y **paso** es el intervalo de omisión. **Sintaxis** ``` [::] ``` Si se omite cualquiera de estos elementos de la expresión de sector, utilizan los siguientes valores predeterminados: + Iniciar: el primer índice de la lista, 0. + Detener: el último índice de la lista. + Paso: sin saltar paso, donde el valor es 1. Para devolver solo los dos primeros volúmenes, utilice un valor inicial de 0, un valor de detención de 2 y un valor de paso de 1, como se muestra en el siguiente ejemplo. ``` $ aws ec2 describe-volumes \ --query 'Volumes[0:2:1]' [ { "AvailabilityZone": "us-west-2a", "Attachments": [ { "AttachTime": "2013-09-17T00:55:03.000Z", "InstanceId": "i-a071c394", "VolumeId": "vol-e11a5288", "State": "attached", "DeleteOnTermination": true, "Device": "/dev/sda1" } ], "VolumeType": "standard", "VolumeId": "vol-e11a5288", "State": "in-use", "SnapshotId": "snap-f23ec1c8", "CreateTime": "2013-09-17T00:55:03.000Z", "Size": 30 }, { "AvailabilityZone": "us-west-2a", "Attachments": [ { "AttachTime": "2013-09-18T20:26:16.000Z", "InstanceId": "i-4b41a37c", "VolumeId": "vol-2e410a47", "State": "attached", "DeleteOnTermination": true, "Device": "/dev/sda1" } ], "VolumeType": "standard", "VolumeId": "vol-2e410a47", "State": "in-use", "SnapshotId": "snap-708e8348", "CreateTime": "2013-09-18T20:26:15.000Z", "Size": 8 } ] ``` Dado que este ejemplo contiene valores predeterminados, puede acortar el segmento de `Volumes[0:2:1]` a `Volumes[:2]`. En el ejemplo siguiente se omiten los valores predeterminados y se devuelve cada dos volúmenes de toda la matriz. ``` $ aws ec2 describe-volumes \ --query 'Volumes[::2]' [ { "AvailabilityZone": "us-west-2a", "Attachments": [ { "AttachTime": "2013-09-17T00:55:03.000Z", "InstanceId": "i-a071c394", "VolumeId": "vol-e11a5288", "State": "attached", "DeleteOnTermination": true, "Device": "/dev/sda1" } ], "VolumeType": "standard", "VolumeId": "vol-e11a5288", "State": "in-use", "SnapshotId": "snap-f23ec1c8", "CreateTime": "2013-09-17T00:55:03.000Z", "Size": 30 }, { "AvailabilityZone": "us-west-2a", "Attachments": [ { "AttachTime": "2020-11-20T19:54:06.000Z", "InstanceId": "i-1jd73kv8", "VolumeId": "vol-a1b3c7nd", "State": "attached", "DeleteOnTermination": true, "Device": "/dev/sda1" } ], "VolumeType": "standard", "VolumeId": "vol-a1b3c7nd", "State": "in-use", "SnapshotId": "snap-234087fb", "CreateTime": "2020-11-20T19:54:05.000Z", "Size": 15 } ] ``` Los pasos también pueden utilizar números negativos para filtrar en el orden inverso de una matriz como se muestra en el siguiente ejemplo. ``` $ aws ec2 describe-volumes \ --query 'Volumes[::-2]' [ { "AvailabilityZone": "us-west-2a", "Attachments": [ { "AttachTime": "2020-11-20T19:54:06.000Z", "InstanceId": "i-1jd73kv8", "VolumeId": "vol-a1b3c7nd", "State": "attached", "DeleteOnTermination": true, "Device": "/dev/sda1" } ], "VolumeType": "standard", "VolumeId": "vol-a1b3c7nd", "State": "in-use", "SnapshotId": "snap-234087fb", "CreateTime": "2020-11-20T19:54:05.000Z", "Size": 15 }, { "AvailabilityZone": "us-west-2a", "Attachments": [ { "AttachTime": "2013-09-17T00:55:03.000Z", "InstanceId": "i-a071c394", "VolumeId": "vol-e11a5288", "State": "attached", "DeleteOnTermination": true, "Device": "/dev/sda1" } ], "VolumeType": "standard", "VolumeId": "vol-e11a5288", "State": "in-use", "SnapshotId": "snap-f23ec1c8", "CreateTime": "2013-09-17T00:55:03.000Z", "Size": 30 } ] ``` Para obtener más información, consulte [Sectores](https://jmespath.org/specification.html#slices) en el *Sitio web JMESPath*. ### Filtrado de datos anidados Para restringir el filtrado de `Volumes[*]` para los valores anidados, se utilizan subexpresiones agregando un punto y sus criterios de filtro. **Sintaxis** ``` . ``` En el siguiente ejemplo se muestra toda la información de `Attachments`para todos los volúmenes. ``` $ aws ec2 describe-volumes \ --query 'Volumes[*].Attachments' [ [ { "AttachTime": "2013-09-17T00:55:03.000Z", "InstanceId": "i-a071c394", "VolumeId": "vol-e11a5288", "State": "attached", "DeleteOnTermination": true, "Device": "/dev/sda1" } ], [ { "AttachTime": "2013-09-18T20:26:16.000Z", "InstanceId": "i-4b41a37c", "VolumeId": "vol-2e410a47", "State": "attached", "DeleteOnTermination": true, "Device": "/dev/sda1" } ], [ { "AttachTime": "2020-11-20T19:54:06.000Z", "InstanceId": "i-1jd73kv8", "VolumeId": "vol-a1b3c7nd", "State": "attached", "DeleteOnTermination": true, "Device": "/dev/sda1" } ] ] ``` Para filtrar más los valores anidados, agregue la expresión para cada indentificador anidado. En el ejemplo siguiente, se muestran los `State` para todos los `Volumes`. ``` $ aws ec2 describe-volumes \ --query 'Volumes[*].Attachments[*].State' [ [ "attached" ], [ "attached" ], [ "attached" ] ] ``` ### Aplanamiento de los resultados Para obtener más información, consulte [SubExpresiones](https://jmespath.org/specification.html#subexpressions) en el*Sitio web JMESPath*. Puede aplanar los resultados de `Volumes[*].Attachments[*].State` eliminando la notación comodín que resulta en la consulta `Volumes[*].Attachments[].State`. El aplanamiento a menudo es útil para mejorar la legibilidad de los resultados. ``` $ aws ec2 describe-volumes \ --query 'Volumes[*].Attachments[].State' [ "attached", "attached", "attached" ] ``` Para obtener más información, consulte [Aplanar](https://jmespath.org/specification.html#flatten) en el *Sitio web JMESPath*. ### Filtrado para valores específicos Para filtrar valores específicos de una lista, utilice una expresión de filtro como se muestra en la siguiente sintaxis. **Sintaxis** ``` ? ] ``` Los comparadores de expresiones incluyen `==`, `!=`, `<`, `<=`, `>` y `>=`. En el ejemplo siguiente se filtra para el `VolumeIds`, para todos los `Volumes` en un `Attached``State`. ``` $ aws ec2 describe-volumes \ --query 'Volumes[*].Attachments[?State==`attached`].VolumeId' [ [ "vol-e11a5288" ], [ "vol-2e410a47" ], [ "vol-a1b3c7nd" ] ] ``` Esto se puede aplanar, lo que resulta en el siguiente ejemplo. ``` $ aws ec2 describe-volumes \ --query 'Volumes[*].Attachments[?State==`attached`].VolumeId[]' [ "vol-e11a5288", "vol-2e410a47", "vol-a1b3c7nd" ] ``` En el ejemplo siguiente se filtra para el `VolumeIds`, de todos los `Volumes` que tienen un tamaño inferior a 20. ``` $ aws ec2 describe-volumes \ --query 'Volumes[?Size < `20`].VolumeId' [ "vol-2e410a47", "vol-a1b3c7nd" ] ``` Para obtener más información, consulte [Expresiones de filtro](https://jmespath.org/specification.html#filterexpressions) en el *Sitio web JMESPath*. ### Expresiones de canalización Puede canalizar los resultados de un filtro a una nueva lista y, a continuación, filtrar el resultado con otra expresión utilizando la siguiente sintaxis: **Sintaxis** ``` | ] ``` En el siguiente ejemplo se toman los resultados del filtro de la expresión `Volumes[*].Attachments[].InstanceId` y genera el primer resultado en la matriz. ``` $ aws ec2 describe-volumes \ --query 'Volumes[*].Attachments[].InstanceId | [0]' "i-a071c394" ``` En este ejemplo, se crea primero la matriz a partir de la siguiente expresión. ``` $ aws ec2 describe-volumes \ --query 'Volumes[*].Attachments[].InstanceId' "i-a071c394", "i-4b41a37c", "i-1jd73kv8" ``` Y luego devuelve el primer elemento de esa matriz. ``` "i-a071c394" ``` Para obtener más información, consulte [Expresiones de canalización](https://jmespath.org/specification.html#pipe-expressions) en el *Sitio web JMESPath*. ### Filtrado para varios valores de identificador Para filtrar por varios identificadores, utilice una lista de selección múltiple mediante la siguiente sintaxis: **Sintaxis** ``` [].[, ] ``` En el siguiente ejemplo, `VolumeId` y `VolumeType` se filtran en la lista `Volumes` lo que resulta en la siguiente expresión. ``` $ aws ec2 describe-volumes \ --query 'Volumes[].[VolumeId, VolumeType]' [ [ "vol-e11a5288", "standard" ], [ "vol-2e410a47", "standard" ], [ "vol-a1b3c7nd", "standard" ] ] ``` Para agregar datos anidados a la lista, agregue otra lista de selección múltiple. El siguiente ejemplo amplía el ejemplo anterior al filtrar también `InstanceId` y `State` en la lista de `Attachments` anidada. Esto da como resultado la siguiente expresión. ``` $ aws ec2 describe-volumes \ --query 'Volumes[].[VolumeId, VolumeType, Attachments[].[InstanceId, State]]' [ [ "vol-e11a5288", "standard", [ [ "i-a071c394", "attached" ] ] ], [ "vol-2e410a47", "standard", [ [ "i-4b41a37c", "attached" ] ] ], [ "vol-a1b3c7nd", "standard", [ [ "i-1jd73kv8", "attached" ] ] ] ] ``` Para que sea más legible, aplane la expresión como se muestra en el siguiente ejemplo. ``` $ aws ec2 describe-volumes \ --query 'Volumes[].[VolumeId, VolumeType, Attachments[].[InstanceId, State][]][]' [ "vol-e11a5288", "standard", [ "i-a071c394", "attached" ], "vol-2e410a47", "standard", [ "i-4b41a37c", "attached" ], "vol-a1b3c7nd", "standard", [ "i-1jd73kv8", "attached" ] ] ``` Para obtener más información, consulte la [Lista de selección múltiple](https://jmespath.org/specification.html#multiselectlist) en el *Sitio web JMESPath*. ### Agregado de etiquetas a valores de identificador Para facilitar la lectura de este resultado, utilice un hash de selección múltiple con la siguiente sintaxis. **Sintaxis** ``` [].{