すべてのプロダクト
Search
ドキュメントセンター

IoT Platform:CreateOTAStaticUpgradeJob

最終更新日:Apr 17, 2025

静的アップデートバッチを作成します。

使用上の注意

  • CreateOTAFirmware 操作の呼び出し時にアップデートパッケージの検証が不要であることを指定した場合、CreateOTAStaticUpgradeJob 操作を呼び出してアップデートバッチを作成する前に、アップデートパッケージが検証されていることを確認する必要があります。 アップデートパッケージを検証するタスクの作成方法の詳細については、「CreateOTAVerifyJob」をご参照ください。
  • 呼び出しごとに最大 200 台のデバイスのアップデートタスクを開始できます。 デバイスリストファイルを使用する場合は、最大 1,000,000 台のデバイスのアップデートタスクを開始できます。 ただし、GenerateDeviceNameListURL 操作を呼び出して、デバイスリストファイルの URL を生成する必要があります。 その後、指示に従ってデバイスリストファイルをアップロードできます。
  • 複数のデバイスのアップデートタスクを開始すると、すでに宛先ファームウェアバージョンがインストールされているデバイスはスキップされます。
  • 各デバイスは、1 つのアップデートタスクでのみ保留中またはアップデート中のステータスになることができます。 保留中またはアップデート中のステータスのデバイスに対して別のアップデートタスクを開始すると、アップデートタスクは失敗します。
  • 1 つのアップデートパッケージを使用して、複数の静的アップデートバッチを作成できます。
  • MQTT プロトコルを使用したアップデートパッケージのダウンロードは、中国 (上海) リージョンでのみサポートされています。

制限

Alibaba Cloud アカウントごとに、最大 20 クエリ/秒 (QPS) を実行できます。

説明 Alibaba Cloud アカウントの Resource Access Management (RAM) ユーザーは、アカウントのクォータを共有します。

デバッグ

OpenAPI Explorer は署名値を自動的に計算します。便宜上、OpenAPI Explorer でこの操作を呼び出すことをお勧めします。 OpenAPI Explorer は、さまざまな SDK 用の操作のサンプルコードを動的に生成します。

リクエストパラメーター

パラメーター タイプ 必須 説明
Action String Yes CreateOTAStaticUpgradeJob

実行する操作。 値を CreateOTAStaticUpgradeJob に設定します。

FirmwareId String Yes nx3xxVvFdwvn6dim50PY03****

アップデートパッケージの ID。

CreateOTAFirmware 操作を呼び出してアップデートパッケージを作成すると、アップデートパッケージ ID が返されます。

ListOTAFirmware 操作を呼び出して ID を取得することもできます。

ProductKey String Yes a1Le6d0****

アップデートパッケージが属するプロダクトの ProductKey

ProductKey は、IoT Platform におけるプロダクトの一意の識別子です。 IoT Platform コンソールで、または QueryProductList 操作を呼び出すことで、現在の Alibaba Cloud アカウント内のすべてのプロダクトに関する情報を表示できます。

Tag.N.Key String Yes key1

アップデートバッチタグのキー。 キーは 1 ~ 30 文字で、文字、数字、ピリオド (.) を使用できます。 アップデートバッチごとに最大 10 個のタグを追加できます。

アップデートバッチのタグは、IoT Platform がこれらのデバイスにアップデート通知をプッシュするときにデバイスに送信されます。

説明 アップデートバッチタグはオプションです。 タグを指定する場合は、Tag.N.Value パラメーターと Tag.N.Key パラメーターをペアで指定する必要があります。
Tag.N.Value String Yes value1

アップデートバッチタグの値。 値は 1 ~ 1,024 文字でなければなりません。 アップデートバッチごとに最大 10 個のタグを追加できます。 すべてのアップデートバッチのタグキーとタグ値の合計の長さは、4,096 文字を超えることはできません。

説明 アップデートバッチタグはオプションです。 タグを指定する場合は、Tag.N.Value パラメーターと Tag.N.Key パラメーターをペアで指定する必要があります。
TargetSelection String Yes ALL

アップデートバッチの範囲。 有効な値:

  • ALL: すべてのデバイスをアップデートします。
  • SPECIFIC: 指定されたデバイスをアップデートします。
  • GRAY: 段階的アップデートを実行します。
  • GROUP: 指定されたグループをアップデートします。
