Use transfer acceleration to accelerate data uploads and downloads over long distances - Object Storage Service

You can enable transfer acceleration to speed up the uploads and downloads of objects in a bucket over long distances. For example, if you are located in the Chinese mainland, you can enable transfer acceleration when you upload objects to or download objects from a bucket that is located outside the Chinese mainland. This way, the data uploads or downloads are accelerated. The transfer acceleration feature provides an optimized end-to-end solution with data centers distributed around the world to accelerate access to Object Storage Service (OSS) over the Internet. When the feature is enabled, requests destined for your bucket are routed to the data center nearest to users over the optimal network path and protocol.

Prerequisites

Real-name registration for the current Alibaba Cloud account is completed. For more information, see How do I complete real-name registration?

Scenarios

Accelerate remote data transfer
Forums and online collaboration tools that provide services to users around the world can store data in OSS. Transfer acceleration allows users from different regions to access data in OSS over the optimal network path. This accelerates data transfer and improves user experience.
Accelerate uploads and downloads of gigabyte-grade and terabyte-grade objects
When large objects are uploaded or downloaded over long distances, transmission failures may occur due to high network latencies. Transfer acceleration combines optimal route selection, protocol stack tuning, and transmission algorithm optimization to reduce timeouts during remote transfers of large objects over the Internet. You can combine transfer acceleration with multipart upload and resumable download to implement a solution for long-distance uploads and downloads of large objects.
Accelerate downloads of dynamic and cold data
User experience is a driving factor for product competitiveness and customer retention in applications that require high data download speeds, such as photo management applications, games, e-commerce applications, enterprise portal websites, and financial applications. High download speeds are also required to obtain good feedback on social networking applications. You can use transfer acceleration to maximize bandwidth utilization and accelerate data transfers from OSS.

Usage notes

Transfer acceleration is supported in the following regions: China (Hangzhou), China (Shanghai), China (Nanjing-Local Region), China (Fuzhou-Local Region), China (Qingdao), China (Beijing), China (Zhangjiakou), China (Hohhot), China (Ulanqab), China (Shenzhen), China (Heyuan), China (Guangzhou), China (Chengdu), China (Hong Kong), US (Silicon Valley), US (Virginia), Japan (Tokyo), South Korea (Seoul), Singapore, Australia (Sydney) Closing Down, Malaysia (Kuala Lumpur), Indonesia (Jakarta), Philippines (Manila), Thailand (Bangkok), Germany (Frankfurt), UK (London), and UAE (Dubai).
You are charged transfer acceleration fees when you use an acceleration endpoint to accelerate data uploads. You are charged transfer acceleration fees and the fees for outbound traffic over the Internet when you use an acceleration endpoint to accelerate data downloads. For example, if you use an acceleration endpoint to download 1 GB data from a bucket for which transfer acceleration is enabled, you are charged transfer acceleration fees of 1 GB data and the fees for 1 GB outbound traffic over the Internet. For more information, see Transfer acceleration fees and Traffic fees.
When transfer acceleration is enabled, an acceleration endpoint is required to improve the access speed. However, you can still use the default endpoint to access OSS. In scenarios in which transfer acceleration is not required, you can use the default endpoint to prevent unnecessary charges. For more information about endpoints, see Regions and endpoints.
When you access OSS by calling API operations with a transfer endpoint specified, only the HTTP or HTTPS protocol is supported. Other protocols, such as Real-Time Messaging Protocol (RTMP) are not supported.
Based on the transfer acceleration logic, HTTPS may be used to ensure secure data transfers. Even if the client uses an acceleration endpoint to access a bucket over HTTP, the protocol recorded in the access log may be HTTPS.

Enable transfer acceleration

After you enable transfer acceleration for a bucket, you can access the bucket by using the default endpoint or one of the following transfer acceleration endpoints:

Global acceleration endpoint: oss-accelerate.aliyuncs.com. Acceleration endpoints are distributed around the world. You can use a global acceleration endpoint to accelerate data transfer for buckets in all regions.
Acceleration endpoint of regions outside the Chinese mainland: oss-accelerate-overseas.aliyuncs.com. Acceleration endpoints are distributed across regions outside the Chinese mainland. You can use the acceleration endpoint of regions outside the Chinese mainland only when you add a CNAME record to point a mapped custom domain without ICP filing to the OSS-accelerated domain for a bucket that is located in the China (Hong Kong) region or other regions outside the Chinese mainland.

You can use one of the following methods to enable transfer acceleration.

