Generates the URL and other information that are required to upload an update package file to Object Storage Service (OSS).

Usage notes

This operation can be used together with other operations to create an update package. Procedure:

1. Call this API operation to generate the details of an update package file that you want to upload to OSS.

The following section describes the response parameters of this API operation:

  • The following request parameters of the OSS PostObject operation that is used to upload the update package file: Key, OSSAccessKeyId, Signature, and Policy.
  • The following request parameter of the CreateOTAFirmware operation that is used to create the update package: FirmwareUrl.

2. Use an OSS SDK to call the PostObject operation to upload the update package file. For more information about sample code, see the "Usage of response parameters" section.

Important The parameter information that is returned by this operation is valid for 1 minute. You must upload the update package file within 1 minute. The maximum size of the uploaded update package file is 1,000 MB.

3. After the update package file is uploaded, call the CreateOTAFirmware operation to create an update package within 60 minutes.

If update package files are uploaded but you do not call the CreateOTAFirmware operation to create update packages for the files, the uploaded files are automatically deleted by the system on a regular basis.

QPS limits

Each Alibaba Cloud account can run up to 10 queries per second (QPS).

Note The RAM users of an Alibaba Cloud account share the quota of the Alibaba Cloud account.

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer. OpenAPI Explorer dynamically generates the sample code of the operation for different SDKs.

Request parameters

Parameter Type Required Example Description
Action String Yes GenerateOTAUploadURL

The operation that you want to perform. Set the value to GenerateOTAUploadURL.

IotInstanceId String No iot-cn-0pp1n8t****

The ID of the instance. You can view the ID of the instance on the Overview page in the IoT Platform console.

Important
  • If your instance has an ID, you must specify the ID for this parameter. Otherwise, the call fails.
  • If no Overview page or ID is generated for your instance, you do not need to configure this parameter.

For more information, see Overview.

FileSuffix String No apk

The file name extension of the update package file. Valid values: bin, dav, apk, tar, gz, tar.gz, zip, and gzip.

Default value: bin.

In addition to the preceding operation-specific request parameters, you must specify common request parameters when you call this operation. For more information, see Common request parameters.

Response parameters

Parameter Type Example Description
Code String iot.system.SystemException

The error code returned if the call fails. For more information, see Error codes.

Data Struct

The information returned if the call is successful. For more information, see the following parameters.

FirmwareUrl String https://iotx-ota.oss-cn-shanghai.aliyuncs.com/ota/65dfcda0473be29836dfde585472****/ck2nfzljo00023g7kysg0****.bin

The URL of the update package file that is stored in OSS.

After the update package file is uploaded, this parameter is used to call the CreateOTAFirmware operation to create an update package.

Host String https://iotx-ota.oss-cn-shanghai.aliyuncs.com

The endpoint of OSS.

Key String ota/65dfcda0473be29836dfde585472****/ck2nfzljo00023g7kysg0****.bin

The full path of the file in OSS. The file is uploaded by calling the OSS PostObject operation.

OSSAccessKeyId String cS8uRRy54Rsz****

The AccessKey ID of the bucket owner.

This OSS bucket stores the update package file.

ObjectStorage String OSS

The type of object storage. Default value: OSS.

Policy String eyJleHBpcmF****

The parameter that is used by OSS to verify form fields for the request.

Signature String v6lViO4FBvfquajQjg20K5hK****

The signature that is calculated based on AccessKeySecret and Policy. When you call an OSS operation, OSS uses the signature information to verify the POST request.

UtcCreate String 2019-11-04T06:21:54.607Z

The time when the URL of the uploaded update package file was generated. The time is displayed in UTC.

ErrorMessage String A system exception occurred.

The error message returned if the call fails.

RequestId String 74C2BB8D-1D6F-41F5-AE68-6B2310883F63

The ID of the request.

Success Boolean true

Indicates whether the call was successful. Valid values:

  • true: The call was successful.
  • false: The call failed.

Purposes of response parameters

