上传文件、图片、视频等资源到OSS

更新时间:2025-02-18 06:50:29
重要

本文中含有需要您注意的重要提示信息,忽略该信息可能对您的业务造成影响,请务必仔细阅读。

当您需要将本地不超过5GB大小的文件、图片、视频等资源上传到OSS,且对并发上传性能要求不高的情况下,您可以选择简单上传的方式。

前提条件

已创建存储空间(Bucket)。更多信息,请参见创建存储空间

操作方式

警告

禁止在开通了OSS-HDFS服务的Bucket中,通过非OSS-HDFS服务的方式向数据存储目录.dlsdata/上传Object,以避免影响OSS-HDFS服务的正常使用或引发数据丢失风险。

使用OSS控制台

说明

金融云下的OSS没有公网地域,无法通过控制台上传文件,请通过SDK、ossutil、ossbrowser等方式上传。

  1. 登录OSS管理控制台

  2. 单击Bucket 列表,然后单击目标Bucket名称。

  3. 在左侧导航栏,选择文件管理 > 文件列表

  4. 文件列表页面,单击上传文件

  5. 上传文件面板,按如下说明配置各项参数。

    1. 设置基础选项。

      参数

      说明

      上传到

      设置文件上传到目标Bucket后的存储路径。

      • 当前目录:将文件上传到当前目录。

      • 指定目录:将文件上传到指定目录,您需要输入目录名称。若输入的目录不存在,OSS将自动创建对应的文件目录并将文件上传到该目录中。

        目录命名规范如下:

        • 请使用符合要求的UTF-8字符;长度必须在1~254字符之间。

        • 不允许以正斜线(/)或反斜线(\)开头。

        • 不允许出现连续的正斜线(/)。

        • 不允许出现名为 .. 的目录。

      文件ACL

      设置文件读写权限ACL。

      • 继承Bucket:以Bucket读写权限为准。

      • 私有(推荐):只有文件Owner拥有该文件的读写权限,其他用户没有权限操作该文件。

      • 公共读:文件Owner拥有该文件的读写权限,其他用户(包括匿名访问者)都可以对文件进行访问,这有可能造成您数据的外泄以及费用激增,请谨慎操作。

      • 公共读写:任何用户(包括匿名访问者)都可以对文件进行访问,并且向该文件写入数据。这有可能造成您数据的外泄以及费用激增,若被人恶意写入违法信息还可能会侵害您的合法权益。除特殊场景外,不建议您配置公共读写权限。

      有关文件ACL的更多信息,请参见设置Object ACL

      待上传文件

      选择您需要上传的文件或文件夹。

      您可以单击扫描文件扫描文件夹选择本地文件或文件夹,或者直接拖拽目标文件或文件夹到待上传文件区域。

      如果上传文件夹中包含了无需上传的文件,请单击目标文件右侧的移除将其移出文件列表。

      重要
      • 在未开启版本控制Bucket中上传文件时,如果上传的文件与已有文件同名,则覆盖已有文件。

      • 在已开启版本控制Bucket中上传文件时,如果上传的文件与已有文件同名,则上传文件将成为最新版本,已有文件将成为历史版本。

    2. 可选:设置文件存储类型、加密方式等高级选项。

      参数

      说明

      存储类型

      设置文件存储类型。

      • 继承Bucket:以Bucket存储类型为准。

      • 标准存储提供高可靠、高可用、高性能的对象存储服务,能够支持频繁的数据访问。适用于各种社交、分享类的图片、音视频应用、大型网站、大数据分析等业务场景。标准存储类型支持同城冗余ZRS(Zone-redundant storage)和本地冗余LRS(Locally redundant storage)两种数据冗余存储方式。

      • 低频访问存储提供高持久性、较低存储成本的对象存储服务。有最小计量单位(64 KB)和最低存储时间(30天)的要求。支持数据实时访问,访问数据时会产生数据取回费用,适用于较低访问频率(平均每月访问频率12次)的业务场景。低频访问存储支持同城冗余和本地冗余两种数据冗余存储方式。

      • 归档存储提供高持久性、极低存储成本的对象存储服务。有最小计量单位(64 KB)和最低存储时间(60天)要求。归档存储数据支持解冻(约1分钟)后访问或直接访问。解冻后访问会产生归档存储数据取回容量费用,直接访问会产生归档直读数据取回容量费用。归档存储适用于数据长期保存的业务场景,例如档案数据、医疗影像、科学资料、影视素材等。归档存储支持同城冗余和本地冗余两种数据冗余存储方式。

      • 冷归档存储提供高持久性、比归档存储的存储成本更低的对象存储服务。有最小计量单位(64 KB)和最低存储时间(180天)的要求。数据需解冻后访问,解冻时间根据数据大小和选择的解冻模式决定,解冻会产生数据取回费用以及取回请求费用。适用于需要超长时间存放的冷数据,例如因合规要求需要长期留存的数据、大数据及人工智能领域长期积累的原始数据、影视行业长期留存的媒体资源、在线教育行业的归档视频等业务场景。冷归档仅支持本地冗余的数据冗余存储方式。

      • 深度冷归档存储提供高持久性、比冷归档存储成本更低的对象存储服务。有最小计量单位(64 KB)和最低存储时间(180天)的要求。数据需解冻后访问,解冻时间根据数据大小和选择的解冻模式决定,解冻会产生数据取回费用以及取回请求费用。适用于需要超长时间存放的极冷数据,例如大数据及人工智能领域的原始数据的长期积累留存、媒体数据的长期保留、法规和合规性存档、磁带替换等业务场景。深度冷归档仅支持本地冗余的数据冗余存储方式。

      更多信息,请参见存储类型介绍

      服务端加密方式

      设置文件的服务端加密方式。

      • 继承Bucket:以Bucket的服务器端加密方式为准。

      • OSS完全托管:使用OSS托管的密钥进行加密。OSS会为每个Object使用不同的密钥进行加密,作为额外的保护,OSS会使用主密钥对加密密钥本身进行加密。

      • KMS:使用KMS默认托管的CMK或指定CMK ID进行加解密操作。KMS对应的加密密钥说明如下:

        • alias/acs/oss(CMK ID):使用默认托管的CMK生成不同的密钥来加密不同的Object,并且在Object被下载时自动解密。

        • alias/<cmkname>(CMK ID):使用指定的CMK生成不同的密钥来加密不同的Object,并将加密ObjectCMK ID记录到Object的元数据中,具有解密权限的用户下载Object时会自动解密。其中<cmkname>为创建密钥时配置的主密钥可选标识。

          使用指定的CMK ID前,您需要在KMS管理控制台创建一个与Bucket处于相同地域的普通密钥或外部密钥。具体操作,请参见创建密钥

      • 加密算法可选择AES256SM4加密算法。

      用户自定义元数据

      用于为Object添加描述信息。您可以添加多条自定义元数据(User Meta),但所有的自定义元数据总大小不能超过8 KB。添加自定义元数据时,要求参数以x-oss-meta-为前缀,并为参数赋值,例如x-oss-meta-location:hangzhou

    3. 单击上传文件

      此时,您可以在上传列表页签查看各个文件的上传进度。