IotInstanceId String No iot-cn-0pp1n8t****

インスタンスの ID。 インスタンスの ID は、IoT Platform コンソールの 概要 ページで確認できます。

重要
  • インスタンスに ID がある場合は、このパラメーターに ID を指定する必要があります。 インスタンス ID を指定しないと、呼び出しは失敗します。
  • インスタンスに 概要 ページまたは ID が生成されていない場合は、このパラメーターを設定する必要はありません。

詳細については、「概要」をご参照ください。

SrcVersion.N RepeatList No V1.0.1

アップデート対象のファームウェアバージョンのリスト。

説明
  • このパラメーターは、TargetSelection パラメーターを ALL または GRAY に設定した場合に利用できます。
  • 差分アップデートパッケージを使用して完全アップデートまたは段階的アップデートを実行する場合、このパラメーターの値は SrcVersion パラメーターの値と同じである必要があります。
  • このパラメーターは、TargetSelection パラメーターを SPECIFIC または GROUP に設定した場合には利用できません。
  • QueryDeviceDetail 操作を呼び出して、レスポンスの FirmwareVersion パラメーターを表示できます。
  • バージョン番号はリスト内で一意である必要があります。
  • 最大 10 個のバージョン番号を指定できます。
ScheduleTime Long No 1577808000000

ファームウェアアップデート (OTA) を開始する時刻。

スケジュールされた時刻は、現在の時刻から 5 分後から 7 日後までです。 値は 13 桁のタイムスタンプである必要があります。

このパラメーターを指定しないと、アップデートはすぐに開始されます。

RetryInterval Integer No 60

デバイスのアップデートに失敗した場合の自動再試行間隔。 単位:分。 有効な値:

  • 0: 自動再試行がすぐに実行されます。
  • 10: 10 分後に自動再試行が実行されます。
  • 30: 30 分後に自動再試行が実行されます。
  • 60: 60 分 (1 時間) 後に自動再試行が実行されます。
  • 1440: 1,440 分 (24 時間) 後に自動再試行が実行されます。
重要 RetryInterval パラメーターの値は、TimeoutInMinutes パラメーターの値よりも小さい必要があります。 例:
  • TimeoutInMinutes パラメーターの値が 60 に設定されている場合、RetryInterval パラメーターの最大値は 30 です。
  • TimeoutInMinutes パラメーターの値が 1440 に設定されている場合、RetryInterval パラメーターの最大値は 60 です。

RetryInterval パラメーターの値が 1440 に設定されている場合は、TimeoutInMinutes パラメーターを指定しないことをお勧めします。 アップデートがタイムアウトした場合、再試行は実行されません。

このパラメーターを指定しないと、再試行は実行されません。

RetryCount Integer No 1

自動再試行の回数。

RetryInterval パラメーターを指定する場合は、このパラメーターを指定する必要があります。

有効な値:

  • 1: 1 回再試行します。
  • 2: 2 回再試行します。
  • 5: 5 回再試行します。
TimeoutInMinutes Integer No 1440

アップデートのタイムアウト期間。 指定された期間内にデバイスがアップデートされない場合、タイムアウトエラーが発生します。 単位:分。 有効な値:1 ~ 1440。

説明
  • タイムアウト期間は、指定されたデバイスが初めてアップデートの進捗状況を送信した時刻から開始されます。 アップデート中、デバイスがオンラインとオフラインを複数回繰り返すため、アップデートパッケージが指定されたデバイスに繰り返しプッシュされる場合があります。 アップデート期間の開始時刻は変更されません。
  • タイムアウトが原因でアップデートに失敗した場合、再試行はトリガーされません。

このパラメーターを指定しないと、タイムアウトエラーは発生しません。

MaximumPerMinute Integer No 1000

アップデートパッケージのダウンロード URL が 1 分あたりにプッシュされるデバイスの最大数。 有効な値:10 ~ 10000。

デフォルト値:10000。

GrayPercent String No 33.33

段階的アップデートの比率。 値は文字列形式のパーセンテージです。 最大 3 桁の少数まで使用できます。 計算されたデバイスの数は、最も近い整数に切り捨てられます。 段階的アップデートでは、少なくとも 1 つのデバイスを指定する必要があります。