When you call the OSS PostObject operation to upload the update package file to OSS, specify the request parameters by using the values that are returned by the GenerateOTAUploadURL operation.

The following sample code that is written in Java shows how to upload the update package file to OSS. For more information about the sample code, see Upload forms.

  • Add the following dependencies to the pom.xml file:
    
    <dependency>
      <groupId>org.apache.httpcomponents</groupId>
      <artifactId>httpclient</artifactId>
      <version>4.5.3</version>
    </dependency>
    
    <dependency>
      <groupId>org.apache.httpcomponents</groupId>
      <artifactId>httpmime</artifactId>
      <version>4.5.10</version>
    </dependency>
                        
  • Sample code:
    
    public static boolean postObject(String key,
                                      String host,
                                      String policy,
                                      String ossAccessKeyId,
                                      String signature,
                                      String data) throws IOException {
      CloseableHttpClient httpClient = HttpClients.createDefault();
      HttpPost uploadFile = new HttpPost(host);
    
      MultipartEntityBuilder builder = MultipartEntityBuilder.create();
      builder.addTextBody("key", key, ContentType.TEXT_PLAIN);
      builder.addTextBody("policy", policy, ContentType.TEXT_PLAIN);
      builder.addTextBody("OSSAccessKeyId", ossAccessKeyId, ContentType.TEXT_PLAIN);
      builder.addTextBody("signature", signature, ContentType.TEXT_PLAIN);
      builder.addTextBody("success_action_status", "200", ContentType.TEXT_PLAIN);
      builder.addBinaryBody("file", data.getBytes());
    
      HttpEntity multipart = builder.build();
      uploadFile.setEntity(multipart);
      CloseableHttpResponse response = httpClient.execute(uploadFile);
    
      if (response.getStatusLine().getStatusCode() == 200) {
        return true;
      }
    
      return false;
    }
                        

Examples

Sample requests

https://iot.cn-shanghai.aliyuncs.com/?Action=GenerateOTAUploadURL
&<Common request parameters>

Sample success responses

XML format

<GenerateOTAUploadURLResponse>
    <Data>
        <Key>ota/65dfcda0473be29836dfde585472****/ck2nfzljo00023g7kysg0****.bin</Key>
        <Host>https://iotx-ota.oss-cn-shanghai.aliyuncs.com</Host>
        <Policy>eyJleHBpcmF****</Policy>
        <OSSAccessKeyId>cS8uRRy54Rsz****</OSSAccessKeyId>
        <ObjectStorage>OSS</ObjectStorage>
        <UtcCreate>2019-11-04T06:21:54.607Z</UtcCreate>
        <Signature>PKmRTy40QxqIUUWy325SCT/****</Signature>
        <FirmwareUrl>https://iotx-ota.oss-cn-shanghai.aliyuncs.com/ota/65dfcda0473be29836dfde585472****/ck2nfzljo00023g7kysg0****.bin</FirmwareUrl>
    </Data>
    <RequestId>B6E77674-09C4-4647-BF85-59CB72A72E4B</RequestId>
    <Success>true</Success>
</GenerateOTAUploadURLResponse>

JSON format

{
    "Data": {
        "Key": "ota/65dfcda0473be29836dfde585472****/ck2nfzljo00023g7kysg0****.bin",
        "Host": "https://iotx-ota.oss-cn-shanghai.aliyuncs.com",
        "Policy": "eyJleHBpcmF****",
        "OSSAccessKeyId": "cS8uRRy54Rsz****",
        "ObjectStorage": "OSS",
        "UtcCreate": "2019-11-04T06:21:54.607Z",
        "Signature": "PKmRTy40QxqIUUWy325SCT/****",
        "FirmwareUrl": "https://iotx-ota.oss-cn-shanghai.aliyuncs.com/ota/65dfcda0473be29836dfde585472****/ck2nfzljo00023g7kysg0****.bin"
    },
    "RequestId": "B6E77674-09C4-4647-BF85-59CB72A72E4B",
    "Success": true
}

Error codes

For a list of error codes, visit the API Error Center.