使用图形化管理工具ossbrowser

  1. 安装ossbrowser 2.0,如已完成安装,请忽略此步骤。

  2. 登录ossbrowser 2.0,如已完成登录,请忽略此步骤。

  3. 单击目标Bucket名称。

  4. 单击上传,按需求上传本地文件或文件夹。

    说明

    文件默认继承BucketACL和存储类型。

    image

  5. 单击此处可查看上传进度。

    image

使用阿里云SDK

Java
Python
Go
Node.js
PHP
Browser.js
.NET
Android
iOS
C++
C
Ruby

以下仅列举了使用Java SDK进行文件上传的示例,更多简单上传场景的示例代码,如上传字符串、文件流、网络流等,请参见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;
import com.aliyun.oss.model.PutObjectRequest;
import com.aliyun.oss.model.PutObjectResult;
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";
        // 填写Object完整路径,完整路径中不能包含Bucket名称,例如exampledir/exampleobject.txt。
        String objectName = "exampledir/exampleobject.txt";
        // 填写本地文件的完整路径,例如D:\\localpath\\examplefile.txt。
        // 如果未指定本地路径,则默认从示例程序所属项目对应本地路径中上传文件。
        String filePath= "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 {
            // 创建PutObjectRequest对象。
            PutObjectRequest putObjectRequest = new PutObjectRequest(bucketName, objectName, new File(filePath));
            // 如果需要上传时设置存储类型和访问权限,请参考以下示例代码。
            // ObjectMetadata metadata = new ObjectMetadata();
            // metadata.setHeader(OSSHeaders.OSS_STORAGE_CLASS, StorageClass.Standard.toString());
            // metadata.setObjectAcl(CannedAccessControlList.Private);
            // putObjectRequest.setMetadata(metadata);
            
            // 上传文件。
            PutObjectResult result = 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();
            }
        }
    }
}

