对象存储OSS提供了兼容Amazon S3的API。当您将数据从Amazon S3迁移到OSS后,只需简单的配置修改,即可让您的客户端应用轻松兼容OSS服务。本文主要介绍如何通过不同开发平台的S3 SDK完成初始化配置,然后使用S3 SDK接口访问OSS资源。

前提条件

  • 已创建RAM用户并获取访问密钥(AccessKey)。具体操作,请参见创建RAM用户
  • 为已创建的RAM用户授予系统权限或自定义权限。
    • 系统权限

      您可以为RAM用户授予管理OSS的权限AliyunOSSFullAccess或者只读访问OSS的权限AliyunOSSReadOnlyAccess

    • 自定义权限

      您还可以结合业务场景,通过创建自定义权限实现OSS的细粒度权限控制。更多信息,请参见RAM Policy常见示例

  • 已创建集成了S3 SDK且能正常运行的客户端应用。

背景信息

以华东1(杭州)地域为例,S3兼容的外网Endpoint格式为 s3.oss-cn-hangzhou.aliyuncs.com,S3兼容的内网Endpoint格式为 s3.oss-cn-hangzhou-internal.aliyuncs.com。如需使用其他地域,请对应替换Endpoint中的Region ID。关于Region和Endpoint的对应关系,请参见 访问域名和数据中心

Java SDK

  • 1.x版本

    以AWS Java SDK 1.11.609版本为例,介绍通过代码完成初始化配置的方法。

    • 通过代码配置AccessKey
      AmazonS3 s3Client = AmazonS3ClientBuilder.standard()
              .withCredentials(new AWSStaticCredentialsProvider(new BasicAWSCredentials(accessKeyId, accessKeySecret)))
              .withEndpointConfiguration(new AwsClientBuilder.EndpointConfiguration(
                      "https://oss-cn-hangzhou.aliyuncs.com",
                      ""))
              .withPathStyleAccessEnabled(false)
              .withChunkedEncodingDisabled(true)
              .build();
    • 通过配置文件读取AccessKey
      1. ~/.aws/credentials路径下的证书文件中配置OSS访问密钥。
        [default]
        aws_access_key_id = [OSS_AccessKeyId]
        aws_secret_access_key = [OSS_AccessKeySecret]
      2. 设置Endpoint。
        AmazonS3 s3Client = AmazonS3ClientBuilder.standard()
                .withEndpointConfiguration(new AwsClientBuilder.EndpointConfiguration(
                        "https://oss-cn-hangzhou.aliyuncs.com",
                        ""))
                .withPathStyleAccessEnabled(false)
                .withChunkedEncodingDisabled(true)
                .build();
  • 2.x版本

    以下以AWS Java SDK 2.17.201版本为例,介绍通过代码完成初始化配置的方法。

    通过代码配置AccessKey
    S3Client s3 = S3Client.builder()
            .credentialsProvider(StaticCredentialsProvider.create(AwsBasicCredentials.create(accessKeyId, accessKeySecret)))
            .region(Region.AWS_GLOBAL)
            .endpointOverride(URI.create("https://s3.oss-cn-hangzhou.aliyuncs.com"))
            .serviceConfiguration(S3Configuration.builder()
                    .pathStyleAccessEnabled(false)
                    .chunkedEncodingEnabled(false)
                    .build())
            .build();

Python SDK

以下以AWS Python SDK 1.9.205版本为例,介绍通过代码完成初始化配置的方法。

import boto3
from botocore.config import Config
endpoint = 'https://oss-cn-hangzhou.aliyuncs.com'
access_key_id = 'OSS_AccessKeyId'
secret_access_key = 'OSS_AccessKeySecret'

s3 = boto3.client(
    's3',
    aws_access_key_id=access_key_id,
    aws_secret_access_key=secret_access_key,
    endpoint_url=endpoint,
    config=Config(s3={"addressing_style": "virtual", "signature_version": 's3v4'}))

PHP SDK

