对象存储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且能正常运行的客户端应用。
使用限制
仅支持使用Amazon S3 SDK兼容的标准内外网域名访问公共云OSS有地域属性的Bucket。
背景信息
以中国香港地域为例,S3兼容的外网Endpoint格式为s3.oss-cn-hongkong.aliyuncs.com
,S3兼容的内网Endpoint格式为s3.oss-cn-hongkong-internal.aliyuncs.com
。如需使用其他地域,请对应替换Endpoint中的Region ID。关于Region和Endpoint的对应关系,请参见访问域名和数据中心。
Java SDK
1.x版本
以AWS Java SDK 1.11.609版本为例,介绍完成初始化实例的方法。
通过代码读取临时访问凭证的方式完成初始化
// 通过环境变量传递临时访问凭证信息。 String accessKeyId = System.getenv().get("OSS_AccessKeyId");; String accessKeySecret = System.getenv().get("OSS_AccessKeySecret");; String sessionToken = System.getenv().get("OSS_SessionToken");; AmazonS3 s3Client = AmazonS3ClientBuilder.standard() .withCredentials(new AWSStaticCredentialsProvider(new BasicSessionCredentials(accessKeyId, accessKeySecret, sessionToken))) .withEndpointConfiguration(new AwsClientBuilder.EndpointConfiguration( "https://oss-cn-hongkong.aliyuncs.com", "")) .withPathStyleAccessEnabled(false) .withChunkedEncodingDisabled(true) .build();
通过配置文件读取临时访问凭证的方式完成初始化
在~/.aws/credentials路径下的证书文件中配置临时访问凭证。
[default] aws_access_key_id = [OSS_AccessKeyId] aws_secret_access_key = [OSS_AccessKeySecret] aws_secret_sessiontoken = [OSS_SessionToken]
初始化实例。
AmazonS3 s3Client = AmazonS3ClientBuilder.standard() .withEndpointConfiguration(new AwsClientBuilder.EndpointConfiguration( "https://oss-cn-hongkong.aliyuncs.com", "")) .withPathStyleAccessEnabled(false) .withChunkedEncodingDisabled(true) .build();
2.x版本
以下以AWS Java SDK 2.17.201版本为例,介绍通过代码完成初始化实例的方法。
// 通过环境变量传递临时访问凭证信息。 String accessKeyId = System.getenv().get("OSS_AccessKeyId");; String accessKeySecret = System.getenv().get("OSS_AccessKeySecret");; String sessionToken = System.getenv().get("OSS_SessionToken");; S3Client s3 = S3Client.builder() .credentialsProvider(StaticCredentialsProvider.create(AwsSessionCredentials.create(accessKeyId, accessKeySecret, sessionToken))) .region(Region.AWS_GLOBAL) .endpointOverride(URI.create("http://s3.oss-us-west-1.aliyuncs.com")) .serviceConfiguration(S3Configuration.builder() .pathStyleAccessEnabled(false) .chunkedEncodingEnabled(false) .build()) .build();
Python SDK
以下以AWS Python SDK 1.9.205版本为例,介绍通过代码完成初始化实例的方法。
import boto3
import os
from botocore.config import Config
endpoint = 'https://oss-cn-hongkong.aliyuncs.com'
# 通过环境变量传递临时访问凭证信息。
access_key_id = os.getenv('OSS_AccessKeyId')
secret_access_key = os.getenv('OSS_AccessKeySecret')
session_token = os.getenv('OSS_SessionToken')
s3 = boto3.client(
's3',
aws_access_key_id=access_key_id,
aws_secret_access_key=secret_access_key,
aws_session_token=session_token,
endpoint_url=endpoint,
config=Config(s3={"addressing_style": "virtual", "signature_version": 's3v4'}))
PHP SDK
以下以AWS PHP SDK 3.109.3版本为例,介绍初始化实例的操作步骤。
修改AWS配置和证书文件。
以下以Linux系统为例:
在~/.aws/config路径下的配置文件中添加以下配置信息:
[default] s3 = addressing_style = virtual
在~/.aws/credentials路径下的证书文件中配置临时访问凭证。
[default] aws_access_key_id = [OSS_AccessKeyId] aws_secret_access_key = [OSS_AccessKeySecret] aws_secret_sessiontoken = [OSS_SessionToken]
初始化实例。
<?php require_once __DIR__ . '/vendor/autoload.php'; use Aws\Credentials\CredentialProvider; use Aws\Credentials\Credentials; use Aws\S3\S3Client; $provider = CredentialProvider::fromCredentials(new Credentials( getenv('OSS_ACCESS_KEY_ID'), getenv('OSS_ACCESS_KEY_SECRET'), getenv('OSS_SESSION_TOKEN') )); // 创建S3客户端。 $s3Client = new S3Client([ 'region' => 'oss-cn-hangzhou', 'version' => '2006-03-01', 'endpoint' => 'http://oss-cn-hangzhou.aliyuncs.com', 'credentials' => $provider ]);
Node.js SDK
以AWS Node.js SDK 2.509.0版本为例,初始化实例的示例代码如下:
const S3 = require("@aws-sdk/client-s3");
const { S3Client, PutObjectCommand } = S3;
// 初始化S3客户端。
const region = "oss-cn-chengdu";
const s3Client = new S3Client({
region,
endpoint: `https://${region}.aliyuncs.com`,
credentials: {
accessKeyId: process.env.AccessKeyId,
secretAccessKey: process.env.AccessKeySecret,
sessionToken: process.env.SecurityToken,
},
});
// 使用客户端执行操作,例如上传文件。
async function uploadObject() {
const command = new PutObjectCommand({
// 填写Bucket名称。
Bucket: "yourbucket",
// 填写OSS文件完整路径和本地文件的完整路径。OSS文件完整路径中不能包含Bucket名称。
Key: "file.txt",
// 指定文件内容或Buffer。
Body: "Hello from AWS SDK v3!",
});
try {
const response = await s3Client.send(command);
console.log("Object uploaded successfully", response);
} catch (error) {
console.error("Error uploading object:", error);
}
}
uploadObject();
.NET SDK
以AWS .NET SDK 3.3.104.12版本为例,初始化实例的示例代码如下:
string sAccessKeyId = Environment.GetEnvironmentVariable("OSS_ACCESS_KEY_ID");
string sAccessKeySecret = Environment.GetEnvironmentVariable("OSS_ACCESS_KEY_SECRET");
string sToken = Environment.GetEnvironmentVariable("OSS_SESSION_TOKEN");
string endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
var config = newAmazonS3Config(){ServiceURL=endpoint};
var client = new AmazonS3Client(sAccessKeyId, sAccessKeySecret, sToken, config);
Android SDK
移动终端是一个不受信任的环境,将长期有效的AccessKey直接保存在移动终端用来加签请求,存在极高的风险。建议您通过STS方式获取临时访问凭证。具体步骤,请参见使用STS临时访问凭证访问OSS。
以AWS Android SDK 2.14.2版本为例,初始化实例的示例代码如下:
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-hongkong.aliyuncs.com");
iOS SDK
移动终端是一个不受信任的环境,将长期有效的AccessKey直接保存在移动终端用来加签请求,存在极高的风险。建议您通过STS方式获取临时访问凭证。具体步骤,请参见使用STS临时访问凭证访问OSS。
以AWS iOS SDK 2.10.2版本为例,介绍初始化实例的操作步骤。
实现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{ }
初始化实例。
NSURL* bucketURL = [NSURL URLWithString:@"https://oss-cn-hongkong.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版本为例,初始化实例的示例代码如下。
package main import ( "fmt" "github.com/aws/aws-sdk-go/aws" "github.com/aws/aws-sdk-go/aws/credentials" "github.com/aws/aws-sdk-go/aws/session" "github.com/aws/aws-sdk-go/service/s3" "log" "os" ) func main() { sess, _ := newSession() service := s3.New(sess) bucket := "demo-bucket" key := "demo" result, err := service.GetObject(&s3.GetObjectInput{ Bucket: aws.String(bucket), Key: aws.String(key), }) if err != nil { log.Printf("LoadDefaultConfig error: %v", err) return } fmt.Printf("result:%#v\n", result) } func newSession() (*session.Session, error) { accessID := os.Getenv("OSS_ACCESS_KEY_ID") accessKey := os.Getenv("OSS_ACCESS_KEY_SECRET") token := os.Getenv("OSS_SESSION_TOKEN") creds := credentials.NewStaticCredentials(accessID, accessKey, token) 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, } return session.NewSession(config) }
2.x版本
以下以AWS Go SDK 2.x版本为例,初始化实例的示例代码如下。
package main import ( "context" "fmt" "github.com/aws/aws-sdk-go-v2/aws" awsconfig "github.com/aws/aws-sdk-go-v2/config" "github.com/aws/aws-sdk-go-v2/credentials" "github.com/aws/aws-sdk-go-v2/service/s3" "log" "os" ) func main() { // 填写Bucket名称。 bucketName := "demo-bucket" // 填写Object完整路径,完整路径中不能包含Bucket名称。 fileName := "demo.go" 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 }) envCredential, err := NewEnvironmentVariableCredentials() if err != nil { log.Printf("error: %v", err) return } provider := NewAwsS3Provider(envCredential) cfg, err := awsconfig.LoadDefaultConfig(context.TODO(), awsconfig.WithCredentialsProvider(provider), awsconfig.WithEndpointResolverWithOptions(customResolver)) if err != nil { log.Printf("LoadDefaultConfig error: %v", err) return } awsS3Client := s3.NewFromConfig(cfg) //fp, _ := os.Open(fileName) //defer fp.Close() result, err := awsS3Client.GetObject(context.TODO(), &s3.GetObjectInput{ Bucket: aws.String(bucketName), Key: aws.String(fileName), }) if err != nil { log.Printf("GetObject error: %v", err) return } fmt.Printf("result:%#v\n", result) } type Credentials struct { AccessKeyId string AccessKeySecret string SecurityToken string } func (credentials *Credentials) GetAccessKeyID() string { return credentials.AccessKeyId } func (credentials *Credentials) GetAccessKeySecret() string { return credentials.AccessKeySecret } func (credentials *Credentials) GetSecurityToken() string { return credentials.SecurityToken } func NewAwsS3Provider(credential *Credentials) credentials.StaticCredentialsProvider { return credentials.StaticCredentialsProvider{ Value: aws.Credentials{ AccessKeyID: credential.AccessKeyId, SecretAccessKey: credential.AccessKeySecret, SessionToken: credential.SecurityToken, }, } } func NewEnvironmentVariableCredentials() (*Credentials, error) { var envCredential *Credentials accessID := os.Getenv("OSS_ACCESS_KEY_ID") if accessID == "" { return envCredential, fmt.Errorf("access key id is empty!") } accessKey := os.Getenv("OSS_ACCESS_KEY_SECRET") if accessKey == "" { return envCredential, fmt.Errorf("access key secret is empty!") } token := os.Getenv("OSS_SESSION_TOKEN") envCredential = &Credentials{ AccessKeyId: accessID, AccessKeySecret: accessKey, SecurityToken: token, } return envCredential, nil }
C++ SDK
以下以AWS C++ SDK 1.7.68版本为例,介绍初始化配置的操作步骤。
修改AWS配置和证书文件。
以下以Linux系统为例:
在~/.aws/config路径下的配置文件中添加以下配置信息:
[default] s3 = addressing_style = virtual
在~/.aws/credentials路径下的证书文件中配置OSS访问密钥。
[default] aws_access_key_id = [OSS_AccessKeyId] aws_secret_access_key = [OSS_AccessKeySecret] aws_secret_sessiontoken = [OSS_SessionToken]
设置Endpoint。
Aws::Client::ClientConfiguration awsCC; awsCC.scheme = Aws::Http::Scheme::HTTP; awsCC.region = "oss-cn-hongkong"; awsCC.endpointOverride = "oss-cn-hongkong.aliyuncs.com"; Aws::S3::S3Client s3_client(awsCC);