以下仅列举了使用Python SDK进行文件上传的示例,更多简单上传场景的示例代码,如上传字符串、网络流等,请参见Python简单上传

# -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider

# 从环境变量中获取访问凭证。运行本代码示例之前,请确保已设置环境变量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"
# 填写Bucket名称,例如examplebucket。
bucketName = "examplebucket"
# 创建Bucket实例,指定存储空间的名称和Region信息。
bucket = oss2.Bucket(auth, endpoint, bucketName, region=region)

# 本地文件的完整路径
local_file_path = 'D:\\localpath\\examplefile.txt'  

# 填写Object完整路径,完整路径中不能包含Bucket名称。例如exampleobject.txt。
objectName = 'exampleobject.txt'

# 使用put_object_from_file方法将本地文件上传至OSS
bucket.put_object_from_file(objectName, local_file_path)

以下仅列举了使用Go SDK进行文件上传的示例,更多简单上传场景的示例代码,如上传字符串、文件流、网络流等,请参见Go简单上传

package main

import (
	"context"
	"flag"
	"log"

	"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(&region, "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)

	// 填写要上传的本地文件路径和文件名称,例如 /Users/localpath/exampleobject.txt
	localFile := "/Users/localpath/exampleobject.txt"

	// 创建上传对象的请求
	putRequest := &oss.PutObjectRequest{
		Bucket:       oss.Ptr(bucketName),      // 存储空间名称
		Key:          oss.Ptr(objectName),      // 对象名称
		StorageClass: oss.StorageClassStandard, // 指定对象的存储类型为标准存储
		Acl:          oss.ObjectACLPrivate,     // 指定对象的访问权限为私有访问
		Metadata: map[string]string{
			"yourMetadataKey1": "yourMetadataValue1", // 设置对象的元数据
		},
	}

	// 执行上传对象的请求
	result, err := client.PutObjectFromFile(context.TODO(), putRequest, localFile)
	if err != nil {
		log.Fatalf("failed to put object from file %v", err)
	}

	// 打印上传对象的结果
	log.Printf("put object from file result:%#v\n", result)
}

以下仅列举了使用Node.js SDK进行文件上传的示例,更多简单上传场景的示例代码,如上传字符串、文件流、网络流等,请参见上传字符串流式上传

const OSS = require('ali-oss')
const path=require("path")

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',
});

// 自定义请求头
const headers = {
  // 指定Object的存储类型。
  'x-oss-storage-class': 'Standard',
  // 指定Object的访问权限。
  'x-oss-object-acl': 'private',
  // 通过文件URL访问文件时,指定以附件形式下载文件,下载后的文件名称定义为example.txt。
  'Content-Disposition': 'attachment; filename="example.txt"',
  // 设置Object的标签,可同时设置多个标签。
  'x-oss-tagging': 'Tag1=1&Tag2=2',
  // 指定PutObject操作时是否覆盖同名目标Object。此处设置为true,表示禁止覆盖同名Object。
  'x-oss-forbid-overwrite': 'true',
};

async function put () {
  try {
    // 填写OSS文件完整路径和本地文件的完整路径。OSS文件完整路径中不能包含Bucket名称。
    // 如果本地文件的完整路径中未指定本地路径,则默认从示例程序所属项目对应本地路径中上传文件。
    const result = await client.put('exampleobject.txt', path.normalize('D:\\localpath\\examplefile.txt')
    // 自定义headers
    ,{headers}
    );
    console.log(result);
  } catch (e) {
    console.log(e);
  }
}

put();

