Preparando trabajos AWS IoT

AWS IoT Device Management Software Package Catalog amplía las AWS IoT tareas mediante parámetros de sustitución e integración con la indexación de AWS IoT flotas, los grupos de cosas dinámicos y la AWS IoT cosa reservada llamada shadow.

nota

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

Parámetros de sustitución de AWS IoT trabajos

Puede utilizar los parámetros de sustitución como marcador de posición en el documento de AWS IoT trabajo. 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 un Amazon Simple Storage Service (Amazon S3)URL, un paquete de software Amazon Resource Name (ARN) o una firma en el documento de trabajo mediante los atributos de la versión del paquete.

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

• Nombre del paquete de software y versión del paquete

  • La cadena vacía intermedia package::version representa el parámetro de sustitución del nombre del paquete de software. La cadena vacía intermedia 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 del 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 utilizando la versión que aparece en los detalles de la versión ARN del paquete. Si va a crear un trabajo o una plantilla de trabajo para una implementación de paquete único mediante un CLI comando API o, la versión de una versión ARN de paquete se representa mediante el destinationPackageVersions parámetro en y. CreateJob DescribeJob

• Todos los atributos de una versión de Software Package

  • 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 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 ejemplo siguiente, hay un paquete de software denominado samplePackage y tiene una versión de paquete denominada 2.1.5 que tiene 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 anterior y posterior)

Los parámetros de sustitución simplifican la creación de un documento de trabajo utilizando varios indicadores, como $default los de la versión del paquete por defecto. Esto elimina la necesidad de introducir manualmente los metadatos de la versión específica del paquete para cada despliegue 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 la versión del paquete predeterminada, consulte. Preparación del documento de trabajo y la versión del paquete para su implementación

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

Si utiliza el parámetro «antes de la sustitución» en DescribeJob y GetJobDocumentAPIs, podrá ver la API respuesta antes y después de eliminar los parámetros de sustitución. Consulte los siguientes ejemplos con las letras y: DescribeJob GetJobDocument APIs

• DescribeJob

  • Vista predeterminada

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

  • Vista anterior a la 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"
        },
    }

  • Vista anterior a la sustitución

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

Para obtener más información sobre los AWS IoT trabajos, la creación de documentos de trabajo y la implementación de trabajos, consulte Jobs.

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

Cuando se crea una versión de paquete, está en un draft estado que indica que se está preparando para su despliegue. Para preparar la versión del paquete para su despliegue, 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: solo puede actualizar los atributos de una versión de paquete mientras esté en ese draft estado).

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

Archivo de instrucciones de despliegue () recipe

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

  En él AWS Management Console, puede crear el archivo en la ventana de vista previa del archivo de instrucciones de despliegue de la pestaña Configuraciones de despliegue 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 mediante Start from AWS IoT recommended file o utilizar su documento de trabajo existente almacenado en un bucket de Amazon S3 mediante Use your own deployment instruction file.

  nota

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

  Al utilizar el AWS CLI o un API comando comoCreatePackageVersion, o GetPackageVersionUpdatePackageVersion, recipe representa el archivo de instrucciones de despliegue, que incluye un documento de trabajo en línea.

  Para obtener más información sobre qué es un documento de trabajo, consulteConceptos básicos.

  Consulte el siguiente ejemplo para ver el archivo de instrucciones de despliegue representado porrecipe:

  {
      "packageName": "sample-package-name",
      "versionName": "sample-package-version",
      ...
      "recipe": "{...}"
  }

  nota

  El archivo de instrucciones de despliegue, representado por, se recipe puede actualizar cuando la versión de un paquete se encuentra en el published estado de estado, ya que es independiente de los metadatos de la versión del paquete. Se vuelve inmutable durante el despliegue del trabajo.

Artifactatributo de versión

• Con el atributo version de artifact 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 el despliegue de un trabajo para la versión de su paquete mediante AWS IoT Jobs, el URL marcador ${aws:iot:package:<packageName>:version:<versionName>:artifact-location:s3-presigned-url} de posición prefirmado 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 depósito de Amazon S3 que almacena los artefactos de la versión del 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 habilitar 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 UpdatePackageVersion API operación CreatePackageVersion o, 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 UpdatePackageVersion API operaciones CreatePackageVersion y, consulte CreatePackageVersiony UpdatePackageVersion.

  Consulte el siguiente ejemplo, que muestra el atributo de versión que artifact admite la ubicación del artefacto en Amazon S3 al crear una nueva versión de paquete:

  {
      "packageName": "sample package name",
      "versionName": "1.0",
      "artifact": {
          "s3Location": {
              "bucket": "firmware",
              "key": "image.bin",
              "version": "12345"
          }
      }
  }

  nota

  Cuando la versión de un paquete se actualiza de un draft estado a otro published estado, 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 se encuentre en el estado de estado. draft

Versión Package

• 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. Sirve como versión básica del paquete de software al implementar la versión predeterminada del paquete en su flota de dispositivos mediante AWS IoT Jobs. Al crear un trabajo para implementar la versión de $default paquete de un paquete de software, la versión del paquete del documento de trabajo y la del nuevo despliegue del trabajo deben coincidir como$default. La versión del paquete en la implementación del trabajo se representa mediante CLI los comandos destinationPackageVersions for API y 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 $default marca del CreateJobTemplate API comando CreateJob o, 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 $default del paquete 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 esté satisfecho con la versión del paquete, publíquela en la página de detalles del paquete de software de la AWS IoT consola o ejecute la UpdatePackageVersionAPIoperación. A continuación, puede hacer referencia a la versión del paquete al crear el trabajo a través de la AWS IoT consola o ejecutando la CreateJobAPIoperación.

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 destinationPackageVersions parámetro de la CreateJob API operación. Si no coinciden, recibirá un mensaje de error en el que se le pedirá que haga coincidir ambas referencias. Para obtener más información sobre los mensajes de error del Catálogo de Paquetes de Software, consulteMensajes de error generales de solución de problemas.

Además de los paquetes de software y las versiones de paquetes a los que se hace referencia en el documento de trabajo, puede incluir paquetes de software y versiones de paquetes adicionales en el destinationPackageVersions parámetro de la CreateJob API operación a los que no se hace referencia en el documento de trabajo. Asegúrese de incluir en el documento de trabajo la información de instalación necesaria para que los dispositivos instalen correctamente las versiones adicionales del paquete de software. Para obtener más información sobre la CreateJob API operación, 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. Puedes ejecutar una consulta de indexación de flotas basada en la información actual del paquete de tu dispositivo y segmentar esas cosas para un AWS IoT trabajo. 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, AWS IoT Jobs puede actualizar la reserva de una cosa llamada shadow ($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 algo AWS IoT Core sin asociar la versión del paquete instalado.

• AWS IoT Jobs no está configurado para actualizar la cosa reservada llamada shadow.

• Utilizas un proceso interno para enviar las versiones de los paquetes a tu flota y ese proceso no AWS IoT Core se actualiza cuando finaliza.

nota

Te recomendamos que utilices AWS IoT Jobs para actualizar la versión del paquete en la sección reservada denominada shadow ($package). Si se actualiza el parámetro de versión en la $package sombra mediante otros procesos (por ejemplo, API llamadas manuales o programáticas) y AWS IoT Jobs 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 shadow.

Puedes añadir o actualizar la versión de un paquete a una versión reservada llamada shadow ($package) a través de la consola o de la operación. UpdateThingShadowAPI Para obtener más información, consulte Asociar una versión de paquete a una AWS IoT cosa.

nota

Al asociar una versión de paquete a una AWS IoT cosa, 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

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

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

El autorizado ARN 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"]