Jobs - Create Scheduled Job

  • 參考
Service:
IoT Hub
API Version:
2021-04-12

建立新的作業，以排程 IoT 中樞 上的對應項更新或直接方法。 如需相關資訊，請參閱 https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-devguide-jobs 。

PUT https://fully-qualified-iothubname.azure-devices.net/jobs/v2/{id}?api-version=2021-04-12

URI 參數

名稱 位於 必要 類型 Description
id
 path True

string

作業的唯一識別碼。
api-version
 query True

string

Api 的版本。

要求本文

名稱 類型 Description
cloudToDeviceMethod

CloudToDeviceMethod

方法類型和參數。 如果作業類型為 cloudToDeviceMethod，則需要此專案。
jobId

string

作業的唯一識別碼。
maxExecutionTimeInSeconds

integer

秒的運行時間上限。
queryCondition

string

要執行作業的裝置條件。 如果作業類型為 updateTwin 或 cloudToDeviceMethod，則需要此專案。
startTime

string

ISO 8601 標準中作業的開始日期和時間。
type enum:
  • unknown
  • export
  • import
  • backup
  • readDeviceProperties
  • writeDeviceProperties
  • updateDeviceConfiguration
  • rebootDevice
  • factoryResetDevice
  • firmwareUpdate
  • scheduleDeviceMethod
  • scheduleUpdateTwin
  • restoreFromBackup
  • failoverDataCopy

作業類型。
updateTwin

Twin

裝置或模組的狀態資訊。 這會在 IoT 中樞 中建立或刪除對應的裝置/模組身分識別時隱含建立和刪除。

回應

名稱 類型 Description
200 OK

JobResponse

正常。

定義

名稱 Description
CloudToDeviceMethod

在裝置上執行直接方法的參數。
DeviceCapabilities

裝置上啟用的功能狀態。
DeviceJobStatistics

有關執行狀態的作業統計數據。
JobRequest
JobResponse
Twin

裝置或模組的狀態資訊。 這會在 IoT 中樞 中建立或刪除對應的裝置/模組身分識別時隱含建立和刪除。
TwinProperties

對應項的所需和報告屬性。 物件的深度上限為 10。
X509Thumbprint

CloudToDeviceMethod

在裝置上執行直接方法的參數。

名稱 類型 Description
connectTimeoutInSeconds

integer

methodName

string

要執行的方法名稱。
payload

object

JSON 格式的直接方法承載，大小上限為 128 kb。
responseTimeoutInSeconds

integer

DeviceCapabilities

裝置上啟用的功能狀態。

名稱 類型 Description
iotEdge

boolean

屬性，判斷裝置是否為邊緣裝置。

DeviceJobStatistics

有關執行狀態的作業統計數據。

名稱 類型 Description
deviceCount

integer

作業的目標裝置數目。
failedCount

integer

失敗的作業數目。
pendingCount

integer