以下仅列举了使用PHP SDK进行文件上传的示例,更多简单上传场景的示例代码,如上传字符串等,请参见PHP简单上传

<?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;
use OSS\Core\OssException;

// 从环境变量中获取访问凭证。运行本代码示例之前,请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
$provider = new EnvironmentVariableCredentialsProvider();
// yourEndpoint填写Bucket所在地域对应的Endpoint。以华东1(杭州)为例,Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。
$endpoint = "yourEndpoint";
// 填写Bucket名称,例如examplebucket。
$bucket= "examplebucket";
// 填写Object完整路径,例如exampledir/exampleobject.txt。Object完整路径中不能包含Bucket名称。
$object = "exampledir/exampleobject.txt";
// 填写本地文件的完整路径,例如D:\\localpath\\examplefile.txt。如果未指定本地路径,则默认从示例程序所属项目对应本地路径中上传文件。
$filePath = "D:\\localpath\\examplefile.txt";

try{
    $config = array(
        "provider" => $provider,
        "endpoint" => $endpoint,
        "signatureVersion" => OssClient::OSS_SIGNATURE_VERSION_V4,
        "region"=> "cn-hangzhou"
    );
    $ossClient = new OssClient($config);

    $ossClient->uploadFile($bucket, $object, $filePath);
} catch(OssException $e) {
    printf(__FUNCTION__ . ": FAILED\n");
    printf($e->getMessage() . "\n");
    return;
}
print(__FUNCTION__ . "OK" . "\n");

有关Browser.js SDK的更多信息,请参见Browser.js简单上传

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Document</title>
  </head>
  <body>
    <input id="file" type="file" />
    <button id="upload">上传</button>
    <script src="https://gosspublic.alicdn.com/aliyun-oss-sdk-6.18.0.min.js"></script>
    <script>
      const client = new OSS({
        // yourRegion填写Bucket所在地域。以华东1(杭州)为例,yourRegion填写为oss-cn-hangzhou。
        region: "yourRegion",
        authorizationV4: true,
        // 从STS服务获取的临时访问密钥(AccessKey ID和AccessKey Secret)。
        accessKeyId: "yourAccessKeyId",
        accessKeySecret: "yourAccessKeySecret",
        // 从STS服务获取的安全令牌(SecurityToken)。
        stsToken: "yourSecurityToken",
        // 填写Bucket名称。
        bucket: "examplebucket",
      });

      // 从输入框获取file对象,例如<input type="file" id="file" />。
      let data;
      // 创建并填写Blob数据。
      //const data = new Blob(['Hello OSS']);
      // 创建并填写OSS Buffer内容。
      //const data = new OSS.Buffer(['Hello OSS']);

      const upload = document.getElementById("upload");

      async function putObject(data) {
        try {
          // 填写Object完整路径。Object完整路径中不能包含Bucket名称。
          // 您可以通过自定义文件名(例如exampleobject.txt)或文件完整路径(例如exampledir/exampleobject.txt)的形式实现将数据上传到当前Bucket或Bucket中的指定目录。
          // data对象可以自定义为file对象、Blob数据或者OSS Buffer。
          const options = {
            meta: { temp: "demo" },
            mime: "json",
            headers: { "Content-Type": "text/plain" },
          };
          const result = await client.put("examplefile.txt", data, options);
          console.log(result);
        } catch (e) {
          console.log(e);
        }
      }

      upload.addEventListener("click", () => {
        const data = file.files[0];
        putObject(data);
      });
    </script>
  </body>
</html>

以下仅列举了使用.NET SDK进行文件上传的示例,更多简单上传场景的示例代码,如上传字符串,请参见.NET简单上传

using Aliyun.OSS;
using Aliyun.OSS.Common;