Use the OSS console

Log on to the OSS console.
In the left-side navigation pane, click Buckets. On the Buckets page, find and click the desired bucket.
In the left-side navigation tree, choose Bucket Settings > Transfer Acceleration.
On the Transfer Acceleration page, turn on Transfer Acceleration and click OK in the message that appears.
After you enable or disable transfer acceleration, approximately 30 minutes are required for the change to take effect.

Use OSS SDKs

The following sample code provides examples on how to enable transfer acceleration by using OSS SDKs for common programming languages. For more information about how to enable transfer acceleration by using OSS SDKs for other programming languages, see Overview.

Java

import com.aliyun.oss.ClientException;
import com.aliyun.oss.OSS;
import com.aliyun.oss.common.auth.*;
import com.aliyun.oss.OSSClientBuilder;
import com.aliyun.oss.OSSException;

public class Demo {

    public static void main(String[] args) throws Exception {
        // In this example, the endpoint of the China (Hangzhou) region is used. Specify your actual endpoint. 
        String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
        // Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. 
        EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
        // Specify the name of the bucket. Example: examplebucket. 
        String bucketName = "examplebucket";

        // Create an OSSClient instance. 
        OSS ossClient = new OSSClientBuilder().build(endpoint, credentialsProvider);

        try {
            // Configure transfer acceleration for the bucket. 
            // If enabled is set to true, transfer acceleration is enabled. If enabled is set to false, transfer acceleration is disabled. 
            boolean enabled = true;
            ossClient.setBucketTransferAcceleration(bucketName, enabled);

        } catch (OSSException oe) {
            System.out.println("Caught an OSSException, which means your request made it to OSS, "
                    + "but was rejected with an error response for some reason.");
            System.out.println("Error Message:" + oe.getErrorMessage());
            System.out.println("Error Code:" + oe.getErrorCode());
            System.out.println("Request ID:" + oe.getRequestId());
            System.out.println("Host ID:" + oe.getHostId());
        } catch (ClientException ce) {
            System.out.println("Caught an ClientException, which means the client encountered "
                    + "a serious internal problem while trying to communicate with OSS, "
                    + "such as not being able to access the network.");
            System.out.println("Error Message:" + ce.getMessage());
        } finally {
            if (ossClient != null) {
                ossClient.shutdown();
            }
        }
    }
}

Python

import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider

# Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. 
auth = oss2.ProviderAuth(EnvironmentVariableCredentialsProvider())
# Specify the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com. 
# Specify the name of the bucket. 
bucket = oss2.Bucket(auth, 'https://oss-cn-hangzhou.aliyuncs.com', 'examplebucket')

# Configure transfer acceleration for the bucket. 
# If enabled is set to true, transfer acceleration is enabled. If enabled is set to false, transfer acceleration is disabled. 
enabled = 'true'
bucket.put_bucket_transfer_acceleration(enabled)

package main

import (
	"fmt"
	"os"

	"github.com/aliyun/aliyun-oss-go-sdk/oss"
)

func HandleError(err error) {
	fmt.Println("Error:", err)
	os.Exit(-1)
}

func main() {
	// Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. 
	provider, err := oss.NewEnvironmentVariableCredentialsProvider()
	if err != nil {
		fmt.Println("Error:", err)
		os.Exit(-1)
	}
	// Create an OSSClient instance. 
	// Specify the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com. Specify your actual endpoint. 
	client, err := oss.New("yourEndpoint", "", "", oss.SetCredentialsProvider(&provider))
	if err != nil {
		fmt.Println("Error:", err)
		os.Exit(-1)
	}

	// Specify the name of the bucket. 
	bucketName := "examplebucket"

	// Enable transfer acceleration for the bucket. 
	// The Enabled parameter specifies whether to enable transfer acceleration. A value of true specifies that transfer acceleration is enabled. A value of false specifies that transfer acceleration is disabled. 
	accConfig := oss.TransferAccConfiguration{}
	accConfig.Enabled = true

	err = client.SetBucketTransferAcc(bucketName, accConfig)
	if err != nil {
		HandleError(err)
	}
	fmt.Printf("set bucket transfer accelerate success\n")
}

Use the OSS API

If your business requires a high level of customization, you can directly call RESTful APIs. To directly call an API, you must include the signature calculation in your code. For more information, see PutBucketTransferAcceleration.

Use transfer acceleration

Use a browser