排程) 作業的擱置 (數目。
runningCount

integer

執行中作業的數目。
succeededCount

integer

成功的作業數目。

JobRequest

名稱 類型 Description
cloudToDeviceMethod

CloudToDeviceMethod

方法類型和參數。 如果作業類型為 cloudToDeviceMethod，則需要此專案。
jobId

string

作業的唯一識別碼。
maxExecutionTimeInSeconds

integer

秒的運行時間上限。
queryCondition

string

要執行作業的裝置條件。 如果作業類型為 updateTwin 或 cloudToDeviceMethod，則需要此專案。
startTime

string

ISO 8601 標準中作業的開始日期和時間。
type enum:
  • backup
  • export
  • factoryResetDevice
  • failoverDataCopy
  • firmwareUpdate
  • import
  • readDeviceProperties
  • rebootDevice
  • restoreFromBackup
  • scheduleDeviceMethod
  • scheduleUpdateTwin
  • unknown
  • updateDeviceConfiguration
  • writeDeviceProperties

作業類型。
updateTwin

Twin

裝置或模組的狀態資訊。 這會在 IoT 中樞 中建立或刪除對應的裝置/模組身分識別時隱含建立和刪除。

JobResponse

名稱 類型 Description
cloudToDeviceMethod

CloudToDeviceMethod

方法類型和參數。 如果作業類型為 cloudToDeviceMethod，則需要此專案。
createdTime

string

系統產生。 在建立時忽略。 作業的建立日期和時間。
deviceJobStatistics

DeviceJobStatistics

有關作業執行狀態的詳細數據。
endTime

string

系統產生。 在建立時忽略。 以UTC為單位之作業的結束日期和時間。
failureReason

string

如果發生失敗，則為失敗的原因。
jobId

string

系統產生。 在建立時忽略。 作業的唯一識別碼。
maxExecutionTimeInSeconds

integer

秒的運行時間上限。
queryCondition

string

裝置查詢條件。
startTime

string

UTC 中排程工作的開始日期和時間。
status enum:
  • cancelled
  • completed
  • enqueued
  • failed
  • queued
  • running
  • scheduled
  • unknown

系統產生。 在建立時忽略。 工作的狀態。
statusMessage

string

作業的狀態消息。
type enum:
  • backup
  • export
  • factoryResetDevice
  • failoverDataCopy
  • firmwareUpdate
  • import
  • readDeviceProperties
  • rebootDevice
  • restoreFromBackup
  • scheduleDeviceMethod
  • scheduleUpdateTwin
  • unknown
  • updateDeviceConfiguration
  • writeDeviceProperties

作業類型。
updateTwin

Twin

裝置或模組的狀態資訊。 這會在 IoT 中樞 中建立或刪除對應的裝置/模組身分識別時隱含建立和刪除。

Twin

裝置或模組的狀態資訊。 這會在 IoT 中樞 中建立或刪除對應的裝置/模組身分識別時隱含建立和刪除。

名稱 類型 Description
authenticationType enum:
  • certificateAuthority
  • none
  • sas
  • selfSigned

裝置所使用的驗證類型。
capabilities

DeviceCapabilities

裝置上啟用的功能狀態。
cloudToDeviceMessageCount

integer

傳送的雲端到裝置訊息數目。
connectionState enum:
  • Connected
  • Disconnected

裝置的連線狀態。
deviceEtag

string

根據RFC7232，代表裝置 ETag 的字串。
deviceId

string

IoT 中樞 身分識別登錄中裝置的唯一標識符。 這是區分大小寫的字串 (最多 128 個字元的 ASCII 7 位英數位元字元) ， 和下列特殊字元 {'-'、'：'、'.'、'+'、'%'、'_'、'#'、'*'、'？'、'！'、' ('、') '、'、'@'、'='、'@'、';'、'$'、'''}。
deviceScope

string

裝置的範圍。
etag

string

字串，表示裝置對應項的 ETag，根據RFC7232。
lastActivityTime

string

裝置上次連線或接收或傳送訊息的日期和時間。 日期和時間是以 UTC ISO8601日期時間格式來分隔，例如 2015-01-28T16：24：48.789Z。 如果裝置使用 HTTP/1 通訊協定來執行傳訊作業，則不會更新此值。
moduleId

string

IoT 中樞 身分識別登錄中模組的唯一標識符。 這是區分大小寫的字串 (最多 128 個字元的 ASCII 7 位英數位元字元) ， 和下列特殊字元 {'-'、'：'、'.'、'+'、'%'、'_'、'#'、'*'、'？'、'！'、' ('、') '、'、'@'、'='、'@'、';'、'$'、'''}。
parentScopes

string[]

如果適用，則為上層邊緣裝置的範圍。 僅適用於邊緣裝置。
properties

TwinProperties

對應項的所需和報告屬性。
status enum:
  • disabled
  • enabled

裝置的啟用狀態。 如果停用，裝置就無法連線到服務。
statusReason

string

裝置目前狀態的原因，如果有的話。
statusUpdateTime

string

上次更新裝置狀態的日期和時間。
tags

object

由解決方案後端讀取和寫入索引鍵/值組的集合。 裝置應用程式看不到它們。 這些金鑰的長度為 UTF-8 編碼、區分大小寫且長度上限為 1 KB。 允許的字元排除 UNICODE 控制字元 (區段 C0 和 C1) 、'.'、'$' 和空格。 這些值為 JSON 對象，長度上限為 4KB。
version

integer

裝置對應項的版本，包括標籤和所需屬性
x509Thumbprint

X509Thumbprint

裝置的 X509 指紋。

TwinProperties

對應項的所需和報告屬性。 物件的深度上限為 10。

名稱 類型 Description
desired

object

所需屬性索引鍵/值組的集合。 密鑰的長度為 UTF-8 編碼、區分大小寫和最多 1 KB。 允許的字元排除 UNICODE 控制字元 (區段 C0 和 C1) 、'.'、'$' 和空格。 所需的 porperty 值是 JSON 對象，長度上限為 4KB。
reported

object

報告屬性索引鍵/值組的集合。 密鑰的長度為 UTF-8 編碼、區分大小寫和最多 1 KB。 允許的字元排除 UNICODE 控制字元 (區段 C0 和 C1) 、'.'、'$' 和空格。 報告屬性值為 JSON 對象，長度上限為 4 KB。

X509Thumbprint

名稱 類型 Description
primaryThumbprint

string

X509 用戶端憑證主要指紋。
secondaryThumbprint

string

X509 用戶端憑證次要指紋。