Parámetros de sustitución de trabajos AWS IoT Preparación del documento de trabajo y la versión del paquete para su implementación Asignar un nombre a los paquetes y las versiones al desplegarlos Segmentar los trabajos mediante grupos de cosas AWS IoT dinámicos Versiones reservadas de paquetes y sombras con nombre Desinstalar un paquete de software

Preparando trabajos AWS IoT

El catálogo de paquetes de software AWS IoT Device Management amplía Trabajos AWS IoT mediante parámetros de sustitución y la integración con la indexación de flotas AWS IoT, los grupos dinámicos de cosas y la sombra con nombre reservada de la cosa AWS IoT.

nota

Para utilizar todas las funciones que ofrece el Catálogo de paquetes de software, debe crear estas funciones y políticas (roles de IAM)AWS Identity and Access Management: derechos de trabajo AWS IoT para implementar versiones de paquetes y derechos de trabajo AWS IoT para actualizar la sombra reservada denominada. Para más información, consulte Preparación de la seguridad.

Parámetros de sustitución de trabajos AWS IoT

Puede utilizar los parámetros de sustitución como marcador de posición en el documento de trabajo AWS IoT. Cuando el servicio de trabajos encuentra un parámetro de sustitución, dirige el trabajo al atributo de una versión de software determinada para el valor del parámetro. Puede utilizar este proceso para crear un único documento de trabajo y pasar los metadatos al trabajo mediante atributos de uso general. Por ejemplo, puede pasar una URL de Amazon Simple Storage Service (Amazon S3), un paquete de Nombre de recurso de Amazon (ARN) o una firma en el documento de trabajo mediante los atributos de la versión del paquete.

Los parámetros de sustitución debe tener el siguiente formato en el documento de trabajo:

Nombre del paquete de software y versión del paquete
- La cadena vacía entre package::version representa el parámetro de sustitución del nombre del paquete de software. La cadena vacía entre version::attribute representa el parámetro de sustitución de la versión del paquete de software. Consulte el siguiente ejemplo para utilizar el nombre del paquete y los parámetros de sustitución de la versión de paquete en un documento de trabajo: ${aws:iot:package::version::attributes:<attributekey>}.
- El documento de trabajo rellenará automáticamente estos parámetros de sustitución con el ARN de la versión de los detalles de la versión del paquete. Si va a crear un trabajo o una plantilla de trabajo para una implementación de paquete único mediante un comando de la API o la CLI, el ARN de la versión de una versión de paquete se representa con el parámetro destinationPackageVersions en CreateJob y DescribeJob.
Todos los atributos para una versión de paquete de software
- Consulte el siguiente ejemplo para utilizar todos los atributos de un parámetro de sustitución de la versión de un paquete de software en un documento de trabajo: ${aws:iot:package:<packageName>:version:<versionName>:attributes}.

nota

El nombre del paquete, la versión del paquete y todos los parámetros de sustitución de los atributos se pueden utilizar juntos. Consulte el siguiente ejemplo para utilizar los tres parámetros de sustitución en un documento de trabajo: ${aws:iot:package::version::attributes}.

En el siguiente ejemplo, hay un paquete de software denominado samplePackage que tiene una versión de paquete denominada 2.1.5 con los siguientes atributos:

Nombre: s3URL, valor: https://EXAMPIEBUCKET.s3.us-west-2.amazonaws.com/exampleCodeFile
- Este atributo identifica la ubicación del archivo de código almacenado en Amazon S3.
Nombre: signature, valor: aaaaabbbbbcccccdddddeeeeefffffggggghhhhhiiiiijjjj
- Este atributo proporciona un valor de firma de código que el dispositivo requiere como medida de seguridad. Para obtener más información, consulte Firma de código para trabajos. Nota: Este atributo es un ejemplo y no es obligatorio como parte del catálogo de paquetes de software ni de los trabajos.

En el caso de s3URL, el parámetro del documento de trabajo se escribe de la siguiente manera:


{
"samplePackage": "${aws:iot:package:samplePackage1:version:2.1.5:attributes:s3URL}"
}

En el caso de signature, el parámetro del documento de trabajo se escribe de la siguiente manera:


{
"samplePackage": "${aws:iot:package:samplePackage1:version:2.1.5:attributes:signature}"
}

El documento de trabajo completo está redactado de la siguiente manera:


{
  ...
  "Steps": {
    "uninstall": ["samplePackage"],
    "download": [ 
      { 
        "samplePackage": "${aws:iot:package:samplePackage1:version:2.1.5:attributes:s3URL}"
      },
    ],
    "signature": [
      "samplePackage" : "${aws:iot:package:samplePackage1:version:2.1.5:attributes:signature}"
    ]
  }
}