When you use an object URL to access the object from a browser, replace the endpoint part of the URL with an acceleration endpoint. For example, to use transfer acceleration to accelerate access to https://test.oss-cn-shenzhen.aliyuncs.com/myphoto.jpg, change the URL to https://test.oss-accelerate.aliyuncs.com/myphoto.jpg. If the access control list (ACL) of the object that you want to access is private, you must sign the access request.

Use ossutil

Replace the endpoint specified in the configuration file of ossutil with an acceleration endpoint
If you need to accelerate access to data in a bucket by using ossutil, replace the endpoint specified in the configuration file with an acceleration endpoint. For more information, see ossutil.
Add -e oss-accelerate.aliyuncs.com to commands
When you run commands in ossutil, add -e oss-accelerate.aliyuncs.com to the commands. The following figure shows how to specify an acceleration endpoint when you run the cp command to upload an object by using ossutil.

Use ossbrowser

Important

When you access a bucket by using ossbrowser, you must specify your AccessKey pair and the preset path of the bucket or the directory of the bucket in OSS.

The following table describes the parameters that you must configure when you use ossbrowser to access data in OSS.

Parameter	Description
Endpoint	Select Customize and enter `https://oss-accelerate.aliyuncs.com`.
AccessKeyId and AccessKeySecret	Provide the AccessKey pair of your account. For more information about how to obtain the AccessKey pair, see Obtain an AccessKey pair. Important To ensure data security, we recommend that you use the AccessKey pair of a RAM user to log on to ossbrowser. To log on as a RAM user, make sure that the following policies are attached to the RAM user: `AliyunOSSFullAccess`, `AliyunRAMFullAccess`, and `AliyunSTSAssumeRoleAccess`. For more information, see Manage permissions.
Preset OSS Path	Specify the bucket or the directory of the bucket to which the user has access. Format: `oss://bucketname/path` For example, if you are authorized to access only objects and subdirectories in the examplefolder directory of a bucket named examplebucket, enter `oss://examplebucket/examplefolder/`.

Example:

Use OSS SDKs

If you need to accelerate data access by using OSS SDKs, set the endpoint parameter to an acceleration endpoint. The following sample code provides examples on how to accelerate simple uploads and simple downloads by using OSS SDK for Java.

Simple upload

import com.aliyun.oss.ClientException;
import com.aliyun.oss.OSS;
import com.aliyun.oss.common.auth.*;
import com.aliyun.oss.OSSClientBuilder;
import com.aliyun.oss.OSSException;
import com.aliyun.oss.model.PutObjectRequest;
import java.io.File;

public class Demo {

    public static void main(String[] args) throws Exception {
        // Specify an acceleration endpoint. In this example, the global acceleration endpoint is used. 
        String endpoint = "https://oss-accelerate.aliyuncs.com";
        // We recommend that you do not save access credentials in the project code. Otherwise, access credentials may be leaked. As a result, the security of all resources in your account is compromised. In this example, access credentials are obtained from environment variables. Before you run the sample code, make sure that the environment variables are configured. 
        EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
        // Specify the name of the bucket. Example: examplebucket. 
        String bucketName = "examplebucket";
        // Specify the full path of the object. Example: exampledir/exampleobject.txt. Do not include the bucket name in the full path. 
        String objectName = "exampledir/exampleobject.txt";
        // Specify the full path of the local file that you want to upload. Example: D:\\localpath\\examplefile.txt. 
        // If the path of the local file is not specified, the local file is uploaded from the path of the project to which the sample program belongs. 
        String filePath= "D:\\localpath\\examplefile.txt";

        // Create an OSSClient instance. 
        OSS ossClient = new OSSClientBuilder().build(endpoint, credentialsProvider);

        try {
            // Create a PutObjectRequest object.             
            PutObjectRequest putObjectRequest = new PutObjectRequest(bucketName, objectName, filePath);
            // Optional. Specify the storage class and ACL of the object. 
            // ObjectMetadata metadata = new ObjectMetadata();
            // metadata.setHeader(OSSHeaders.OSS_STORAGE_CLASS, StorageClass.Standard.toString());
            // metadata.setObjectAcl(CannedAccessControlList.Private);
            // putObjectRequest.setMetadata(metadata);

            // Upload the local file. 
            ossClient.putObject(putObjectRequest);
        } catch (OSSException oe) {
            System.out.println("Caught an OSSException, which means your request made it to OSS, "
                    + "but was rejected with an error response for some reason.");
            System.out.println("Error Message:" + oe.getErrorMessage());
            System.out.println("Error Code:" + oe.getErrorCode());
            System.out.println("Request ID:" + oe.getRequestId());
            System.out.println("Host ID:" + oe.getHostId());
        } catch (ClientException ce) {
            System.out.println("Caught an ClientException, which means the client encountered "
                    + "a serious internal problem while trying to communicate with OSS, "
                    + "such as not being able to access the network.");
            System.out.println("Error Message:" + ce.getMessage());
        } finally {
            if (ossClient != null) {
                ossClient.shutdown();
            }
        }
    }
}