以下以AWS PHP SDK 3.109.3版本为例,介绍初始化配置的操作步骤。

  1. 修改AWS配置和证书文件。
    以下以Linux系统为例:
    1. ~/.aws/config路径下的配置文件中添加以下配置信息:
      [default]
      s3 =
      addressing_style = virtual
    2. ~/.aws/credentials路径下的证书文件中配置OSS访问密钥。
      [default]
      aws_access_key_id = [OSS_AccessKeyId]
      aws_secret_access_key = [OSS_AccessKeySecret]
  2. 设置Endpoint。
    $S3Client = new S3Client([
      'region'          => 'oss-cn-hangzhou',
      'version'         => '2006-03-01',
      'endpoint'        => 'https://oss-cn-hangzhou.aliyuncs.com'
    ]);

Node.js SDK

以AWS Node.js SDK 2.509.0版本为例,初始化实例时设置OSS AccessKey和Endpoint的示例代码如下:

var AWS = require('aws-sdk');

AWS.config.update({
    accessKeyId: "OSS_AccessKeyId",
    secretAccessKey: "OSS_AccessKeySecret",
    region: "oss-cn-hangzhou",
    endpoint: 'https://oss-cn-hangzhou.aliyuncs.com',
});

s3 = new AWS.S3({apiVersion: '2006-03-01'});

.NET SDK

以AWS .NET SDK 3.3.104.12版本为例,初始化实例时设置OSS AccessKey和Endpoint的示例代码如下:

string sAccessKeyId = "OSS_AccessKeyId";
string sAccessKeySecret = "OSS_AccessKeySecret";
string endpoint = "https://oss-cn-hangzhou.aliyuncs.com";

var config = new AmazonS3Config() { ServiceURL = endpoint };
var client = new AmazonS3Client(sAccessKeyId, sAccessKeySecret, config);

Android SDK

重要 移动终端是一个不受信任的环境,将长期有效的AccessKey直接保存在移动终端用来加签请求,存在极高的风险。建议您通过STS方式获取临时访问凭证。具体步骤,请参见 使用STS临时访问凭证访问OSS

以AWS Android SDK 2.14.2版本为例,初始化实例时设置临时访问凭证和Endpoint的示例代码如下:

AmazonS3Client s3 = new AmazonS3Client(new AWSCredentialsProvider() {
    @Override
    public AWSCredentials getCredentials() {
         // 获取STS返回的临时访问凭证。
        return new BasicSessionCredentials(
                "StsToken.AccessKeyId", "StsToken.SecretKeyId", "StsToken.SecurityToken"
        );
    }

    @Override
    public void refresh() {
        //
    }
});
// 设置Endpoint。
s3.setEndpoint("oss-cn-hangzhou.aliyuncs.com");

iOS SDK

重要 移动终端是一个不受信任的环境,将长期有效的AccessKey直接保存在移动终端用来加签请求,存在极高的风险。建议您通过STS方式获取临时访问凭证。具体步骤,请参见 使用STS临时访问凭证访问OSS

以AWS iOS SDK 2.10.2版本为例,介绍初始化配置的操作步骤。

  1. 实现AWSCredentialsProvider协议。
    -(AWSTask<AWSCredentials *> *)credentials{
        // 获取STS返回的临时访问凭证。
        AWSCredentials *credential = [[AWSCredentials alloc]initWithAccessKey:@"StsToken.AccessKeyId" secretKey:@"StsToken.SecretKeyId" sessionKey:@"StsToken.SecurityToken" expiration:[NSDate dateWithTimeIntervalSince1970:1565770577]];
    
        return [AWSTask taskWithResult:credential];
    
    }
    
    - (void)invalidateCachedTemporaryCredentials{
    
    }
  2. 初始化实例。
    NSURL* bucketURL = [NSURL URLWithString:@"https://oss-cn-hangzhou.aliyuncs.com"];
    
    AWSEndpoint* endpoint = [[AWSEndpoint alloc] initWithRegion:AWSRegionUnknown service:AWSServiceS3 URL:bucketURL];
    AWSServiceConfiguration* configuration = [[AWSServiceConfiguration alloc]
        initWithRegion:AWSRegionUSEast2 endpoint:endpoint
        credentialsProvider:[MyCredentialProvider new]];
    
    [[AWSServiceManager defaultServiceManager] setDefaultServiceConfiguration:configuration];