Una vez realizada la sustitución, se implementa el siguiente documento de trabajo en los dispositivos:


{
  ...
  "Steps": {
    "uninstall": ["samplePackage"],
    "download": [ 
      { 
        "samplePackage": "https://EXAMPIEBUCKET.s3.us-west-2.amazonaws.com/exampleCodeFile"
      },
    ],
    "signature": [
      "samplePackage" : "aaaaabbbbbcccccdddddeeeeefffffggggghhhhhiiiiijjjj"
    ]
  }
}

Parámetros de sustitución (vista antes y después)

Los parámetros de sustitución simplifican la creación de un documento de trabajo con varios indicadores, como $default para la versión de paquete predeterminada. Esto elimina la necesidad de introducir manualmente los metadatos de la versión específica del paquete para cada implementación de trabajo, ya que esos indicadores se rellenan automáticamente con los metadatos a los que se hace referencia en la versión específica del paquete. Para obtener más información sobre los atributos de la versión del paquete, como $default para la versión del paquete predeterminada, consulte Preparación del documento de trabajo y la versión del paquete para su implementación.

En la AWS Management Console, active el botón Vista previa de la sustitución de la ventana del Editor del archivo de instrucciones de implementación durante la implementación de una versión de paquete para ver el documento de trabajo con y sin los parámetros de sustitución.

Con el parámetro “before-substitution” en las API DescribeJob y GetJobDocument, puede ver la respuesta de la API antes y después de eliminar los parámetros de sustitución. Consulte los siguientes ejemplos con las API DescribeJob y GetJobDocument:

DescribeJob

Vista predeterminada


{
    "jobId": "<jobId>",
    "description": "<description>",
    "destinationPackageVersions": ["arn:aws:iot:us-west-2:123456789012:package/TestPackage/version/1.0.2"]
}

Antes de la vista de sustitución


{
    "jobId": "<jobId>",
    "description": "<description>",
    "destinationPackageVersions": ["arn:aws:iot:us-west-2:123456789012:package/TestPackage/version/$default"]
}

GetJobDocument

Vista predeterminada


{
    "attributes": {
        "location": "prod-artifacts.s3.us-east-1.amazonaws.com/mqtt-core",
        "signature": "IQoJb3JpZ2luX2VjEIrwEaCXVzLWVhc3QtMSJHMEUCIAofPNPpZ9cI",
        "streamName": "mqtt-core",
        "fileId": "0"
    },
}

Antes de la vista de sustitución


{
    "attributes": "${aws:iot:package:TestPackage:version:$default:attributes}",
}

Para más información sobre trabajos, creación de documentos de trabajo AWS IoT y despliegue de trabajos, consulte Trabajos.

Preparación del documento de trabajo y la versión del paquete para su implementación

Cuando se crea una versión de paquete, tiene el estado de draft, lo que indica que se está preparando para su implementación. Para preparar la versión del paquete para la implementación, debe crear un documento de trabajo, guardar el documento en una ubicación a la que pueda acceder el trabajo (como Amazon S3) y confirmar que la versión del paquete tiene los valores de atributo que desea que utilice el documento de trabajo. (Nota: Puede actualizar los atributos de una versión del paquete mientras tenga el estado draft).

Al crear un trabajo o una plantilla de trabajo de AWS IoT para una implementación de paquete único, tiene las siguientes opciones para personalizar su documento de trabajo:

Archivo de instrucciones de implementación (recipe)

El archivo de instrucciones de implementación de una versión de paquete contiene las instrucciones de implementación, incluido un documento de trabajo en línea, para implementar una versión de paquete en varios dispositivos. El archivo asocia instrucciones de implementación específicas a una versión de paquete para una implementación rápida y eficiente del trabajo.

En la AWS Management Console, puede crear el archivo en la ventana Vista previa del archivo de instrucciones de implementación de la pestaña Configuraciones de implementación de versiones del flujo de trabajo de creación de un paquete nuevo. Puede aprovechar AWS IoT para generar automáticamente un archivo de instrucciones a partir de los atributos de la versión de su paquete con Comience desde el archivo recomendado de AWS IoT o utilizar su documento de trabajo existente almacenado en un bucket de Amazon S3 mediante Utilice su propio archivo de instrucciones de implementación.

nota
Si utiliza su propio documento de trabajo, puede actualizarlo directamente en la ventana de Vista previa del archivo de instrucciones de implementación, pero no actualizará automáticamente el documento de trabajo original almacenado en su bucket de Amazon S3.

Cuando utilice el comando AWS CLI o un comando de la API, como CreatePackageVersion, GetPackageVersion o UpdatePackageVersion, recipe representa el archivo de instrucciones de implementación, que incluye un documento de trabajo en línea.