// yourEndpoint填写Bucket所在地域对应的Endpoint。以华东1(杭州)为例,Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。
var endpoint = "yourEndpoint";
// 从环境变量中获取访问凭证。运行本代码示例之前,请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
var accessKeyId = Environment.GetEnvironmentVariable("OSS_ACCESS_KEY_ID");
var accessKeySecret = Environment.GetEnvironmentVariable("OSS_ACCESS_KEY_SECRET");
// 填写Bucket名称,例如examplebucket。
var bucketName = "examplebucket";
// 填写Object完整路径,完整路径中不能包含Bucket名称,例如exampledir/exampleobject.txt。
var objectName = "exampledir/exampleobject.txt";
// 填写本地文件的完整路径。如果未指定本地路径,则默认从示例程序所属项目对应本地路径中上传文件。
var localFilename = "D:\\localpath\\examplefile.txt";
// 填写Bucket所在地域对应的Region。以华东1(杭州)为例,Region填写为cn-hangzhou。
const string region = "cn-hangzhou";

// 创建ClientConfiguration实例,按照您的需要修改默认参数。
var conf = new ClientConfiguration();

// 设置v4签名。
conf.SignatureVersion = SignatureVersion.V4;

// 创建OssClient实例。
var client = new OssClient(endpoint, accessKeyId, accessKeySecret, conf);
client.SetRegion(region);
try
{
    // 上传文件。
    client.PutObject(bucketName, objectName, localFilename);
    Console.WriteLine("Put object succeeded");
}
catch (Exception ex)
{
    Console.WriteLine("Put object failed, {0}", ex.Message);
}

以下仅列举了使用Android SDK进行文件上传的示例,更多简单上传场景的示例代码,如上传二进制byte[]数组,请参见Android简单上传

// 构造上传请求。
// 依次填写Bucket名称(例如examplebucket)、Object完整路径(例如exampledir/exampleobject.txt)和本地文件完整路径(例如/storage/emulated/0/oss/examplefile.txt)。
// Object完整路径中不能包含Bucket名称。
PutObjectRequest put = new PutObjectRequest("examplebucket", "exampledir/exampleobject.txt", "/storage/emulated/0/oss/examplefile.txt");

// 设置文件元数据为可选操作。
 ObjectMetadata metadata = new ObjectMetadata();
// metadata.setContentType("application/octet-stream"); // 设置content-type。
// metadata.setContentMD5(BinaryUtil.calculateBase64Md5(uploadFilePath)); // 校验MD5。
// 设置Object的访问权限为私有。
metadata.setHeader("x-oss-object-acl", "private");
// 设置Object的存储类型为标准存储。
metadata.setHeader("x-oss-storage-class", "Standard");
// 设置禁止覆盖同名Object。
// metadata.setHeader("x-oss-forbid-overwrite", "true");
// 指定Object的对象标签,可同时设置多个标签。
// metadata.setHeader("x-oss-tagging", "a:1");
// 指定OSS创建目标Object时使用的服务器端加密算法 。
// metadata.setHeader("x-oss-server-side-encryption", "AES256");
// 表示KMS托管的用户主密钥,该参数仅在x-oss-server-side-encryption为KMS时有效。
// metadata.setHeader("x-oss-server-side-encryption-key-id", "9468da86-3509-4f8d-a61e-6eab1eac****");

put.setMetadata(metadata);

try {
    PutObjectResult putResult = oss.putObject(put);

    Log.d("PutObject", "UploadSuccess");
    Log.d("ETag", putResult.getETag());
    Log.d("RequestId", putResult.getRequestId());
} catch (ClientException e) {
    // 客户端异常,例如网络异常等。
    e.printStackTrace();
} catch (ServiceException e) {
    // 服务端异常。
    Log.e("RequestId", e.getRequestId());
    Log.e("ErrorCode", e.getErrorCode());
    Log.e("HostId", e.getHostId());
    Log.e("RawMessage", e.getRawMessage());
}

有关iOS SDK的更多信息,请参见iOS简单上传

OSSPutObjectRequest * put = [OSSPutObjectRequest new];

// 填写Bucket名称,例如examplebucket。
put.bucketName = @"examplebucket";
// 填写文件完整路径,例如exampledir/exampleobject.txt。Object完整路径中不能包含Bucket名称。
put.objectKey = @"exampledir/exampleobject.txt";
put.uploadingFileURL = [NSURL fileURLWithPath:@"<filePath>"];
// put.uploadingData = <NSData *>; // 直接上传NSData。