たとえば、100 台のデバイスに対して段階的アップデートの比率を 33.33 に設定した場合、アップデートされるデバイスの数は 33 になります。

TargetSelection パラメーターを GRAY に設定する場合は、このパラメーターを指定する必要があります。

TargetDeviceName.N RepeatList No deviceName1

デバイス名のリスト。

説明
  • TargetSelection パラメーターを SPECIFIC に設定する場合は、このパラメーターまたは DnListFileUrl パラメーターを指定する必要があります。 2 つのパラメーターを同時に指定することはできません。
  • 差分アップデートパッケージを使用して特定のアップデートを実行する場合、アップデート対象のデバイスの OTA モジュールバージョンは、SrcVersion パラメーターの値と同じである必要があります。
  • QueryDeviceDetail 操作を呼び出して、レスポンスの FirmwareVersion パラメーターを表示できます。
  • リスト内のデバイスは、アップデートパッケージと同じプロダクトに属している必要があります。
  • デバイス名はリスト内で一意である必要があります。
  • リストには最大 200 個のデバイス名を含めることができます。
ScheduleFinishTime Long No 1577909000000

アップデートを終了する時刻。

終了時刻は、ScheduleTime パラメーターで指定された開始時刻の 1 時間後から 30 日後までである必要があります。 値は 13 桁のタイムスタンプである必要があります。

このパラメーターを指定しないと、アップデートは強制終了されません。

OverwriteMode Integer No 1

以前のアップデートタスクを上書きするかどうかを指定します。 デフォルト値:1。 有効な値:

  • 1: 以前のアップデートタスクは上書きされません。 デバイスにすでにアップデートタスクがある場合、以前のアップデートタスクが実装されます。
  • 2: 以前のアップデートタスクは上書きされます。 現在のアップデートタスクのみが実装されます。 この場合、MultiModuleModetrue に設定することはできません。
説明 進行中のアップデートタスクは上書きされません。
DnListFileUrl String No https://iotx-ota.oss-cn-shanghai.aliyuncs.com/ota/65dfcda0473be29836dfde585472****/ck2nfzljo00023g7kysg0****.bin

特定のアップデートを実行するために使用されるデバイスリストファイルの URL。

説明
  • TargetSelection パラメーターを SPECIFIC に設定する場合は、このパラメーターまたは TargetDeviceName.N パラメーターを指定する必要があります。 2 つのパラメーターを同時に指定することはできません。
  • GenerateDeviceNameListURL 操作を呼び出してファイル URL を生成できます。 その後、指示に従ってデバイスリストファイルをアップロードできます。
  • 完全アップデート中は、すでにアップデートされているデバイスはスキップされます。
  • 差分アップデート中は、すでにアップデートされているデバイスと、初期バージョン番号がアップデートパッケージと異なるデバイスはスキップされます。
NeedPush Boolean No true

IoT Platform からデバイスにアップデートタスクを自動的にプッシュするかどうかを指定します。 デフォルト値:true。 有効な値:

  • true: アップデートバッチが作成されると、IoT Platform は指定されたオンラインデバイスにアップデートタスクを自動的にプッシュします。

    この場合でも、デバイスは IoT Platform からファームウェアアップデート (OTA) タスクに関する情報を取得するリクエストを開始できます。

  • false: デバイスは、IoT Platform から OTA アップデートタスクに関する情報を取得するリクエストを開始する必要があります。
NeedConfirm Boolean No false

モバイルアプリを使用してアップデートを制御するかどうかを指定します。 必要に応じてモバイルアプリを開発する必要があります。 デフォルト false: true。 有効な値:

  • false: デバイスは、NeedPush パラメーターに基づいて OTA アップデートタスクに関する情報を取得します。
  • true: デバイスで OTA アップデートを実行するには、モバイルアプリを使用してアップデートを確認する必要があります。 その後、デバイスは NeedPush パラメーターに基づいて OTA アップデートタスクに関する情報を取得できます。
GroupId String No CtjzCkNuOx***

グループの ID。

TargetSelection パラメーターを GROUP に設定する場合は、このパラメーターと GroupType パラメーターを指定する必要があります。

QueryDeviceGroupList 操作を呼び出して、GroupId パラメーターをクエリできます。

GroupType String No LINK_PLATFORM

グループのタイプ。 有効な値:LINK_PLATFORM

