简单下载指的是使用OSS API的GetObject接口,下载已上传的文件(Object),适用于一次HTTP请求交互即可完成下载的场景。
前提条件
操作方式
使用OSS控制台
不支持通过OSS控制台下载文件夹(包含子目录)。如果需要下载文件夹(包含子目录),您可以使用ossbrowser、ossutil、SDK、API等方式进行下载。
登录OSS管理控制台。
单击Bucket 列表,然后单击目标Bucket名称。
在左侧导航栏,选择文件管理>文件列表。
下载文件。
下载单个文件
方式一:选择目标文件右侧的
> 下载。
说明如果您已将该操作项从默认的收藏进更多移到文件常见操作,则无需展开
图标即可直接查看到该操作项。
方式二:单击目标文件的文件名或其右侧的详情,在弹出的详情面板中单击下载。
下载多个文件
选中多个文件,然后单击下方的下载。通过OSS控制台可一次批量下载最多100个文件。
使用图形化管理工具ossbrowser
ossbrowser支持Object级别的操作与控制台支持的操作类似,请按照ossbrowser界面指引完成简单下载的操作。关于如何使用ossbrowser,请参见ossbrowser 2.0。
使用阿里云SDK
以下仅列举常见SDK的简单下载的代码示例。关于其他SDK的简单下载的代码示例,请参见SDK简介。
package com.aliyun.oss.demo;
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 {
// Endpoint以华东1(杭州)为例,其它Region请按实际情况填写。
String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
//从环境变量中获取访问凭证。运行本代码示例之前,请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
// 填写Bucket名称,例如examplebucket。
String bucketName = "examplebucket";
// 填写不包含Bucket名称在内的Object完整路径,例如testfolder/exampleobject.txt。
String objectName = "testfolder/exampleobject.txt";
// 填写Object下载到本地的完整路径。
String pathName = "D:\\localpath\\examplefile.txt";
// 填写Bucket所在地域。以华东1(杭州)为例,Region填写为cn-hangzhou。
String region = "cn-hangzhou";
// 创建OSSClient实例。
ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);
OSS ossClient = OSSClientBuilder.create()
.endpoint(endpoint)
.credentialsProvider(credentialsProvider)
.clientConfiguration(clientBuilderConfiguration)
.region(region)
.build();
try {
// 下载Object到本地文件,并保存到指定的本地路径中。如果指定的本地文件存在会覆盖,不存在则新建。
// 如果未指定本地路径,则下载后的文件默认保存到示例程序所属项目对应本地路径中。
ossClient.getObject(new GetObjectRequest(bucketName, objectName), new File(pathName));
} 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();
}
}
}
}
<?php
if (is_file(__DIR__ . '/../autoload.php')) {
require_once __DIR__ . '/../autoload.php';
}
if (is_file(__DIR__ . '/../vendor/autoload.php')) {
require_once __DIR__ . '/../vendor/autoload.php';
}
use OSS\Credentials\EnvironmentVariableCredentialsProvider;
use OSS\OssClient;
// 从环境变量中获取访问凭证。运行本代码示例之前,请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
$provider = new EnvironmentVariableCredentialsProvider();
// 填写Bucket所在地域对应的Endpoint。以华东1(杭州)为例,Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。
$endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
// 填写Bucket名称,例如examplebucket。
$bucket= "examplebucket";
// 填写不包含Bucket名称在内的Object完整路径,例如testfolder/exampleobject.txt。
$object = "testfolder/exampleobject.txt";
// 下载Object到本地文件examplefile.txt,并保存到指定的本地路径中(D:\\localpath)。如果指定的本地文件存在会覆盖,不存在则新建。
// 如果未指定本地路径,则下载后的文件默认保存到示例程序所属项目对应本地路径中。
$localfile = "D:\\localpath\\examplefile.txt";
$options = array(
OssClient::OSS_FILE_DOWNLOAD => $localfile
);
// 使用try catch捕获异常。如果捕获到异常,则说明下载失败;如果没有捕获到异常,则说明下载成功。
try{
$config = array(
"provider" => $provider,
"endpoint" => $endpoint,
"signatureVersion" => OssClient::OSS_SIGNATURE_VERSION_V4,
"region"=> "cn-hangzhou"
);
$ossClient = new OssClient($config);
$ossClient->getObject($bucket, $object, $options);
} catch(OssException $e) {
printf(__FUNCTION__ . ": FAILED\n");
printf($e->getMessage() . "\n");
return;
}
print(__FUNCTION__ . ": OK, please check localfile: 'examplefile.txt'" . "\n");
const OSS = require('ali-oss');
const client = new OSS({
// yourregion填写Bucket所在地域。以华东1(杭州)为例,Region填写为oss-cn-hangzhou。
region: 'yourRegion',
// 从环境变量中获取访问凭证。运行本代码示例之前,请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
accessKeyId: process.env.OSS_ACCESS_KEY_ID,
accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
authorizationV4: true,
// 填写Bucket名称。
bucket: 'examplebucket'
});
async function get () {
try {
// 填写Object完整路径和本地文件的完整路径。Object完整路径中不能包含Bucket名称。
// 如果指定的本地文件存在会覆盖,不存在则新建。
// 如果未指定本地路径,则下载后的文件默认保存到示例程序所属项目对应本地路径中。
const result = await client.get('exampleobject.txt', 'D:\\localpath\\examplefile.txt');
console.log(result);
} catch (e) {
console.log(e);
}
}
get();
# -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider
# 创建Server对象。
# 从环境变量中获取访问凭证。运行本代码示例之前,请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())
# 填写Bucket所在地域对应的Endpoint。以华东1(杭州)为例,Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。
endpoint = "https://oss-cn-hangzhou.aliyuncs.com"
# 填写Endpoint对应的Region信息,例如cn-hangzhou。注意,v4签名下,必须填写该参数
region = "cn-hangzhou"
# yourBucketName填写存储空间名称。
bucket = oss2.Bucket(auth, endpoint, "yourBucketName", region=region)
# 填写Object完整路径,完整路径中不包含Bucket名称,例如testfolder/exampleobject.txt。
# 下载Object到本地文件,并保存到指定的本地路径D:\\localpath\\examplefile.txt。如果指定的本地文件存在会覆盖,不存在则新建。
bucket.get_object_to_file('testfolder/exampleobject.txt', 'D:\\localpath\\examplefile.txt')
print("Download complete.")
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<title>Document</title>
</head>
<body>
<!--导入SDK文件-->
<script
type="text/javascript"
src="https://gosspublic.alicdn.com/aliyun-oss-sdk-6.18.0.min.js"
></script>
<script type="text/javascript">
const client = new OSS({
// yourRegion填写Bucket所在地域。以华东1(杭州)为例,Region填写为oss-cn-hangzhou。
region: "yourRegion",
authorizationV4: true,
// 从STS服务获取的临时访问密钥(AccessKey ID和AccessKey Secret)。
accessKeyId: "yourAccessKeyId",
accessKeySecret: "yourAccessKeySecret",
// 从STS服务获取的安全令牌(SecurityToken)。
stsToken: "yoursecurityToken",
// 填写Bucket名称。
bucket: "examplebucket",
});
// 配置响应头实现通过URL访问时自动下载文件,并设置下载后的文件名。
const filename = "examplefile.txt";
const response = {
"content-disposition": `attachment; filename=${encodeURIComponent(
filename
)}`,
};
// 填写Object完整路径。Object完整路径中不能包含Bucket名称。
const url = client.signatureUrl("exampleobject.txt", { response });
console.log(url);
</script>
</body>
</html>
// 构造下载文件请求。
// 依次填写Bucket名称(例如examplebucket)和Object完整路径(例如exampledir/exampleobject.txt)。Object完整路径中不能包含Bucket名称。
GetObjectRequest get = new GetObjectRequest("examplebucket", "exampledir/exampleobject.txt");
oss.asyncGetObject(get, new OSSCompletedCallback<GetObjectRequest, GetObjectResult>() {
@Override
public void onSuccess(GetObjectRequest request, GetObjectResult result) {
// 开始读取数据。
long length = result.getContentLength();
if (length > 0) {
byte[] buffer = new byte[(int) length];
int readCount = 0;
while (readCount < length) {
try{
readCount += result.getObjectContent().read(buffer, readCount, (int) length - readCount);
}catch (Exception e){
OSSLog.logInfo(e.toString());
}
}
// 将下载后的文件存放在指定的本地路径,例如D:\\localpath\\exampleobject.jpg。
try {
FileOutputStream fout = new FileOutputStream("download_filePath");
fout.write(buffer);
fout.close();
} catch (Exception e) {
OSSLog.logInfo(e.toString());
}
}
}
@Override
public void onFailure(GetObjectRequest request, ClientException clientException,
ServiceException serviceException) {
}
});
OSSGetObjectRequest * request = [OSSGetObjectRequest new];
// 填写Bucket名称,例如examplebucket。
request.bucketName = @"examplebucket";
// 填写文件完整路径,例如exampledir/exampleobject.txt。Object完整路径中不能包含Bucket名称。
request.objectKey = @"exampledir/exampleobject.txt";
// 可选字段。
request.downloadProgress = ^(int64_t bytesWritten, int64_t totalBytesWritten, int64_t totalBytesExpectedToWrite) {
// 当前下载段长度、当前已经下载总长度、一共需要下载的总长度。
NSLog(@"%lld, %lld, %lld", bytesWritten, totalBytesWritten, totalBytesExpectedToWrite);
};
// request.range = [[OSSRange alloc] initWithStart:0 withEnd:99]; // bytes=0-99,指定范围下载。
// request.downloadToFileURL = [NSURL fileURLWithPath:@"<filepath>"]; // 如果需要直接下载到文件,需要指明目标文件地址。
OSSTask * getTask = [client getObject:request];
[getTask continueWithBlock:^id(OSSTask *task) {
if (!task.error) {
NSLog(@"download object success!");
OSSGetObjectResult * getResult = task.result;
NSLog(@"download result: %@", getResult.downloadedData);
} else {
NSLog(@"download object failed, error: %@" ,task.error);
}
return nil;
}];
// [getTask waitUntilFinished];
// [request cancel];
#include <alibabacloud/oss/OssClient.h>
#include <memory>
#include <fstream>
using namespace AlibabaCloud::OSS;
int main(void)
{
/* 初始化OSS账号信息。*/
/* yourEndpoint填写Bucket所在地域对应的Endpoint。以华东1(杭州)为例,Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。*/
std::string Endpoint = "yourEndpoint";
/* yourRegion填写Bucket所在地域对应的Region。以华东1(杭州)为例,Region填写为cn-hangzhou。*/
std::string Region = "yourRegion";
/* 填写Bucket名称,例如examplebucket。*/
std::string BucketName = "examplebucket";
/* 填写Object完整路径,完整路径中不能包含Bucket名称,例如exampledir/exampleobject.txt。*/
std::string ObjectName = "exampledir/exampleobject.txt";
/* 下载Object到本地文件examplefile.txt,并保存到指定的本地路径中(D:\\localpath)。如果指定的本地文件存在会覆盖,不存在则新建。*/
/* 如果未指定本地路径,则下载后的文件默认保存到示例程序所属项目对应本地路径中。*/
std::string FileNametoSave = "D:\\localpath\\examplefile.txt";
/* 初始化网络等资源。*/
InitializeSdk();
ClientConfiguration conf;
conf.signatureVersion = SignatureVersionType::V4;
/* 从环境变量中获取访问凭证。运行本代码示例之前,请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。*/
auto credentialsProvider = std::make_shared<EnvironmentVariableCredentialsProvider>();
OssClient client(Endpoint, credentialsProvider, conf);
client.SetRegion(Region);
/* 下载Object到本地文件。*/
GetObjectRequest request(BucketName, ObjectName);
request.setResponseStreamFactory([=]() {return std::make_shared<std::fstream>(FileNametoSave, std::ios_base::out | std::ios_base::in | std::ios_base::trunc| std::ios_base::binary); });
auto outcome = client.GetObject(request);
if (outcome.isSuccess()) {
std::cout << "GetObjectToFile success" << outcome.result().Metadata().ContentLength() << std::endl;
}
else {
/* 异常处理。*/
std::cout << "GetObjectToFile fail" <<
",code:" << outcome.error().Code() <<
",message:" << outcome.error().Message() <<
",requestId:" << outcome.error().RequestId() << std::endl;
return -1;
}
/* 释放网络等资源。*/
ShutdownSdk();
return 0;
}
#include "oss_api.h"
#include "aos_http_io.h"
/* yourEndpoint填写Bucket所在地域对应的Endpoint。以华东1(杭州)为例,Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。*/
const char *endpoint = "yourEndpoint";
/* 填写Bucket名称,例如examplebucket。*/
const char *bucket_name = "examplebucket";
/* 填写Object完整路径,完整路径中不能包含Bucket名称,例如exampledir/exampleobject.txt。*/
const char *object_name = "exampledir/exampleobject.txt";
/* 填写本地文件的完整路径。*/
const char *local_filename = "yourLocalFilename";
/* yourRegion填写Bucket所在地域对应的Region。以华东1(杭州)为例,Region填写为cn-hangzhou。*/
const char *region = "yourRegion";
void init_options(oss_request_options_t *options)
{
options->config = oss_config_create(options->pool);
/* 用char*类型的字符串初始化aos_string_t类型。*/
aos_str_set(&options->config->endpoint, endpoint);
/* 从环境变量中获取访问凭证。运行本代码示例之前,请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。*/
aos_str_set(&options->config->access_key_id, getenv("OSS_ACCESS_KEY_ID"));
aos_str_set(&options->config->access_key_secret, getenv("OSS_ACCESS_KEY_SECRET"));
//需要额外配置以下两个参数
aos_str_set(&options->config->region, region);
options->config->signature_version = 4;
/* 是否使用了CNAME。0表示不使用。*/
options->config->is_cname = 0;
/* 用于设置网络相关参数,比如超时时间等。*/
options->ctl = aos_http_controller_create(options->pool, 0);
}
int main(int argc, char *argv[])
{
/* 在程序入口调用aos_http_io_initialize方法来初始化网络、内存等全局资源。*/
if (aos_http_io_initialize(NULL, 0) != AOSE_OK) {
exit(1);
}
/* 用于内存管理的内存池(pool),等价于apr_pool_t。其实现代码在apr库中。*/
aos_pool_t *pool;
/* 重新创建一个内存池,第二个参数是NULL,表示没有继承其它内存池。*/
aos_pool_create(&pool, NULL);
/* 创建并初始化options,该参数包括endpoint、access_key_id、acces_key_secret、is_cname、curl等全局配置信息。*/
oss_request_options_t *oss_client_options;
/* 在内存池中分配内存给options。*/
oss_client_options = oss_request_options_create(pool);
/* 初始化Client的选项oss_client_options。*/
init_options(oss_client_options);
/* 初始化参数。*/
aos_string_t bucket;
aos_string_t object;
aos_string_t file;
aos_table_t *params;
aos_table_t *headers = NULL;
aos_table_t *resp_headers = NULL;
aos_status_t *resp_status = NULL;
aos_str_set(&bucket, bucket_name);
aos_str_set(&object, object_name);
aos_str_set(&file, local_filename);
params = aos_table_make(pool, 0);
/* 下载文件。如果指定的本地文件存在会覆盖,不存在则新建。*/
resp_status = oss_get_object_to_file(oss_client_options, &bucket, &object, headers, params, &file, &resp_headers);
if (aos_status_is_ok(resp_status)) {
printf("Get object from file succeeded\n");
} else {
printf("Get object from file failed\n");
}
/* 释放内存池,相当于释放了请求过程中各资源分配的内存。*/
aos_pool_destroy(pool);
/* 释放之前分配的全局资源。*/
aos_http_io_deinitialize();
return 0;
}
require 'aliyun/oss'
client = Aliyun::OSS::Client.new(
# Endpoint以华东1(杭州)为例,其它Region请按实际情况填写。
endpoint: 'https://oss-cn-hangzhou.aliyuncs.com',
# 从环境变量中获取访问凭证。运行本代码示例之前,请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
access_key_id: ENV['OSS_ACCESS_KEY_ID'],
access_key_secret: ENV['OSS_ACCESS_KEY_SECRET']
)
# 填写Bucket名称,例如examplebucket。
bucket = client.get_bucket('examplebucket')
# 将Object下载至本地。
bucket.get_object('exampleobject.txt', :file => 'D:\\localpath\\examplefile.txt')
package main
import (
"context"
"flag"
"log"
"net/http"
"time"
"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
)
// 定义全局变量
var (
region string // 存储区域
bucketName string // 存储空间名称
objectName string // 对象名称
)
// init函数用于初始化命令行参数
func init() {
flag.StringVar(®ion, "region", "", "The region in which the bucket is located.")
flag.StringVar(&bucketName, "bucket", "", "The name of the bucket.")
flag.StringVar(&objectName, "object", "", "The name of the object.")
}
func main() {
// 解析命令行参数
flag.Parse()
// 检查bucket名称是否为空
if len(bucketName) == 0 {
flag.PrintDefaults()
log.Fatalf("invalid parameters, bucket name required")
}
// 检查region是否为空
if len(region) == 0 {
flag.PrintDefaults()
log.Fatalf("invalid parameters, region required")
}
// 检查object名称是否为空
if len(objectName) == 0 {
flag.PrintDefaults()
log.Fatalf("invalid parameters, object name required")
}
// 加载默认配置并设置凭证提供者和区域
cfg := oss.LoadDefaultConfig().
WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
WithRegion(region)
// 创建OSS客户端
client := oss.NewClient(cfg)
// 指定本地文件路径
localFile := "download.file"
// 假设Object最后修改时间为2024年10月21日18:43:02,则填写的UTC早于该时间时,将满足IfModifiedSince的限定条件,并触发下载行为。
date := time.Date(2024, time.October, 21, 18, 43, 2, 0, time.UTC)
// 假设ETag为e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855,则填写的ETag与Object的ETag值相等时,将满足IfMatch的限定条件,并触发下载行为。
etag := "\"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855\""
// 创建下载对象到本地文件的请求
getRequest := &oss.GetObjectRequest{
Bucket: oss.Ptr(bucketName), // 存储空间名称
Key: oss.Ptr(objectName), // 对象名称
IfModifiedSince: oss.Ptr(date.Format(http.TimeFormat)), // 指定IfModifiedSince参数
IfMatch: oss.Ptr(etag), // 指定IfMatch参数
}
// 执行下载对象到本地文件的操作并处理结果
result, err := client.GetObjectToFile(context.TODO(), getRequest, localFile)
if err != nil {
log.Fatalf("failed to get object to file %v", err)
}
log.Printf("get object to file result:%#v\n", result)
}
使用命令行工具ossutil
您可以使用命令行工具ossutil来下载文件,ossutil的安装请参见安装ossutil。
以下命令用于获取examplebucket
存储空间下的exampleobject
文件。
ossutil api get-object --bucket examplebucket --key exampleobject
关于该命令的更多信息,请参见get-object。
相关API
以上操作方式底层基于API实现,如果您的程序自定义要求较高,您可以直接发起REST API请求。直接发起REST API请求需要手动编写代码计算签名。更多信息,请参见GetObject。
权限说明
阿里云账号默认拥有全部权限。阿里云账号下的RAM用户或RAM角色默认没有任何权限,需要阿里云账号或账号管理员通过RAM Policy或Bucket Policy授予操作权限。
API | Action | 说明 |
GetObject |
| 下载Object。 |
| 下载Object时,如果通过versionId指定了Object的版本,则需要授予此操作的权限。 | |
| 下载Object时,如果Object的元数据包含X-Oss-Server-Side-Encryption: KMS,则需要此操作的权限。 |
计费说明
简单下载会产生以下计费项。有关计费项的定价详情,请参见OSS产品定价:
API | 计费项 | 说明 |
GetObject | GET 类型请求 | 根据成功的请求次数计算请求费用。 |
外网流出流量费用 | 如果是通过外网Endpoint(示例值oss-cn-hangzhou.aliyuncs.com)或者传输加速Endpoint(示例值oss-accelerate.aliyuncs.com)调用GetObject接口时,会产生外网流出流量费用,根据数据容量大小计费。 | |
低频访问数据取回容量 | 如果取回的数据是低频访问数据,会产生低频访问数据取回容量的费用,按数据取回量计费。 | |
归档直读数据取回容量 | 如果读取的是归档的Object且Bucket开启了归档直读,会产生归档直读数据取回容量费用,根据取回的数据容量大小计费。 | |
传输加速 | 如果开启了传输加速功能且使用传输加速域名访问您的Bucket会产生传输加速费用,根据数据容量大小计费。 |
相关文档
如何在开启了版本控制的Bucket中下载文件,请参见开启版本控制下Object的操作。
如何在暂停了版本控制的Bucket中下载文件,请参见暂停版本控制下Object的操作。
为了防止第三方未经授权从您的Bucket里下载数据,OSS提供了Bucket和Object级别的访问权限控制。更多信息,请参见权限控制。
如果您希望在下载大文件过程中,从下载中断的位置继续下载未完成的部分,您可以使用断点续传。具体操作,请参见断点续传下载。
如果您希望将私有Bucket的Object提供给第三方进行下载,请通过STS临时访问凭证或签名URL的方式授权第三方下载文件。具体操作,请参见授权给第三方下载。
如果您希望在下载文件时,满足限定条件则下载,不满足限定条件则返回错误且不会触发下载行为,您可以在下载文件时指定限制条件。具体操作,请参见限定条件下载。