// (可选)设置上传进度。
put.uploadProgress = ^(int64_t bytesSent, int64_t totalByteSent, int64_t totalBytesExpectedToSend) {
    // 指定当前上传长度、当前已经上传总长度、待上传的总长度。
    NSLog(@"%lld, %lld, %lld", bytesSent, totalByteSent, totalBytesExpectedToSend);
};
// 配置可选字段。
// put.contentType = @"application/octet-stream";
// 设置Content-MD5。
// put.contentMd5 = @"eB5eJF1ptWaXm4bijSPyxw==";
// 设置Object的编码方式。
// put.contentEncoding = @"identity";
// 设置Object的展示形式。
// put.contentDisposition = @"attachment";
// 可以在上传文件时设置文件元数据或者HTTP头部。
// NSMutableDictionary *meta = [NSMutableDictionary dictionary];
// 设置文件元数据。
// [meta setObject:@"value" forKey:@"x-oss-meta-name1"];
// 设置Object的访问权限为私有。
// [meta setObject:@"private" forKey:@"x-oss-object-acl"];
// 设置Object的归档类型为标准存储。
// [meta setObject:@"Standard" forKey:@"x-oss-storage-class"];
// 设置覆盖同名目标Object。
// [meta setObject:@"true" forKey:@"x-oss-forbid-overwrite"];
// 指定Object的对象标签,可同时设置多个标签。
// [meta setObject:@"a:1" forKey:@"x-oss-tagging"];
// 指定OSS创建目标Object时使用的服务器端加密算法。
// [meta setObject:@"AES256" forKey:@"x-oss-server-side-encryption"];
// 表示KMS托管的用户主密钥,该参数仅在x-oss-server-side-encryption为KMS时有效。
// [meta setObject:@"9468da86-3509-4f8d-a61e-6eab1eac****" forKey:@"x-oss-server-side-encryption-key-id"];
// put.objectMeta = meta;
OSSTask * putTask = [client putObject:put];

[putTask continueWithBlock:^id(OSSTask *task) {
    if (!task.error) {
        NSLog(@"upload object success!");
    } else {
        NSLog(@"upload object failed, error: %@" , task.error);
    }
    return nil;
}];
// waitUntilFinished会阻塞当前线程,但是不会阻塞上传任务进程。
// [putTask waitUntilFinished];
// [put cancel];

以下仅列举了使用C++ SDK进行文件上传的示例,更多简单上传场景的示例代码,如上传字符串,请参见C++简单上传

#include <alibabacloud/oss/OssClient.h>
#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";

    /* 初始化网络等资源。*/
    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);
    /* 填写本地文件完整路径,例如D:\\localpath\\examplefile.txt,其中localpath为本地文件examplefile.txt所在本地路径。*/
    std::shared_ptr<std::iostream> content = std::make_shared<std::fstream>("D:\\localpath\\examplefile.txt", std::ios::in | std::ios::binary);
    PutObjectRequest request(BucketName, ObjectName, content);

    /*(可选)请参见如下示例设置访问权限ACL为私有(private)以及存储类型为标准存储(Standard)。*/
    //request.MetaData().addHeader("x-oss-object-acl", "private");
    //request.MetaData().addHeader("x-oss-storage-class", "Standard");

    auto outcome = client.PutObject(request);

    if (!outcome.isSuccess()) {
        /* 异常处理。*/
        std::cout << "PutObject fail" <<
        ",code:" << outcome.error().Code() <<
        ",message:" << outcome.error().Message() <<
        ",requestId:" << outcome.error().RequestId() << std::endl;
        return -1;
    }

    /* 释放网络等资源。*/
    ShutdownSdk();
        return 0;
}

以下仅列举了使用C SDK进行文件上传的示例,更多简单上传场景的示例代码,如上传字符串,请参见C简单上传

#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 *object_content = "More than just cloud.";
/* 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_list_t buffer;
    aos_buf_t *content = NULL;
    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_list_init(&buffer);
    content = aos_buf_pack(oss_client_options->pool, object_content, strlen(object_content));
    aos_list_add_tail(&content->node, &buffer);
    /* 上传文件。*/
    resp_status = oss_put_object_from_buffer(oss_client_options, &bucket, &object, &buffer, headers, &resp_headers);
    /* 判断上传是否成功。*/
    if (aos_status_is_ok(resp_status)) {
        printf("put object from buffer succeeded\n");
    } else {
        printf("put object from buffer failed\n");      
    }
    /* 释放内存池,相当于释放了请求过程中各资源分配的内存。*/
    aos_pool_destroy(pool);
    /* 释放之前分配的全局资源。*/
    aos_http_io_deinitialize();
    return 0;
}

