Especificación de configuraciones de trabajo mediante la API de trabajos de AWS IoT

Puede usar la API CreateJobo la CreateJobTemplateAPI para especificar las diferentes configuraciones de trabajo. En las siguientes secciones se describe cómo añadir estas configuraciones. Una vez agregadas las configuraciones, puede JobExecutionSummaryutilizarlas y JobExecutionSummaryForJobver su estado.

Para obtener más información sobre las diferentes configuraciones y cómo funcionan, consulte Cómo funcionan las configuraciones de trabajos.

Configuración de despliegue

Puede especificar una velocidad de despliegue constante o exponencial para la configuración de despliegue.

• Establecimiento de una velocidad de despliegue constante

  Para establecer una velocidad de despliegue constante, use el objeto JobExecutionsRolloutConfig para añadir el parámetro maximumPerMinute a la solicitud CreateJob. Este parámetro especifica el límite superior de la velocidad a la cual pueden producirse las ejecuciones de los trabajos. Este valor es opcional y va de 1 a 1000. Si no se establece, se usará 1000 como valor predeterminado.

      "jobExecutionsRolloutConfig": {
          "maximumPerMinute": 1000
      } 

• Establecimiento de una velocidad de despliegue exponencial

  Para establecer una velocidad de despliegue de trabajos variable, utilice el objeto JobExecutionsRolloutConfig. Puede configurar la propiedad ExponentialRolloutRate al ejecutar la operación CreateJob de la API. En el siguiente ejemplo se establece una velocidad de despliegue exponencial mediante el parámetro exponentialRate. Para obtener más información sobre los parámetros, consulte ExponentialRolloutRate.

  {
  ...
    "jobExecutionsRolloutConfig": {
      "exponentialRate": {
        "baseRatePerMinute": 50,
        "incrementFactor": 2,
        "rateIncreaseCriteria": {
          "numberOfNotifiedThings": 1000,
          "numberOfSucceededThings": 1000
        },
        "maximumPerMinute": 1000
      }
    }
  ...
  }                       

Donde el parámetro:

baseRatePerMinuto

Especifica la velocidad a la cual se ejecutan los trabajos hasta llegar al umbral numberOfNotifiedThings o numberOfSucceededThings.

incrementFactor

Especifica el factor exponencial según el cual aumenta la velocidad de despliegue tras alcanzar el umbral numberOfNotifiedThings o numberOfSucceededThings.

rateIncreaseCriteria

Especifica el umbral numberOfNotifiedThings o numberOfSucceededThings.

Configuración de anulación

Para añadir esta configuración mediante la API, especifique el parámetro AbortConfig al ejecutar la operación CreateJob o CreateJobTemplate de la API. En el siguiente ejemplo, se muestra una configuración de anulación para el despliegue de un trabajo que estaba experimentando varias ejecuciones fallidas, tal y como se especificó en la operación CreateJob de la API.

nota

Eliminar la ejecución de un trabajo afecta al valor de cálculo del total de ejecuciones realizadas. Cuando se anula un trabajo, el servicio crea valores comment y reasonCode automáticos para diferenciar una cancelación promovida por un usuario de una de anulación de un trabajo.

   "abortConfig": { 
      "criteriaList": [ 
         { 
            "action": "CANCEL",
            "failureType": "FAILED",
            "minNumberOfExecutedThings": 100,
            "thresholdPercentage": 20
         },
         { 
            "action": "CANCEL",
            "failureType": "TIMED_OUT",
            "minNumberOfExecutedThings": 200,
            "thresholdPercentage": 50
         }
      ]
    }            

Donde el parámetro:

action

Especifica la acción que se debe realizar cuando se han cumplido los criterios de anulación. Este parámetro es necesario y CANCEL es el único valor válido.

failureType

Especifica qué tipos de error deben iniciar la anulación de un trabajo. Los valores válidos son FAILED, REJECTED, TIMED_OUT y ALL.

minNumberOfExecutedThings

