ApsaraVideo VOD:Migrate resources to ApsaraVideo VOD

Migration scenarios and methods

ApsaraVideo VOD supports multiple migration methods. You can migrate resources that are stored on personal websites and in third-party cloud services to ApsaraVideo VOD, migrate resources stored in Object Storage Service (OSS) to ApsaraVideo VOD within an Alibaba Cloud account or across different Alibaba Cloud accounts, and migrate resources in ApsaraVideo VOD across different Alibaba Cloud accounts.

After you migrate a video to ApsaraVideo VOD, video information such as the video ID, playback URL, and thumbnail URL is generated in ApsaraVideo VOD. You need to associate the video information before the migration with that after the migration.

Before you begin

• An Alibaba Cloud account is created and real-name verification is complete. To create an Alibaba Cloud account, visit the Alibaba Cloud official website. For more information about how to create an Alibaba Cloud account, see Create an Alibaba Cloud account.

• Obtain an AccessKey pair to complete identity verification so that you can call server API operations. For more information about how to obtain an AccessKey pair, see Obtain an AccessKey pair.

  Note

  To migrate resources as a RAM user, you must create a RAM user before you obtain the AccessKey pair. For more information, see Create and grant permissions to a RAM user.

(Recommended) Upload resources in batches based on URLs

Scenario

If you want to migrate resources that are not stored on on-premises servers or devices and these resources are publicly accessible, we recommend that you migrate the resources in batches based on URLs. This way, you can quickly upload a large number of files over an internal network and reduce traffic usage.

Limits

You can upload resources in batches based on URLs only in the China (Shanghai) and Singapore regions. You can use other methods to migrate resources in other regions.

Usage notes

• URL-based upload jobs are asynchronous. After you submit a URL-based upload job, it may take hours, even days to complete. If you require high timeliness, we recommend that you use the upload SDK.

• Every time you submit an upload job by using a URL, a new media ID is generated in ApsaraVideo VOD.

Migration process

Procedure

1. Integrate the ApsaraVideo VOD SDK.

   ApsaraVideo VOD SDK for Java is used in this example. For more information about how to use the ApsaraVideo VOD SDK in other programming languages, see Usage notes.

   For more information about how to download and install the SDK for Java, see SDK overview and download and Installation.

2. Prepare the resources that you want to migrate.

   Note

   • You must prepare the download URLs of all files that you want to migrate. If URL signing is enabled, make sure that the URLs are valid during the download.

   • The download URLs must include file names and file name extensions, such as https://****.mp4.