以下仅列举了使用Ruby SDK进行文件上传的示例,更多简单上传场景的示例代码,如流式上传,请参见Ruby流式上传

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')
# 上传文件。
bucket.put_object('exampleobject.txt', :file => 'D:\\localpath\\examplefile.txt')

使用命令行工具ossutil

您可以使用命令行工具ossutil来上传文件,ossutil的安装请参见安装ossutil

以下命令用于将本地文件上传到存储空间examplebucket中。

ossutil api put-object --bucket examplebucket --key exampleobject --body file://uploadFile

关于该命令的更多信息,请参见put-object

相关API

以上操作方式底层基于API实现,如果您的程序自定义要求较高,您可以直接发起REST API请求。直接发起REST API请求需要手动编写代码计算签名。更多信息,请参见PutObject

权限说明

阿里云账号默认拥有全部权限。阿里云账号下的RAM用户或RAM角色默认没有任何权限,需要阿里云账号或账号管理员通过RAM PolicyBucket Policy授予操作权限。

API

Action

说明

API

Action

说明

PutObject

oss:PutObject

上传Object。

oss:PutObjectTagging

上传Object时,如果通过x-oss-tagging指定Object的标签,则需要此操作的权限。

kms:GenerateDataKey

上传Object时,如果通过x-oss-server-side-encryption指定服务器端的加密方式为KMS或者Bucket开启了KMS方式的服务端加密,则需要这两个操作的权限。

kms:Decrypt

计费说明

通过简单上传方式将文件上传到OSS,会产生以下计费项。有关计费项的定价详情,请参见OSS产品定价

API

计费项

说明

API

计费项

说明

PutObject

PUT类型请求

根据成功的请求次数计算请求费用。

存储费用

根据Object的存储类型、大小和时长收取存储费用。

了解更多

上传过程管理

  • 上传进度监控:如果需要监控上传进度并展示进度条,请参见上传进度条

  • 上传回调:在文件上传后,您可以向指定应用服务器发起回调请求,请参见上传回调

上传后对文件进行处理

  • 图片处理:对上传的图片进行压缩、添加自定义样式、获取图片大小信息等操作,请参见图片处理

  • 媒体处理:对上传的图片或者视频等进行文字识别、字幕提取、视频转码、生成视频封面等处理,请参见媒体处理

  • 文档预览和编辑:如果您希望对上传的PDF、PPT、Word等格式的文档进行在线预览或在线编辑,请参见WebOffice预览和协作编辑

ECI中访问OSS数据

使用Hadoop、Spark 等批处理作业时,可以将 OSS 作为存储后端。上传文件后,您可以在ECI中直接访问OSS数据。更多信息,请参见ECI中访问OSS数据

客户端直传上传文件

客户端直传相比服务端代理上传,可以避免中转,提升上传速度并减少服务器负担,推荐使用客户端直传的方式将文件上传到 OSS。更多信息,请参见客户端直传

常见问题

如何上传超过5GB的大文件

简单上传的文件大小限制为5GB。对于超过5GB的文件,请使用分片上传

如何实现批量上传?

OSS控制台和ossbrowser仅支持批量上传指定目录下的所有文件,不支持文件筛选。如果需要筛选文件,建议使用ossutil。

  • 使用OSS控制台

    单击目标Bucket名称进入Bucket,单击上传文件 > 扫描文件夹,选中待上传的文件夹,最后单击上传文件即可。

    image

  • 使用ossbrowser

    单击目标Bucket名称进入Bucket,单击页面上方上传按钮,在下拉列表框中选择上传文件夹。

    image

  • 使用ossutil工具

    使用ossutil工具的cp命令,结合-r(--recursive)选项,可批量上传文件到OSS,更多信息请参见cp(上传文件)

    • 将本地文件夹localfolder中的文件上传至examplebucket中的desfolder文件夹下。

      ossutil cp -r D:/localpath/localfolder/ oss://examplebucket/desfolder/
    • 批量上传符合条件的文件。

      上传所有文件格式为TXT的文件。

      ossutil cp -r D:/localpath/localfolder/ oss://examplebucket/desfolder/ --include "*.txt"
  • ZIP包解压

    使用ZIP包解压功能,先配置解压规则,然后将多个文件打包成ZIP包上传到OSS。此时将触发函数计算进行解压并将解压后的文件传回OSS,实现批量上传。详情请参见ZIP包解压

