This topic describes how to integrate the upload SDK for JavaScript and use the SDK to upload local or online files from clients to ApsaraVideo VOD.
Prerequisites
ApsaraVideo VOD is activated. For more information, see Activate ApsaraVideo VOD.
- The system settings required for the upload, including the storage path in the specified region and the callback settings, are configured. For more information, see Manage VOD storage and Configure callbacks.
- A RAM user is created and used to access ApsaraVideo VOD. To prevent security risks caused by the leakage of the AccessKey pair of your Alibaba Cloud account, we recommend that you create a RAM user and grant the RAM user the permissions required to access ApsaraVideo VOD. Then, you can use the AccessKey pair of the RAM user to access ApsaraVideo VOD. For more information, see Create and grant permissions to a RAM user.
- Optional. A role is created for the RAM user and the role is granted the permissions required to access ApsaraVideo VOD if you want to access ApsaraVideo VOD by using Security Token Service (STS). For more information, see Create a RAM role and grant temporary access permissions to the role by using STS. Note For more information about the scenarios in which STS can be used, see Comparison between credentials and STS.
- The file to be uploaded is selected by using the standard input method. The size of the file to be uploaded cannot exceed 10 GB. If the file size exceeds 10 GB, resumable upload is used. For more information, see Advanced feature.
- The upload SDK for JavaScript can be used in the following browsers:
- Internet Explorer 10 and later
- Edge
- Major versions of Google Chrome, Firefox, or Safari
- Major versions of the default browsers provided by Android, iOS, or Windows Phone
Upload a file
Perform the steps described in this section to upload a file by using the upload SDK for JavaScript.
- If the upload on the web client is interrupted, a 404 error may occur when you try to upload the file again. You can update the upload SDK to V1.5.3 or later and upload the file again. If you use the upload SDK for JavaScript that is earlier than V1.5.3, rename the file before you upload the file again to prevent errors.
- If you want to upload multiple files at the same time, you can create multiple upload instances. Each upload instance represents an upload task for a single file. You cannot use an upload instance to upload multiple files at the same time.
- Integrate the upload SDK for JavaScript. Download the upload SDK for JavaScript. For more information, see SDK download. The upload SDK provides only partial support for external modules. If you call the
import
orrequire
method to reference files, theReferenceError: OSS is not defined
error message is returned. You can use one of the following methods to reference files based on your business requirements:- (Recommended) Reference by using scripts in HTML
<!-- The es6-promise file is required for Internet Explorer. Internet Explorer 10 and later versions are supported. --> <script src="../lib/es6-promise.min.js"></script> <script src="../lib/aliyun-oss-sdk-6.17.1.min.js"></script> <script src="../aliyun-vod-upload-sdk-1.5.5.min.js"></script>
- Reference by using a moduleYou can manually add an Object Storage Service (OSS) module to the window. The following sample code provides an example:Note If you have already referenced files in the HTML page by using scripts, you do not need to add the module.
import OSS from '../lib/aliyun-upload-sdk/lib/aliyun-oss-sdk-6.17.1.min' window.OSS = OSS; import '../lib/aliyun-upload-sdk/aliyun-upload-sdk-1.5.5.min'
- (Recommended) Reference by using scripts in HTML
- Obtain an upload URL and an upload credential or an STS token for upload authorization.
If you use the upload SDK for JavaScript to upload a file, you must obtain an upload credential from AppServer and upload the file to the OSS server on Alibaba Cloud. After you obtain the upload credential from AppServer, specify the credential in the configurations of the SDK. You can use one of the following methods to obtain an upload credential:
- For more information about how to obtain the upload URL and credential, see Obtain upload URLs and credentials.
- For more information about how to obtain an STS token, see Obtain an STS token.
Use the obtained upload URL and credential or the obtained STS token to initialize the upload instance.
- Initialize the upload instance by using an upload credential or an STS token. We recommend that you use an upload credential to initialize the upload instance.
You need to configure the initialization callback before you initialize the upload instance.
- Specify the parameters for the upload based on the type of the file that you want to upload.
- Start the upload. Note You can upload only a video or audio file from a client.
- After a video or audio file is uploaded, videoId is returned. Then, you need to obtain a playback URL to play the file. For more information, see Use playback credentials to play videos.
- imageUrl is not automatically returned after an image is uploaded. To obtain the image URL, configure a callback for the ImageUploadComplete event before you upload images. You can obtain FileURL in the ImageUploadComplete callback. For more information, see Configure callbacks. If you have enabled URL signing, the URL expires after the validity period elapses. For more information, see Configure URL authentication .
Manage the upload list
- listFiles
The returned data contains information about the files that are uploaded by calling addFile. The file property in the returned data indicates the file type. You can traverse the list to obtain the indexes of the files that you want to manage.
var list = uploader.listFiles(); for (var i=0; i<list.length; i++) { log("file:" + list[i].file.name); }
- deleteFile
uploader.deleteFile(index);// The index of the file to be deleted. The index is returned by the listFiles operation.
- cancelFileNote
- After
cancelFile
is called, theoss is cancel as error
message is displayed in the console. This prevents the uploaded parts from occupying the storage space and reduces storage costs. - If you want to re-upload the file after you cancel the upload, you must use
uploader.resumeFile(index);
to restore the file before you re-upload the file.
uploader.cancelFile(index);
- After
- resumeFile
uploader.resumeFile(index);
- cleanList
uploader.cleanList();
Set the upload credential or STS token
- Set the upload URL and credential
Set the upload URL and credential in the
onUploadstarted
callback.uploadInfo
is included in the callback.const {VideoId,UploadAuth,UploadAddress} = data; uploader.setUploadAuthAndAddress(uploadInfo,UploadAuth,UploadAddress,VideoId);
Parameter Description uploadInfo The value can be obtained from the first parameter in the onUploadstarted callback. uploadAuth The value can be obtained from the response to the CreateUploadVideo operation. uploadAddress The value can be obtained from the response to the CreateUploadVideo operation. videoId The value can be obtained from the response to the CreateUploadVideo operation. - Resume the upload after the upload credential expires
Call the resumeUploadWithAuth operation in the onUploadTokenExpired callback to resume the upload after the upload credential expires. Set uploadAuth to the new upload credential returned in the response to the RefreshUploadVideo operation.
const {VideoId,UploadAuth,UploadAddress} = data; uploader.resumeUploadWithAuth(UploadAuth);
- Set the STS token
Call setSTSToken to set the STS token for file upload. Call setSTSToken in the
onUploadstarted
callback.uploadInfo
is included in the callback.var info = data.SecurityTokenInfo uploader.setSTSToken(uploadInfo,info.AccessKeyId,info.AccessKeySecret,info.SecretToken);
Parameter Description uploadInfo The value can be obtained from the first parameter in the onUploadstarted callback. accessKeyId The value can be obtained from the response to the CreateSecurityToken operation. accessKeySecret The value can be obtained from the response to the CreateSecurityToken operation. secretToken The value can be obtained from the response to the CreateSecurityToken operation. - Resume the upload after the STS token expires
Call resumeUploadWithSTSToken in the onUploadTokenExpired callback to update the upload credential after it expires.
var info = data.SecurityTokenInfo uploader.resumeUploadWithSTSToken(info.AccessKeyId, info.AccessKeySecret, info.SecretToken);
Upload management
Stop the upload
stopUpload
only when a file is being uploaded. Otherwise, the API operation does not work. uploader.stopUpload();
Advanced feature
Resumable uploadIf errors such as forceful page shutdown and browser breakdown occur during file upload and you try to upload the file again, the upload SDK for JavaScript resumes the upload from the breakpoint and obtains the upload credential from the onUploadstarted
callback. If you use the upload URL and credential to upload the file, call API operations in ApsaraVideo VOD to obtain breakpoint information based on the value of videoId. Sample code:
onUploadstarted: function (uploadInfo) {
if (Upload method 1) {
if(!uploadInfo.videoId)// No error occurred during file upload.
{
// Call the CreateUploadVideo operation in your environment.
uploader.setUploadAuthAndAddress(uploadInfo, uploadAuth, uploadAddress,videoId);
}
else// If the videoId parameter is not empty, update the upload credential based on the value of videoId.
{
// Call the RefreshUploadVideo operation in your environment to update the upload credential.
uploader.setUploadAuthAndAddress(uploadInfo, uploadAuth, uploadAddress);
}
}
else(Upload method 2)
{
// Call the setSTSToken operation to obtain the STS token in your environment.
uploader.setSTSToken(uploadInfo, accessKeyId, accessKeySecret,secretToken);
}
}
You can call the following method to obtain the breakpoint information:
uploader.getCheckpoint(file);