3. Call the UploadMediaByURL operation by using ApsaraVideo VOD SDK to upload resources in batches.

   ApsaraVideo VOD SDK for Java is used in the following example. For more information about how to call API operations by using ApsaraVideo VOD SDK in other programming languages, see Upload multiple media files at a time by using the URLs of source files.

   You can perform online debugging by using OpenAPI Explorer.

   Show sample code in Java

   import com.alibaba.fastjson.JSON;
   import com.alibaba.fastjson.JSONArray;
   import com.alibaba.fastjson.JSONObject;
   import com.aliyuncs.DefaultAcsClient;
   import com.aliyuncs.auth.AlibabaCloudCredentials;
   import com.aliyuncs.auth.EnvironmentVariableCredentialsProvider;
   import com.aliyuncs.exceptions.ClientException;
   import com.aliyuncs.profile.DefaultProfile;
   import com.aliyuncs.vod.model.v20170321.UploadMediaByURLRequest;
   import com.aliyuncs.vod.model.v20170321.UploadMediaByURLResponse;
   
   import java.net.URLEncoder;
   
   /**
    * Sample code of uploading media files at a time based on URLs
    *
    */
   public class AudioOrVideoUploadByUrl {
   
       /** 
        * Obtain the AccessKey information.
        */
       public static DefaultAcsClient initVodClient() throws ClientException {
       // The region in which ApsaraVideo VOD is activated.
       String regionId = "cn-shanghai"; 
       // The AccessKey pair of an Alibaba Cloud account has permissions on all API operations. We recommend that you use a RAM user to call API operations or perform routine O&M. 
       // We recommend that you not include your AccessKey pair (AccessKey ID and AccessKey secret) in your project code. Otherwise, the AccessKey pair may be leaked and the security of all resources within your account may be compromised. 
       // In this example, ApsaraVideo VOD reads the AccessKey pair from the environment variables to implement identity verification for API access. Before you run the sample code, configure the environment variables ALIBABA_CLOUD_ACCESS_KEY_ID and ALIBABA_CLOUD_ACCESS_KEY_SECRET. 
       DefaultProfile profile = DefaultProfile.getProfile(regionId, System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"), System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
       DefaultAcsClient client = new DefaultAcsClient(profile);
       return client;
       }
   
       /**
        * Upload media files at a time based on URLs.
        *
        * @param client The client that sends a request.
        * @return UploadMediaByURLResponse The fields contained in the response..
        * @throws Exception
        */
       public static UploadMediaByURLResponse uploadMediaByURL(DefaultAcsClient client) throws Exception {
           UploadMediaByURLRequest request = new UploadMediaByURLRequest();
           String url = "http://video_01.mp4";
           String encodeUrl = URLEncoder.encode(url, "UTF-8");
           // The URLs of source files.
           request.setUploadURLs(encodeUrl);
   
           // The metadata of the video that you want to upload.
           JSONObject uploadMetadata = new JSONObject();
           // The URLs of the source files that you want to upload. The URL must be included in the value of the UploadURLs parameter.
           uploadMetadata.put("SourceUrl", encodeUrl);
           // The video title.
           uploadMetadata.put("Title", "upload by url sample");
   
           JSONArray uploadMetadataList = new JSONArray();
           uploadMetadataList.add(uploadMetadata);
           request.setUploadMetadatas(uploadMetadataList.toJSONString());
   
           // Optional. The user data that consists of user-defined parameters. Configure the user data if you need a callback URL and transparent data transmission.
           JSONObject userData = new JSONObject();
   
           // The callback configurations in the user data.
           // The callback settings for event notifications. If you specify callback settings, the specified callback settings take effect. Otherwise, the global callback settings take effect.
           JSONObject messageCallback = new JSONObject();
           // The callback URL.
           messageCallback.put("CallbackURL", "http://192.168.0.0/16");
           // The callback type. Default value: http.
           messageCallback.put("CallbackType", "http");
           userData.put("MessageCallback", messageCallback.toJSONString());
   
           JSONObject extend = new JSONObject();
           extend.put("MyId", "user-defined-id");
           userData.put("Extend", extend.toJSONString());
   
           request.setUserData(userData.toJSONString());
   
           return client.getAcsResponse(request);
       }
   
       /** 
        * Request example
        */
       public static void main(String[] argv) {
   
           try {
               DefaultAcsClient client = initVodClient();
               UploadMediaByURLResponse response = uploadMediaByURL(client);
               System.out.print("UploadJobs = " + JSON.toJSONString(response.getUploadJobs()) + "\n");
               System.out.print("RequestId = " + response.getRequestId() + "\n");
           } catch (Exception e) {
               System.out.print("ErrorMessage = " + e.getLocalizedMessage());
           }
       }
   
   }

4. Use one of the following methods to obtain the upload result.

   Method 1: Use event notifications

   ApsaraVideo VOD supports HTTP callbacks and MNS callbacks. After you configure event notifications, ApsaraVideo VOD sends you a notification based on the callback method that you specified when media files are processed. For example, ApsaraVideo VOD notifies you when media files are uploaded or transcoded. For more information, see Overview.

   You can obtain information about URL-based batch upload jobs such as the job status from the UploadByURLComplete callback. For more information, see UploadByURLComplete (for video uploads).

   • Sample callback of a successful upload

     { 
       "Status": "success",
       "EventTime": "2017-03-20T07:49:17Z",
       "EventType": "UploadByURLComplete", 
       "VideoId": "43q9fjdun3f****", 
       "JobId": "4c815bjs83j1****", 
       "SourceURL ": "http://example-bucket-****.oss-cn-shanghai.aliyuncs.com/27ffc438-164d55217ef-0005-6884-51a-1****.mp4",
       "Size":"123456"
     }

   • Sample callback of a failed upload

     { 
       "Status": "fail",
       "EventTime": "2017-03-20T07:49:17Z",
       "EventType": "UploadByURLComplete", 
       "ErrorCode ": "URLInvalidError ", 
       "ErrorMessage ": "download video failed by the url, please check it", 
       "JobId": "4c815bjsued1****" ,
       "SourceURL ": "http://example-bucket-****.oss-cn-shanghai.aliyuncs.com/27ffc438-164d55217ef-0005-6884-51a-1****.mp4"
     }

   Method 2: Call API operations

   You can call the GetURLUploadInfos operation to query information about URL-based batch upload jobs such as the job status. For more information, see GetURLUploadInfos.

Upload resources by using a self-built upload service

If URL-based batch upload is not supported in your service region or you require high upload timeliness, download the resources to your local devices and use the upload SDKs to upload the resources to ApsaraVideo VOD. If you set up your upload service on an Elastic Compute Service (ECS) instance, you can upload resources over the internal network or over the Internet based on the region in which your ECS instance resides.

Add OSS buckets to ApsaraVideo VOD and register resources

Scenario

To migrate OSS resources to ApsaraVideo VOD within an Alibaba Cloud account, add the OSS buckets to ApsaraVideo VOD and register the resources. This way, you do not need to upload resources.

Limits

• You can add only OSS buckets whose storage class is Standard to ApsaraVideo VOD.

• You can add up to 10 OSS buckets to ApsaraVideo VOD in each region.

Procedure

1. Add the OSS bucket in which resources you want to migrate reside to ApsaraVideo VOD.

   For more information about the procedure and parameter description, see Manage VOD storage.

2. Call an operation to register the OSS resources with ApsaraVideo VOD.

   1. List the objects that are stored in the OSS bucket by using an OSS SDK or calling an API operation. For more information, see List objects.

   2. Call the RegisterMedia operation to register a media resource and generate the media ID. For more information, see RegisterMedia. Set FileURL in RegisterMetadatas to the full path of the object that you obtained by listing the OSS objects. You must add the OSS domain name to the file path. Sample URL:

      https://oss-cn-hangzhou.aliyuncs.com/video/example.mp4

Set up an upload service

If you want to migrate third-party resources or migrate resources across Alibaba Cloud accounts, you must download the original video resources, and then use the upload tool to upload the resources to ApsaraVideo VOD. ApsaraVideo VOD allows you to upload resources by using the upload SDK or ApsaraVideo VOD SDK. The upload service can be implemented by using the upload SDK or ApsaraVideo VOD API. We recommend that you set up an upload service by using the upload SDK. This way, the resources are uploaded in a synchronous and efficient manner. The process of setting up an upload service by using ApsaraVideo VOD API is complex.

Procedure

1. Integrate the upload SDK or ApsaraVideo VOD SDK.

   You can integrate the upload SDK or ApsaraVideo VOD SDK based on the programming language that you use. For more information about how to integrate the upload SDK, see Overview. For more information about how to integrate ApsaraVideo VOD SDK, see Usage notes.

2. Write the code of the upload service. The following sample code provides an example on how to write the code:

(Recommended) Set up an upload service by using the upload SDK

The following code in Java is used as an example. For more information about the upload SDK in other programming languages, see Overview.

import com.aliyun.vod.upload.impl.UploadVideoImpl;
import com.aliyun.vod.upload.req.UploadStreamRequest;
import com.aliyun.vod.upload.resp.UploadStreamResponse;
import java.io.*;
import java.net.URL;

/**
 * Use the upload SDK to upload video files.
 */
public class UploadStreamDemo {
    /**
     * The stream upload operation.
     *
     * @param accessKeyId
     * @param accessKeySecret
     * @param title
     * @param fileName
     * @param inputStream
     */
    private static void testUploadStream(String accessKeyId, String accessKeySecret, String title, String fileName, InputStream inputStream) {
        UploadStreamRequest request = new UploadStreamRequest(accessKeyId, accessKeySecret, title, fileName, inputStream);
        
        /* Specify custom callback settings for event notifications. For more information about the parameters, see Basic data types. */
        //request.setUserData(""{\"Extend\":{\"test\":\"www\",\"localId\":\"xxxx\"},\"MessageCallback\":{\"CallbackURL\":\"http://example.aliyundoc.com\"}}"");
        /* Optional. Specify the category ID of the video. */
        //request.setCateId(0);
        /* Optional. Specify the tags of the video. Separate multiple tags with commas (,). */
        //request.setTags("Tag 1,Tag 2");
        /* Optional. Specify the description of the video. */
        //request.setDescription("Video description");
        /* Optional. Specify the URL of the thumbnail. Example: http://****.example.com/image_01.jpg. */
        //request.setCoverURL("<Your CoverURL>");
        /* Optional. Specify the ID of the template group. */
        //request.setTemplateGroupId("8c4792cbc8694e****fd5330e56a33d");
        /* Optional. Specify the ID of the workflow. */
        //request.setWorkflowId("d4430d07361f****1339577859b0177b");
        /* Optional. Specify the storage region. */
        //request.setStorageLocation("outin-20170323****266-5sejdln9o.oss-cn-shanghai.aliyuncs.com");
        /* Specify the access region of ApsaraVideo VOD. */
        request.setApiRegionId("cn-shanghai");
        /* Specify the region in which the ECS instance is deployed. */
        // request.setEcsRegionId("cn-shanghai");
        UploadVideoImpl uploader = new UploadVideoImpl();
        UploadStreamResponse response = uploader.uploadStream(request);
        System.out.print("RequestId=" + response.getRequestId() + "\n"); // Specify the ID of the request that is sent to ApsaraVideo VOD.
        if (response.isSuccess()) {
            System.out.print("VideoId=" + response.getVideoId() + "\n");
        } else { // If the callback URL that you specify is invalid, the upload process is not affected. The video ID and an error code are returned. If the video ID is empty, the upload fails. Analyze the cause based on the returned error code.
            System.out.print("VideoId=" + response.getVideoId() + "\n");
            System.out.print("ErrorCode=" + response.getCode() + "\n");
            System.out.print("ErrorMessage=" + response.getMessage() + "\n");
        }
    }

    public static void main(String[] args) {
        /**
         * Specify the URL of the source video, pass the information about the video, and upload the video.
         */
        InputStream inputStream = null;
        // The URL of the video. Example: http://example.aliyundoc.com/video/****.mp4.
        String url = "<Your File URL>";
        try {
            inputStream = new URL(url).openStream();
        } catch (IOException e) {
            e.printStackTrace();
        }
        // The AccessKey pair of an Alibaba Cloud account has access permissions on all API operations. We recommend that you use the AccessKey pair of a RAM user to call API operations or perform routine O&M. 
        // We recommend that you not include your AccessKey pair (AccessKey ID and AccessKey secret) in your project code. Otherwise, the AccessKey pair may be leaked and the security of all resources within your account may be compromised. 
        // In this example, ApsaraVideo VOD reads the AccessKey pair from the environment variables to implement identity verification for API access. Before you run the sample code, configure the environment variables ALIBABA_CLOUD_ACCESS_KEY_ID and ALIBABA_CLOUD_ACCESS_KEY_SECRET. 
        String accessKeyId = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID");
        String accessKeySecret = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET");

        // In the following code, the AccessKey ID and the AccessKey Secret are the AccessKey pair that you obtained. <Your Video Title> is the title of the video. <Your Video with File Extension> is the name of a video file that includes a filename extension, such as video-1.mp4. 
        testUploadStream(accessKeyId, accessKeySecret, "<Your Video Title>", "<Your Video with File Extension>", inputStream);
    }
}

Set up an upload service by using ApsaraVideo VOD API

To set up an upload service by using ApsaraVideo VOD SDK to call API operations, you must implement the logic for the entire upload process. You need to obtain upload URLs and credentials from ApsaraVideo VOD, decode the Base64-encoded upload URLs and credentials, and then use OSS SDKs to upload media files. In this case, the operations are complex and prone to errors. We recommend that you use the upload SDK to set up an upload service. For more information about the complete upload logic, see Upload media files by calling the ApsaraVideo VOD API.