如何将OSS资源分享给第三方临时访问?

OSS 提供两种方式供第三方临时访问:

  • 签名URL

    如果您仅需要第三方对指定文件进行临时上传或下载,签名URL便可满足您的需求,详细使用方法请参见使用签名URL上传文件使用签名URL下载文件

  • STS临时访问凭证

    如果您希望第三方对OSS的操作不只局限于上传、下载,而是可以执行例如:列举文件、拷贝文件等更多OSS资源的管理操作,建议您了解并使用STS临时访问凭证,详情请参见使用STS临时访问凭证访问OSS

如何使用自定义域名进行简单上传?

在使用SDK创建OssClient时,请改用自定义域名,具体操作可参考步骤三:使用自定义域名SDK。请注意,各语言的配置中,cname参数需设置为true。

如何防止文件被意外覆盖?

简单上传默认会覆盖同名Object,您可以选择以下任意方式防止Object被意外覆盖。

  • 开启版本控制功能

    开启版本控制功能后,被覆盖的Object会以历史版本的形式保存下来。您可以随时恢复历史版本Object。更多信息,请参见版本控制介绍

  • 在上传请求中携带禁止覆盖同名Object的参数

    在上传请求的Header中携带参数x-oss-forbid-overwrite,并指定其值为true。当您上传的ObjectOSS中存在同名Object时,该Object会上传失败,并返回FileAlreadyExists错误。当不携带此参数或此参数的值为false时,同名Object会被覆盖。

如何降低PUT类请求费用?

如果要上传的文件数量较多,直接指定上传的文件类型为深度冷归档类型会造成较高的PUT类请求费用。建议您先将文件的存储类型指定为标准存储进行上传,然后通过生命周期规则将其转储为深度冷归档类型,从而降低PUT类请求费用。

多个用户上传同名(含路径)的文件,OSS会如何保留?

这取决于是否开启了版本控制

image

  • 在版本控制未开启或暂停时:若有多个用户上传同名Object,后上传完成的Object会覆盖前一个,并只保留最后上传完成的Object。例如,用户A在用户B之后完成上传,最终将保留用户A上传的Object。

  • 版本控制开启时:每次上传同名Object都会创建新版本,并用版本ID(Version ID)标识。OSS根据上传的开始时间确定最新版本。例如,用户B在用户A之后开始上传,则用户B上传的Object将被标记为最新版本。

如何调优上传性能?

如果您在上传大量Object时,在命名上使用了顺序前缀(如时间戳或字母顺序),可能会出现大量Object索引集中存储于存储空间中某个特定分区的情况,进而导致请求速率下降。建议您在上传大量Object时,不要使用顺序前缀的Object名称,而是将顺序前缀改为随机性前缀。具体操作,请参见OSS性能最佳实践

  • 本页导读 (1)
  • 前提条件
  • 操作方式
  • 使用OSS控制台
  • 使用图形化管理工具ossbrowser
  • 使用阿里云SDK
  • 使用命令行工具ossutil
  • 相关API
  • 权限说明
  • 计费说明
  • 了解更多
  • 上传过程管理
  • 上传后对文件进行处理
  • 在ECI中访问OSS数据
  • 客户端直传上传文件
  • 常见问题
  • 如何上传超过5GB的大文件
  • 如何实现批量上传?
  • 如何将OSS资源分享给第三方临时访问?
  • 如何使用自定义域名进行简单上传?
  • 如何防止文件被意外覆盖?
  • 如何降低PUT类请求费用?
  • 多个用户上传同名(含路径)的文件,OSS会如何保留?
  • 如何调优上传性能?
AI助理

点击开启售前

在线咨询服务

你好,我是AI助理

可以解答问题、推荐解决方案等