本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 使用任務 API 指定 AWS IoT 任務組態
您可以使用 [CreateJob](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJob.html) 或 [CreateJobTemplate](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJobTemplate.html) API 來指定不同的任務組態。下列各節描述如何新增這些組態。新增組態後，您可以使用 [JobExecutionSummary](https://docs.aws.amazon.com/iot/latest/apireference/API_JobExecutionSummary.html) 和 [JobExecutionSummaryForJob](https://docs.aws.amazon.com/iot/latest/apireference/API_JobExecutionSummaryForJob.html) 來查看其狀態。
如需不同組態及其運作方式的詳細資訊，請參閱 [任務組態的運作方式](jobs-configurations-details.md)。
## 推展組態
您可以為推展組態指定恆定推展率或指數推展率。
+
**設定恆定推展率**
若要設定恆定推展率，請使用 [https://docs.aws.amazon.com/iot/latest/apireference/API_JobExecutionsRolloutConfig.html](https://docs.aws.amazon.com/iot/latest/apireference/API_JobExecutionsRolloutConfig.html) 物件將 `maximumPerMinute` 參數新增至 `CreateJob` 請求。此參數指定可以發生任務執行的速率上限。此值為選用值，範圍從 1 到 1000。如果未設定該值，則將使用 1000 作為預設值。
```
"jobExecutionsRolloutConfig": {
"maximumPerMinute": 1000
}
```
+
**設定指數推展率**
若要設定可變任務推展率，請使用 [https://docs.aws.amazon.com/iot/latest/apireference/API_JobExecutionsRolloutConfig.html](https://docs.aws.amazon.com/iot/latest/apireference/API_JobExecutionsRolloutConfig.html) 物件。您可以在執行 `CreateJob` API 操作時設定 `ExponentialRolloutRate` 屬性。以下範例使用 `exponentialRate` 參數來設定指數推展率。如需這些參數的詳細資訊，請參閱 [https://docs.aws.amazon.com/iot/latest/apireference/API_ExponentialRolloutRate.html](https://docs.aws.amazon.com/iot/latest/apireference/API_ExponentialRolloutRate.html)。
```
{
...
"jobExecutionsRolloutConfig": {
"exponentialRate": {
"baseRatePerMinute": 50,
"incrementFactor": 2,
"rateIncreaseCriteria": {
"numberOfNotifiedThings": 1000,
"numberOfSucceededThings": 1000
},
"maximumPerMinute": 1000
}
}
...
}
```
其中參數：
**baseRatePerMinute**
指定達到 `numberOfNotifiedThings` 或 `numberOfSucceededThings` 閾值之前的任務執行速率。
**incrementFactor**
指定推展率在達到 `numberOfNotifiedThings` 或 `numberOfSucceededThings` 閾值之後提高的指數因數。
**rateIncreaseCriteria**
指定 `numberOfNotifiedThings` 或 `numberOfSucceededThings` 閾值。
## 中止組態
若要使用 API 新增此組態，請在執行 [https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJob.html](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJob.html) 或 [https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJobTemplate.html](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJobTemplate.html) API 操作時指定 [https://docs.aws.amazon.com/iot/latest/apireference/API_AbortConfig.html](https://docs.aws.amazon.com/iot/latest/apireference/API_AbortConfig.html) 參數。以下範例顯示任務推展的中止組態，該組態經歷了多次失敗的執行，如 `CreateJob` API 操作所指定。
**注意**
刪除任務執行會影響已完成執行總數的計算值。當任務中止時，服務會建立自動化的 `comment` 和 `reasonCode`，以區分使用者驅動的取消和任務中止的取消。
```
"abortConfig": {
"criteriaList": [
{
"action": "CANCEL",
"failureType": "FAILED",
"minNumberOfExecutedThings": 100,
"thresholdPercentage": 20
},
{
"action": "CANCEL",
"failureType": "TIMED_OUT",
"minNumberOfExecutedThings": 200,
"thresholdPercentage": 50
}
]
}
```
其中參數：
**動作**
指定符合中止條件時所要採取的動作。此為必要參數，且 `CANCEL` 是唯一有效的值。
**failureType**
指定應啟動任務中止的失敗類型。有效值為 `FAILED`、`REJECTED`、`TIMED_OUT`、`ALL`。
**minNumberOfExecutedThings**
指定在符合任務中止條件之前，必須發生的任務執行完成數量。在此範例中， AWS IoT 不會檢查是否在至少 100 個裝置完成任務執行之前發生任務中止。
**thresholdPercentage**
針對可以啟動任務中止的已執行任務指定物件總數。在此範例中， 會依序 AWS IoT 檢查，並在達到閾值百分比時啟動任務中止。如果在 100 次執行完成後至少有 20% 的完成執行失敗，則會取消任務推展。如果不符合此條件， AWS IoT 則 會檢查至少 50% 的已完成執行是否在 200 個執行完成後逾時。如果發生情況，即會取消任務推展。
## Scheduling configuration (排程組態)
若要使用 API 新增此組態，請在執行 [https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJob.html](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJob.html) 或 [https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJobTemplate.html](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJobTemplate.html) API 操作時指定選用的 [https://docs.aws.amazon.com/iot/latest/apireference/API_SchedulingConfig.html](https://docs.aws.amazon.com/iot/latest/apireference/API_SchedulingConfig.html)。
```
"SchedulingConfig": {
"endBehavior": string
"endTime": string
"maintenanceWindows": string
"startTime": string
}
```
其中參數：
**startTime**
指定任務開始的日期和時間。
**endTime**
指定任務開始的日期和時間。
**maintenanceWindows**
指定是否為排程任務選取了選用維護時段，以便將任務文件推展至目標群組中的所有裝置。`maintenanceWindow` 的字串格式是日期為 YYYY/MM/DD，而時間則為 hh:mm。
**endBehavior**
指定排程任務到達 `endTime` 時的任務行為。
**注意**
可在 [https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeJob.html](https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeJob.html) 和 [https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeJobTemplate.html](https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeJobTemplate.html) API 中檢視任務的選擇性 `SchedulingConfig`。
## 逾時組態
若要使用 API 新增此組態，請在執行 [https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJob.html](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJob.html) 或 [https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJobTemplate.html](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJobTemplate.html) API 操作時指定 [https://docs.aws.amazon.com/iot/latest/apireference/API_TimeoutConfig.html](https://docs.aws.amazon.com/iot/latest/apireference/API_TimeoutConfig.html) 參數。
使用逾時組態
1. 若要在建立任務或任務範本時設定進行中計時器，請為選用 [TimeoutConfig](https://docs.aws.amazon.com//iot/latest/apireference/API_TimeoutConfig.html) 物件的 `inProgressTimeoutInMinutes` 屬性設定值。
```
"timeoutConfig": {
"inProgressTimeoutInMinutes": number
}
```
1. 若要針對任務執行指定步驟計時器，您可在呼叫 [UpdateJobExecution](https://docs.aws.amazon.com//iot/latest/apireference/API_iot-jobs-data_UpdateJobExecution.html) 時設定 `stepTimeoutInMinutes` 的值。步驟計時器僅適用於您更新的任務執行。您可以在每次更新任務執行時，為此計時器設定新值。
**注意**
`UpdateJobExecution` 可以透過建立值為 -1 的新步驟計時器，來捨棄已建立的步驟計時器。
```
{
...
"statusDetails": {
"string" : "string"
},
"stepTimeoutInMinutes": number
}
```
1. 若要建立新的步驟計時器，還可以呼叫 [StartNextPendingJobExecution](https://docs.aws.amazon.com//iot/latest/apireference/API_iot-jobs-data_StartNextPendingJobExecution.html) API 操作。
## 重試組態
**注意**
建立任務時，請考慮用於組態的適當重試次數。為避免因潛在的重試失敗而產生超額成本，請新增中止組態。建立任務後，即無法更新重試次數。您僅可使用 [UpdateJob](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdateJob.html) API 操作將重試次數設定為 0。
若要使用 API 新增此組態，請在執行 [https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJob.html](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJob.html) 或 [https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJobTemplate.html](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJobTemplate.html) API 操作時指定 [https://docs.aws.amazon.com/iot/latest/apireference/API_jobExecutionsRetryConfig.html](https://docs.aws.amazon.com/iot/latest/apireference/API_jobExecutionsRetryConfig.html) 參數。
```
{
...
"jobExecutionsRetryConfig": {
"criteriaList": [
{
"failureType": "string",
"numberOfRetries": number
}
]
}
...
}
```
其中 **criteriaList** 是一個陣列，用於指定條件清單，可確定任務的每種失敗類型所允許的重試次數。