Go SDK

  • 1.x版本

    以AWS Go SDK 1.21.9版本为例,介绍初始化配置的操作步骤。

    1. 根据AccessKey创建Session。
      func newSession() (*session.Session, error) {
          creds := credentials.NewStaticCredentials("OSS_AccessKeyId", "OSS_AccessKeySecret", "")
          region := "oss-cn-hangzhou"
          endpoint := "https://oss-cn-hangzhou.aliyuncs.com"
          config := &aws.Config{
              Region:           aws.String(region),
              Endpoint:         &endpoint,
              S3ForcePathStyle: aws.Bool(false),
              Credentials:      creds,
              // DisableSSL:       &disableSSL,
          }
          return session.NewSession(config)
      }
    2. 根据Session创建Server发起请求。

      以下代码用于将本地文件examplefile.txt上传到examplebucket中exampledir目录下的exampleobject.txt文件。

      sess, _ := newSession()
      service := s3.New(sess)
      
      // 填写本地文件的完整路径。
      fp, _ := os.Open("D:\\localpath\\examplefile.txt")
      defer fp.Close()
      
      ctx, cancel := context.WithTimeout(context.Background(), time.Duration(30)*time.Second)
      defer cancel()
      
      service.PutObjectWithContext(ctx, &s3.PutObjectInput{
          // 填写Bucket名称。
          Bucket: aws.String("examplebucket"),
          // 填写Object完整路径,完整路径中不能包含Bucket名称。
          Key:    aws.String("exampledir/exampleobject.txt"),
          Body:   fp,
      })
  • 2.x版本

    以下以AWS Go SDK 2.x版本为例,介绍初始化配置的操作步骤。

    package main
    
    import (
        "context"
        "fmt"
        "github.com/aws/aws-sdk-go-v2/aws"
        "github.com/aws/aws-sdk-go-v2/config"
        "github.com/aws/aws-sdk-go-v2/credentials"
        "github.com/aws/aws-sdk-go-v2/feature/s3/manager"
        "github.com/aws/aws-sdk-go-v2/service/s3"
        "log"
        "os"
    )
    func main() {
        // 填写Bucket名称。
        bucketName := "examplebucket"
        // 填写Object完整路径,完整路径中不能包含Bucket名称。
        fileName := "exampledir/exampleobject.txt"
        customResolver := aws.EndpointResolverWithOptionsFunc(func(service, region string, options ...interface{}) (aws.Endpoint, error) {
            return aws.Endpoint{
                PartitionID:   "oss",
                URL:           "https://oss-cn-hangzhou.aliyuncs.com",
                SigningRegion: "cn-hangzhou",
            }, nil
        })
        creds := credentials.NewStaticCredentialsProvider("OSS_AccessKeyId", "OSS_AccessKeySecret", "")
        cfg, err := config.LoadDefaultConfig(context.TODO(), config.WithCredentialsProvider(creds), config.WithEndpointResolverWithOptions(customResolver))
        if err != nil {
            log.Printf("error: %v", err)
            return
        }
        awsS3Client := s3.NewFromConfig(cfg)
    
        fp, _ := os.Open(fileName)
        defer fp.Close()
    
        uploader := manager.NewUploader(awsS3Client)
        result, err := uploader.Upload(context.TODO(), &s3.PutObjectInput{
            Bucket: aws.String(bucketName),
            Key:    aws.String(fileName),
            Body:   fp,
        })
        if err != nil {
            log.Printf("error: %v", err)
            return
        }
        fmt.Printf("%#v\n", result)
    
    }

C++ SDK

以下以AWS C++ SDK 1.7.68版本为例,介绍初始化配置的操作步骤。

  1. 修改AWS配置和证书文件。
    以下以Linux系统为例:
    1. ~/.aws/config路径下的配置文件中添加以下配置信息:
      [default]
      s3 =
      addressing_style = virtual
    2. ~/.aws/credentials路径下的证书文件中配置OSS访问密钥。
      [default]
      aws_access_key_id = [OSS_AccessKeyId]
      aws_secret_access_key = [OSS_AccessKeySecret]
  2. 设置Endpoint。
    Aws::Client::ClientConfiguration awsCC;
    awsCC.scheme = Aws::Http::Scheme::HTTP;
    awsCC.region = "oss-cn-hangzhou";
    awsCC.endpointOverride = "oss-cn-hangzhou.aliyuncs.com";
    Aws::S3::S3Client s3_client(awsCC);