TargetSelection パラメーターを GROUP に設定する場合は、このパラメーターと GroupId パラメーターを指定する必要があります。

DownloadProtocol String No HTTPS

アップデートパッケージのダウンロードプロトコル。 有効な値:HTTPS および MQTT。 デフォルト値:HTTPS。 デバイスは、IoT Platform によってプッシュされたアップデートパッケージ情報を受信した後、このプロトコルを使用してアップデートパッケージをダウンロードします。

重要 MQTT 経由でアップデートパッケージをダウンロードする必要がある場合は、次の点に注意してください。
  • サービスは、中国 (上海)、中国 (北京)、または中国 (深圳) リージョンにデプロイする必要があります。
  • OTA アップデートパッケージには 1 つのファイルのみを含めることができ、ファイルサイズは 16 MB を超えることはできません。
  • C 用の Link SDK の最新バージョンを使用してデバイス機能を開発し、OTA アップデートを実行して MQTT 経由でファイルをダウンロードする必要があります。 詳細については、「サンプルコード」をご参照ください。
MultiModuleMode Boolean No false

デバイスが複数モジュールの同時アップデートをサポートするかどうかを指定します。 デフォルト値:false。 有効な値:

  • false
  • true: この場合、OverwriteMode2 に設定しないでください。

    同じモジュールのアップデートタスクは上書きされます。 進行中のアップデートタスクは上書きされません。 モジュールのアップデートタスクは互いに影響しません。

重要
  • Enterprise Edition インスタンスと新しいパブリックインスタンスのみがサポートされています。
  • C 4.x 用の Link SDK を使用してデバイスを開発する必要があります。

詳細については、「概要」をご参照ください。

上記の操作固有のリクエストパラメーターに加えて、この操作を呼び出す際には共通リクエストパラメーターを指定する必要があります。 詳細については、「共通パラメーター」をご参照ください。

レスポンスパラメーター

パラメーター タイプ 説明
Code String MissingFirmwareId

呼び出しに失敗した場合に返されるエラーコード。 詳細については、「エラーコード」をご参照ください。

Data Struct

呼び出しが成功した場合に返されるアップデートバッチ情報。 詳細については、Data を参照してください。

JobId String wahVIzGkCMuAUE2gDERM02****

アップデートバッチの一意の識別子。

UtcCreate String 2019-11-04T06:22:19.566Z

アップデートバッチが作成された時刻。 時刻は UTC で表示されます。

ErrorMessage String FirmwareId is mandatory for this action.

呼び出しに失敗した場合に返されるエラーメッセージ。

RequestId String 29EC7245-0FA4-4BB6-B4F5-5F04818FDFB1

リクエストの ID。

Success Boolean true

呼び出しが成功したかどうかを示します。 有効な値:

  • true: リクエストは成功しました。
  • false: リクエストは失敗しました。

リクエストの例

http(s)://iot.cn-shanghai.aliyuncs.com/?Action=CreateOTAStaticUpgradeJob
&FirmwareId=nx3xxVvFdwvn6dim50PY03****
&ProductKey=a1Le6d0****
&Tag.1.Key=key1
&Tag.1.Value=value1
&TargetSelection=ALL
&MaximumPerMinute=1000
&RetryCount=1
&RetryInterval=60
&TimeoutInMinutes=1440
&SrcVersion.1=V1.0.1
&<共通リクエストパラメーター>

成功レスポンスの例

XML 形式

<CreateOTAStaticUpgradeJobResponse>
   <Data>
       <JobId>wahVIzGkCMuAUE2gDERM02****</JobId>
       <UtcCreate>2019-11-04T06:22:19.566Z</UtcCreate>
   </Data>
   <RequestId>29EC7245-0FA4-4BB6-B4F5-5F04818FDFB1</RequestId>
   <Success>true</Success>
</CreateOTAStaticUpgradeJobResponse>

JSON 形式

{
  "Data": {
    "JobId": "wahVIzGkCMuAUE2gDERM02****",
    "UtcCreate": "2019-11-04T06:22:19.566Z"
  },
  "RequestId": "29EC7245-0FA4-4BB6-B4F5-5F04818FDFB1",
  "Success": true
}

エラーコード

エラーコードのリストについては、「IoT Platform エラーコード」をご参照ください。