Especifica el número de ejecuciones de trabajos completadas que deben ocurrir antes de que se cumplan los criterios de anulación del trabajo. En este ejemplo, AWS IoT no comprueba si se debe anular un trabajo hasta que al menos 100 dispositivos hayan completado ejecuciones de trabajos.

thresholdPercentage

Especifica el número total de objetos para los que se ejecutan trabajos que pueden iniciar la anulación de un trabajo. En este ejemplo, AWS IoT comprueba secuencialmente e inicia una anulación del trabajo si se alcanza el porcentaje límite. Si al menos el 20 % de las ejecuciones completas fallan una vez finalizadas 100 ejecuciones, se cancela el despliegue del trabajo. Si no se cumple este criterio, comprueba si se ha AWS IoT agotado el tiempo de espera de al menos el 50% de las ejecuciones completadas una vez finalizadas 200 ejecuciones. Si este es el caso, se cancela el despliegue del trabajo.

Configuración de programación

Para añadir esta configuración mediante la API, especifique la SchedulingConfig opcional al ejecutar la operación CreateJob o CreateJobTemplate de la API.

    "SchedulingConfig": { 
      "endBehavior": string
      "endTime": string
      "maintenanceWindows": string
      "startTime": string
   }

Donde el parámetro:

startTime

Especifica la fecha y la hora en que se iniciará el trabajo.

endTime

Especifica la fecha y la hora en que finalizará el trabajo.

maintenanceWindows

Especifica si se ha seleccionado un periodo de mantenimiento opcional para el trabajo programado a fin de desplegar el documento de trabajo en todos los dispositivos del grupo de destino. El formato de cadena para maintenanceWindow es AAAA/MM/DD para la fecha y hh:mm para la hora.

endBehavior

Especifica el comportamiento de un trabajo programado al llegar al endTime.

nota

La SchedulingConfig opcional para un trabajo se puede ver en las API DescribeJob y DescribeJobTemplate.

Configuración de tiempo de espera

Para añadir esta configuración mediante la API, especifique el parámetro TimeoutConfig al ejecutar la operación CreateJob o CreateJobTemplate de la API.

Para usar la configuración de tiempo de espera

1. Para configurar el temporizador en curso al crear un trabajo o una plantilla de trabajo, defina un valor para la inProgressTimeoutInMinutes propiedad del objeto opcional TimeoutConfig.

       "timeoutConfig": { 
         "inProgressTimeoutInMinutes": number
      }

2. Para especificar un temporizador gradual para la ejecución de un trabajo, defina un valor para stepTimeoutInMinutes cuando llame UpdateJobExecution. El temporizador de pasos se aplica únicamente a la ejecución del trabajo que actualice. Puede establecer un nuevo valor para este temporizador cada vez que actualice la ejecución de un trabajo.

   nota

   UpdateJobExecution puede descartar un temporizador de pasos que ya se ha creado mediante la creación de un nuevo temporizador de pasos con un valor de -1.

   {
      ... 
       "statusDetails": { 
         "string" : "string" 
      },
      "stepTimeoutInMinutes": number
   }

3. Para crear un nuevo temporizador por pasos, también puedes llamar a la operación de la StartNextPendingJobExecutionAPI.

Configuración de reintentos

nota

Al crear un trabajo, tenga en cuenta el número adecuado de reintentos que desee utilizar en la configuración. Para evitar incurrir en costes excesivos debido a posibles errores en los reintentos, añada una configuración de anulación. Una vez creado un trabajo, no se puede actualizar el número de reintentos. Solo puedes establecer el número de reintentos en 0 mediante la operación de UpdateJobAPI.

Para añadir esta configuración mediante la API, especifique el parámetro jobExecutionsRetryConfig al ejecutar la operación CreateJob o CreateJobTemplate de la API.

{
...
  "jobExecutionsRetryConfig": { 
      "criteriaList": [ 
         { 
            "failureType": "string",
            "numberOfRetries": number
         }
      ]
  }
...
}                       

Donde criteriaList es una matriz que especifica la lista de criterios que determina el número de reintentos permitidos para cada tipo de error de un trabajo.