Para obtener más información sobre lo que es un documento de trabajo, consulte Conceptos básicos.

Consulte el siguiente ejemplo para ver el archivo de instrucciones de implementación tal como lo representa recipe:
```
{
    "packageName": "sample-package-name",
    "versionName": "sample-package-version",
    ...
    "recipe": "{...}"
}
```
nota
El archivo de instrucciones de implementación tal como lo representa recipe se puede actualizar cuando una versión de paquete tiene el estado published, ya que es independiente de los metadatos de la versión del paquete. Se vuelve inmutable durante la implementación del trabajo.

Atributo de la versión de Artifact

Con el atributo de la version de artifact de la versión de su paquete de software, puede añadir la ubicación de Amazon S3 para los artefactos de la versión del paquete. Cuando se desencadena la implementación de un trabajo para la versión de su paquete con AWS IoT Jobs, el marcador de posición de URL prefirmada ${aws:iot:package:<packageName>:version:<versionName>:artifact-location:s3-presigned-url} del documento de trabajo se actualizará con el bucket de Amazon S3, la clave del bucket y la versión del archivo almacenado en el bucket de Amazon S3. El bucket de Amazon S3 que almacena los artefactos de la versión de paquete debe estar ubicado en la misma región en la que se creó la versión del paquete.

nota
Para almacenar varias versiones de objetos del mismo archivo en su bucket de Amazon S3, debe activar el control de versiones en su bucket. Para obtener más información, consulte Habilitar el control de versiones en buckets.

Para acceder a los artefactos de la versión del paquete en el bucket de Amazon S3 al utilizar la operación de la API CreatePackageVersion o UpdatePackageVersion, debe tener los siguientes permisos:
```
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "s3:GetObjectVersion",
            "Resource": "arn:<partition>:s3:::<bucket>/<key>"
        }
    ]
}
```
Para obtener más información sobre el atributo de versión artifact en las operaciones de la API CreatePackageVersion y UpdatePackageVersion, consulte CreatePackageVersion y UpdatePackageVersion.

Consulte el siguiente ejemplo, que muestra el atributo de versión artifact que admite la ubicación del artefacto en Amazon S3 al crear una nueva versión del paquete:
```
{
    "packageName": "sample package name",
    "versionName": "1.0",
    "artifact": {
        "s3Location": {
            "bucket": "firmware",
            "key": "image.bin",
            "version": "12345"
        }
    }
}
```
nota
Cuando la versión de paquete se actualiza de un estado draft a otro estado published, los atributos de la versión del paquete y la ubicación del artefacto se vuelven inmutables. Para actualizar esta información, debe crear una nueva versión del paquete y realizar esas actualizaciones mientras tenga el estado draft.

Versión de paquete

Se puede indicar una versión de paquete de software predeterminada en las versiones disponibles del paquete de software, lo que proporciona una versión de paquete segura y estable. Además, sirve como versión básica del paquete de software al implementar la versión de paquete predeterminada en su flota de dispositivos mediante AWS IoT Jobs. Al crear un trabajo para implementar la versión de paquete $default para un paquete de software, la versión del paquete del documento de trabajo y la de la nueva implementación del trabajo deben coincidir como $default. La versión del paquete en la implementación del trabajo está representada por destinationPackageVersions para los comandos de la API y la CLI y VersionARN en AWS Management Console. La versión del paquete en el documento de trabajo se representa mediante el siguiente marcador de posición del documento de trabajo que se muestra a continuación:
```
arn:aws:iot:<regionCode>:111122223333:package/<packageName>/version/$default
```
Para crear un trabajo o una plantilla de trabajo con la versión de paquete predeterminada, utilice la marca $default en el comando de la API CreateJob o CreateJobTemplate, tal como se muestra a continuación:
```
"$ aws iot create-job \
    --destination-package-versions "arn:aws:iot:us-west-2:123456789012:package/TestPackage/version/$default"
    --document file://jobdoc.json
```
nota
El atributo de versión de paquete $default que hace referencia a la versión predeterminada es un atributo opcional que solo se requiere cuando se hace referencia a la versión del paquete predeterminada para la implementación de un trabajo mediante AWS IoT Jobs.

Cuando dé el visto bueno a la versión del paquete, publíquela a través de la página de detalles del paquete de software en la consola de AWS IoT o emitiendo la operación de la API UpdatePackageVersion. A continuación, puede hacer referencia a la versión del paquete al crear el trabajo a través de la consola de AWS IoT o emitiendo la operación de la API CreateJob.

Asignar un nombre a los paquetes y las versiones al desplegarlos

