如何使用AWSS3SDK訪問OSS - Object Storage Service

Object Storage Service提供了相容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的對應關係，請參見OSS地區和訪問網域名稱。

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='v4'))

PHP SDK

以下以AWS PHP SDK 3.109.3版本為例，介紹初始化執行個體的操作步驟。

修改AWS配置和認證檔案。
以下以Linux系統為例：
1. 在~/.aws/config路徑下的設定檔中添加以下配置資訊：
```
[default]
s3 =
addressing_style = virtual
```
2. 在~/.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

重要

以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系統為例：
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]
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);