Simple download

import com.aliyun.oss.ClientException;
import com.aliyun.oss.OSS;
import com.aliyun.oss.common.auth.*;
import com.aliyun.oss.OSSClientBuilder;
import com.aliyun.oss.OSSException;
import com.aliyun.oss.model.GetObjectRequest;
import java.io.File;

public class Demo {

    public static void main(String[] args) throws Exception {
        // Specify an acceleration endpoint. In this example, the global acceleration endpoint is used. 
        String endpoint = "https://oss-accelerate.aliyuncs.com";
        // We recommend that you do not save access credentials in the project code. Otherwise, access credentials may be leaked. As a result, the security of all resources in your account is compromised. In this example, access credentials are obtained from environment variables. Before you run the sample code, make sure that the environment variables are configured. 
        EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
        // Specify the name of the bucket. Example: examplebucket. 
        String bucketName = "examplebucket";
        // Specify the full path of the object. Do not include the bucket name in the full path. Example: testfolder/exampleobject.txt. 
        String objectName = "testfolder/exampleobject.txt";
        String filePath = "D:\\localpath\\examplefile.txt";

        // Create an OSSClient instance. 
        OSS ossClient = new OSSClientBuilder().build(endpoint, credentialsProvider);

        try {
            // Download the object as a local file in the specified path. If a file that has the same name already exists in the path, the downloaded object overwrites the file. If no file that has the same name exists in the path, the downloaded object is saved in the path. 
            // If you do not specify a local path for the downloaded object, the downloaded object is saved to the path of the project to which the sample program belongs. 
            ossClient.getObject(new GetObjectRequest(bucketName, objectName), new File(filePath));
        } catch (OSSException oe) {
            System.out.println("Caught an OSSException, which means your request made it to OSS, "
                    + "but was rejected with an error response for some reason.");
            System.out.println("Error Message:" + oe.getErrorMessage());
            System.out.println("Error Code:" + oe.getErrorCode());
            System.out.println("Request ID:" + oe.getRequestId());
            System.out.println("Host ID:" + oe.getHostId());
        } catch (ClientException ce) {
            System.out.println("Caught an ClientException, which means the client encountered "
                    + "a serious internal problem while trying to communicate with OSS, "
                    + "such as not being able to access the network.");
            System.out.println("Error Message:" + ce.getMessage());
        } finally {
            if (ossClient != null) {
                ossClient.shutdown();
            }
        }
    }
}

Test the effect of transfer acceleration

Use ossutil

You can run commands in ossutil to upload an object to OSS by using the default endpoint and an acceleration endpoint, respectively. You can compare the time that is used to upload the object to verify the effect of transfer acceleration. In the sample commands shown in the following figure, -e oss-us-west-1.aliyuncs.com is used to upload the object by using the default endpoint, and -e oss-accelerate.aliyuncs.com is used to upload the object by using the acceleration endpoint.

FAQ

Does OSS support other acceleration solutions in addition to transfer acceleration?

Yes, OSS also supports access acceleration based on Alibaba Cloud CDN. For more information, see Use Alibaba Cloud CDN to accelerate access to OSS.

Can I configure multiple acceleration solutions at the same time?

Yes, you can configure multiple acceleration solutions at the same time. For example, after you enable Alibaba Cloud CDN, you can also enable transfer acceleration, specify the OSS-accelerated domain as the origin of the CDN-accelerated domain, and then map the CDN-accelerated domain to the OSS bucket. For more information, see Map accelerated domain names.

Why am I unable to list buckets by using an acceleration endpoint?

Transfer acceleration takes effect only for domain names in the https://BucketName.oss-accelerate.aliyuncs.com format. Acceleration endpoints do not include a bucket name. Therefore, acceleration endpoints cannot be used to list buckets. To list buckets in a specific region, we recommend that you use the default endpoint of the region, such as https://oss-cn-hangzhou.aliyuncs.com for the China (Hangzhou) region.