Para implementar una versión de paquete de software en un dispositivo, confirme que el paquete de software y la versión del paquete a los que se hace referencia en el documento de trabajo coincidan con el paquete de software y la versión del paquete indicados en el parámetro destinationPackageVersions de la operación de la API CreateJob. Si no coinciden, recibirá un mensaje de error en el que se le pedirá que haga que ambas referencias coincidan. Para obtener más información sobre los mensajes de error del Catálogo de paquetes de software, consulte Mensajes de error de la resolución de problemas general.

Además de los paquetes de software y las versiones de paquete a los que se hace referencia en el documento de trabajo, puede incluir paquetes de software y versiones de paquetes adicionales en el parámetro destinationPackageVersions de la operación de la API CreateJob a los que no se hace referencia en el documento de trabajo. Asegúrese de incluir la información de instalación necesaria en el documento de trabajo para que los dispositivos instalen correctamente las versiones adicionales del paquete de software. Para obtener más información acerca de la operación de la API CreateJob, consulte CreateJob.

Segmentar los trabajos mediante grupos de cosas AWS IoT dinámicos

El Catálogo de paquetes de software funciona con la indexación de flotas, los trabajos AWS IoT y los grupos de cosas AWS IoT dinámicos para filtrar y segmentar los dispositivos de su flota para seleccionar qué versión de paquete implementar en sus dispositivos. Puede ejecutar una consulta de indexación de la flota en función de la información actual del paquete de su dispositivo y segmentar esos elementos para una tarea AWS IoT específica. También puede lanzar actualizaciones de software, pero sólo a los dispositivos de destino elegibles. Por ejemplo, puede especificar que desea implementar una configuración solo en los dispositivos en los que actualmente se ejecuta iot-device-client 1.5.09. Para más información, consulte Crear un grupo de cosas dinámico.

Versiones reservadas de paquetes y sombras con nombre

Si está configurado, Trabajos AWS IoT puede actualizar la reserva de una cosa llamada sombra ($package) cuando la tarea se complete correctamente. Si lo hace, no necesita asociar manualmente la versión de un paquete a la versión reservada de una cosa llamada shadow.

Puede optar por asociar o actualizar manualmente una versión de paquete a la sombra de nombre reservado de la cosa en las siguientes situaciones:

Se registra una cosa a AWS IoT Core sin asociar la versión del paquete instalado.
Trabajos AWS IoT no está configurado para actualizar la cosa reservada llamada sombra.
Utiliza un proceso interno para enviar versiones de paquetes a su flota y ese proceso no actualiza AWS IoT Core cuando finaliza.

nota

Le recomendamos que utilice Trabajos AWS IoT para actualizar la versión del paquete en la sombra de nombre reservado ($package). Si se actualiza el parámetro de versión en la sombra $package mediante otros procesos (por ejemplo, llamadas a la API manuales o programáticas) y Trabajos AWS IoT también está configurado para actualizar la sombra, se pueden producir incoherencias entre la versión real del dispositivo y la versión reportada a la versión reservada denominada sombra.

Puede añadir o actualizar la versión de un paquete a una versión reservada llamada sombra ($package) mediante la consola o la operación de la API UpdateThingShadow. Para obtener más información, consulte Cómo asociar una versión de paquete a una cosa AWS IoT.

nota

Al asociar una versión de paquete a una cosa AWS IoT, no se actualiza directamente el software del dispositivo. Debe implementar la versión del paquete en el dispositivo para actualizar el software del dispositivo.

Desinstalación de un paquete de software y de su versión

$null es un marcador de posición reservado que solicita al servicio Trabajos AWS IoT que elimine el paquete de software y la versión del paquete existentes de la sombra reservada con nombre del dispositivo $package. Para obtener más información, consulte Sombra con nombre reservado.

Para utilizar esta característica, sustituya el nombre de versión al final del Nombre de recurso de Amazon (ARN) de la versión al final del Nombre de recurso de Amazon (ARN) de DestinationPackageVersion por $null. Después, debe indicar a su servicio que elimine el software del dispositivo.

El ARN autorizado utiliza el siguiente formato:


arn:aws:iot:<regionCode>:111122223333:package/<packageName>/version/$null

Por ejemplo:


$ aws iot create-job \
    ... \
    --destinationPackageVersions ["arn:aws:iot:us-east-1:111122223333:package/samplePackage/version/$null"]

Aviso JavaScript está desactivado o no está disponible en su navegador.

Para utilizar la documentación de AWS, debe estar habilitado JavaScript. Para obtener más información, consulte las páginas de ayuda de su navegador.

Convenciones del documento

Preparación para la indexación de flotas

Introducción