ApsaraVideo VOD:Video-on-Demand Resource Migration

Migration scenarios and methods

ApsaraVideo VOD supports multiple migration methods. You can migrate resources from personal websites or third-party cloud services, OSS resources within or between Alibaba Cloud accounts, and ApsaraVideo VOD resources between Alibaba Cloud accounts.

After a successful migration, ApsaraVideo VOD generates new video information, such as the video ID, playback URL, and thumbnail URL. You must manually associate the video information from before and after the migration.

Before you begin

• An Alibaba Cloud account is created and identity verification is complete. To create an Alibaba Cloud account, visit the Alibaba Cloud official website. For more information, see Create an Alibaba Cloud account.

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

  Note

  If you use a RAM user to perform the migration, you must create the RAM user before you obtain the AccessKey pair. For more information, see Access ApsaraVideo VOD as a RAM user.

(Recommended) Upload resources in batches based on URLs

Scenarios

If the files that you want to migrate are not stored on local servers or devices but are publicly accessible over the Internet, you can use URL-based batch upload. This method lets you quickly upload many files over an internal network and reduces traffic usage.

Limits

URL-based batch upload is supported only in the China (Shanghai), China (Beijing), China (Shenzhen), Singapore, and US (Silicon Valley) regions. You must use other migration methods in other regions. For more information about endpoints, see ApsaraVideo VOD region IDs.

Usage notes

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

• Each time you submit a URL-based upload job, ApsaraVideo VOD creates a new media resource with a new media ID.

Migration process

Procedure

1. Integrate the ApsaraVideo VOD server-side SDK.

   This example uses the ApsaraVideo VOD SDK for Java. For more information about how to use the SDK in other programming languages, see Server-side SDK.

   To download the SDK for Java, see Server-side SDK. To install the SDK for Java, see Installation.

2. Prepare the resources to migrate.

   Note

   • Prepare the download URLs for all files to migrate. If the URLs require signing, you must ensure that they remain valid during the download period.

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

3. Call the UploadMediaByURL operation using the ApsaraVideo VOD server-side SDK to upload resources in batches.

   The following example shows how to call the operation in Java. For examples in other programming languages, see UploadMediaByURL.

   You can also perform online debugging 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 for the batch upload by URL feature
    *
    */
   public class AudioOrVideoUploadByUrl {
   
       /** 
        * Read the AccessKey information
        */
       public static DefaultAcsClient initVodClient() throws ClientException {
       // The region where ApsaraVideo VOD is activated.
       String regionId = "cn-shanghai"; 
       // An 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 strongly recommend that you do not hard-code the AccessKey ID and AccessKey secret in your project code. Otherwise, the AccessKey pair may be leaked, which threatens the security of all your resources.
       // This example shows how to read the AccessKey pair from environment variables to authenticate API access. Before you run the sample code, configure the ALIBABA_CLOUD_ACCESS_KEY_ID and ALIBABA_CLOUD_ACCESS_KEY_SECRET environment variables.
       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;
       }
   
       /**
        * Batch upload by URL
        *
        * @param client The client that sends the request
        * @return UploadMediaByURLResponse The response data for the batch upload by URL
        * @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 URL of the video source file
           request.setUploadURLs(encodeUrl);
   
           // The metadata of the video to upload
           JSONObject uploadMetadata = new JSONObject();
           // The URL of the video source file to upload. This must match a URL in UploadURLs to take effect.
           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());
   
           // UserData: The user-defined parameter settings. Set this parameter when you need to specify a webhook address and pass-through data. This parameter is optional.
           JSONObject userData = new JSONObject();
   
           // UserData callback settings
           // Message callback settings. If this parameter is set, it overrides the global event notification settings.
           JSONObject messageCallback = new JSONObject();
           // Set the webhook address
           messageCallback.put("CallbackURL", "http://192.168.0.0/16");
           // Set 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. Retrieve the upload result.

   Method 1: Use event notifications

   ApsaraVideo VOD supports HTTP callbacks and MNS callbacks. After you configure event notifications, ApsaraVideo VOD sends a notification when media processing is complete, for example, when an upload or transcoding is finished. For more information about the configuration, see Event notifications.

   The event type for URL-based batch upload is UploadByURLComplete. You can retrieve information such as the job status from the callback response.

   • Sample callback for a successful upload

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

   • Sample callback for 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": "4c815bjsued****" ,
       "SourceURL ": "http://example.aliyundoc.com/27ffc438-164d55217ef-0005-6884-51a-1****.mp4",
     }

   Method 2: Call an API operation

   Call the GetURLUploadInfos operation to query the status of a URL-based upload job.

Upload resources using a self-built upload service

If URL-based batch upload is not supported in your service region or you require high upload timeliness, you can download the files and use the ApsaraVideo VOD upload SDK to upload them. If you deploy your upload service on an Elastic Compute Service (ECS) instance, you can choose to upload over an internal network or the Internet based on the region of the ECS instance.

Add OSS buckets to ApsaraVideo VOD and register resources

Scenarios

If resources are stored in an OSS bucket under the same Alibaba Cloud account, you can add the bucket to ApsaraVideo VOD and register the resources. This method avoids the need to re-upload the resources.

Limits

• Only OSS buckets with Standard storage class are supported.

• Up to 10 OSS buckets can be added per region.

Procedure

1. Add the OSS bucket that contains the resources to migrate to ApsaraVideo VOD.

   For step-by-step instructions and parameter descriptions, see Manage storage buckets.

2. Register the OSS resources with ApsaraVideo VOD by calling an API operation.

   1. List all objects in the bucket using the OSS API or SDK. For more information, see List objects.

   2. Call the RegisterMedia operation to register media files and generate media IDs. Set the FileURL in the RegisterMetadatas parameter to the full path of the object, including the OSS domain name. For example:

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

Set up an upload service

To migrate third-party resources or resources between Alibaba Cloud accounts, you must download the original videos and upload them to ApsaraVideo VOD. ApsaraVideo VOD provides two upload tools: the upload SDK and the server-side API. You can implement your upload service using either tool. We recommend that you use the upload SDK because it performs synchronous uploads and is more efficient. Using the server-side API is complex and error-prone.

Steps to set up an upload service

1. Integrate the upload SDK or server-side SDK.

   Choose the SDK based on your programming language. For more information about how to integrate the upload SDK, see Upload SDK overview. For more information about how to integrate the server-side SDK, see Server-side SDK.

2. Write the upload service code. See the following examples.

Upload SDK code sample (recommended)

The following example uses Java. For examples in other programming languages, see Upload SDK 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 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 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 permissions to call 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 do 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);
    }
}

Server-side API code example (not recommended)

To set up an upload service using the server-side API, you must implement the entire upload logic yourself. This includes retrieving upload URLs and credentials from ApsaraVideo VOD, Base64-decoding the credentials and URLs, and using the OSS SDK to upload media files. This method is complex and error-prone. We recommend that you use the upload SDK instead. For the complete upload logic, see Upload media files by calling the ApsaraVideo VOD API.