OSS SDK安装配置与Object上传下载快速入门-对象存储(OSS)-阿里云帮助中心

OSS SDK支持使用Java、Python、Go、PHP、C#和Node.js连接Bucket，并完成Object上传、下载和删除，帮助您快速配置SDK并验证OSS访问。

前提条件

已开通OSS服务并创建Bucket。具体操作，请参见控制台快速入门。
已获取可用的AccessKey。如果没有AccessKey，请参见创建AccessKey。

重要
为避免主账号AccessKey泄露带来的安全风险，建议使用RAM用户的AccessKey，并按最小权限原则授予测试Bucket的oss:PutObject、oss:GetObject和oss:DeleteObject权限。

配置访问凭证

SDK从环境变量中读取AccessKey。请勿将AccessKey明文写入代码。

macOS或Linux

export OSS_ACCESS_KEY_ID="yourAccessKeyId"
export OSS_ACCESS_KEY_SECRET="yourAccessKeySecret"

Windows PowerShell

$env:OSS_ACCESS_KEY_ID="yourAccessKeyId"
$env:OSS_ACCESS_KEY_SECRET="yourAccessKeySecret"

准备示例参数

运行代码前，将示例中的以下参数替换为实际值。

参数	示例值	说明
`region`	`<region-id>`	Bucket所在地域的Region ID。
`bucket`	`example-bucket`	已创建的Bucket名称。
`key`	`example.txt`	示例Object的完整名称。代码运行结束时会删除该Object。

Java、Python、Go、PHP和C#的V2 SDK会根据Region ID使用默认公网Endpoint，因此本示例无需显式配置Endpoint。Node.js SDK的Region值需要添加oss-前缀。如果需要使用内网、传输加速或自定义域名，请参见通过Endpoint和Bucket域名访问OSS。

SDK示例

选择开发语言。每个标签页均包含SDK安装命令，以及客户端初始化、上传、下载验证、删除和资源释放所需的完整代码。

Java SDK V2

在Maven项目的pom.xml中添加以下依赖。示例使用0.5.1版本。

<dependency>
    <groupId>com.aliyun</groupId>
    <artifactId>alibabacloud-oss-v2</artifactId>
    <version>0.5.1</version>
</dependency>

示例代码如下。

package com.example.oss;

import com.aliyun.sdk.service.oss2.OSSClient;
import com.aliyun.sdk.service.oss2.credentials.EnvironmentVariableCredentialsProvider;
import com.aliyun.sdk.service.oss2.models.DeleteObjectRequest;
import com.aliyun.sdk.service.oss2.models.GetObjectRequest;
import com.aliyun.sdk.service.oss2.models.GetObjectResult;
import com.aliyun.sdk.service.oss2.models.PutObjectRequest;
import com.aliyun.sdk.service.oss2.transport.BinaryData;
import com.aliyun.sdk.service.oss2.utils.IOUtils;

import java.nio.charset.StandardCharsets;

public class QuickStart {
    public static void main(String[] args) throws Exception {
        String region = "<region-id>";
        String bucket = "example-bucket";
        String key = "example.txt";
        String content = "Hello OSS";

        try (OSSClient client = OSSClient.newBuilder()
                .credentialsProvider(new EnvironmentVariableCredentialsProvider())
                .region(region)
                .build()) {
            boolean uploaded = false;
            try {
                client.putObject(PutObjectRequest.newBuilder()
                        .bucket(bucket)
                        .key(key)
                        .body(BinaryData.fromString(content))
                        .build());
                uploaded = true;
                System.out.println("Object uploaded");

                String downloaded;
                try (GetObjectResult result = client.getObject(GetObjectRequest.newBuilder()
                        .bucket(bucket)
                        .key(key)
                        .build())) {
                    downloaded = new String(IOUtils.toByteArray(result.body()), StandardCharsets.UTF_8);
                }
                if (!content.equals(downloaded)) {
                    throw new IllegalStateException("Downloaded content does not match uploaded content");
                }
                System.out.println("Downloaded content: " + downloaded);
            } finally {
                if (uploaded) {
                    client.deleteObject(DeleteObjectRequest.newBuilder()
                            .bucket(bucket)
                            .key(key)
                            .build());
                    System.out.println("Object deleted");
                }
            }
        }

        System.out.println("Quick start completed");
    }
}

更多配置和示例，请参见OSS Java SDK V2。

Python SDK V2

安装SDK。示例使用1.3.2版本。

python3 -m pip install alibabacloud-oss-v2

示例代码如下。

import alibabacloud_oss_v2 as oss


def main():
    region = "<region-id>"
    bucket = "example-bucket"
    key = "example.txt"
    content = "Hello OSS"

    config = oss.config.load_default()
    config.credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()
    config.region = region
    client = oss.Client(config)

    uploaded = False
    try:
        client.put_object(oss.PutObjectRequest(
            bucket=bucket,
            key=key,
            body=content.encode("utf-8"),
        ))
        uploaded = True
        print("Object uploaded")

        result = client.get_object(oss.GetObjectRequest(bucket=bucket, key=key))
        with result.body as body_stream:
            downloaded = body_stream.read().decode("utf-8")
        if downloaded != content:
            raise RuntimeError("Downloaded content does not match uploaded content")
        print(f"Downloaded content: {downloaded}")
    finally:
        if uploaded:
            client.delete_object(oss.DeleteObjectRequest(bucket=bucket, key=key))
            print("Object deleted")

    print("Quick start completed")


if __name__ == "__main__":
    main()

更多配置和示例，请参见OSS Python SDK V2。

Go SDK V2

安装最新版本的SDK。示例使用v1.5.3版本。

go get github.com/aliyun/alibabacloud-oss-go-sdk-v2@latest

示例代码如下。

package main

import (
    "context"
    "fmt"
    "io"
    "log"
    "strings"

    "github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
    "github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
)

func run() (err error) {
    region := "<region-id>"
    bucket := "example-bucket"
    key := "example.txt"
    content := "Hello OSS"
    ctx := context.Background()

    config := oss.LoadDefaultConfig().
        WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
        WithRegion(region)
    client := oss.NewClient(config)

    uploaded := false
    defer func() {
        if !uploaded {
            return
        }
        _, deleteErr := client.DeleteObject(ctx, &oss.DeleteObjectRequest{
            Bucket: oss.Ptr(bucket),
            Key:    oss.Ptr(key),
        })
        if deleteErr != nil {
            if err == nil {
                err = fmt.Errorf("delete object: %w", deleteErr)
            }
            return
        }
        fmt.Println("Object deleted")
    }()

    _, err = client.PutObject(ctx, &oss.PutObjectRequest{
        Bucket: oss.Ptr(bucket),
        Key:    oss.Ptr(key),
        Body:   strings.NewReader(content),
    })
    if err != nil {
        return fmt.Errorf("upload object: %w", err)
    }
    uploaded = true
    fmt.Println("Object uploaded")

    result, err := client.GetObject(ctx, &oss.GetObjectRequest{
        Bucket: oss.Ptr(bucket),
        Key:    oss.Ptr(key),
    })
    if err != nil {
        return fmt.Errorf("download object: %w", err)
    }
    defer result.Body.Close()

    data, err := io.ReadAll(result.Body)
    if err != nil {
        return fmt.Errorf("read downloaded object: %w", err)
    }
    downloaded := string(data)
    if downloaded != content {
        return fmt.Errorf("downloaded content does not match uploaded content")
    }
    fmt.Printf("Downloaded content: %s\n", downloaded)

    return nil
}

func main() {
    if err := run(); err != nil {
        log.Fatal(err)
    }
    fmt.Println("Quick start completed")
}

更多配置和示例，请参见OSS Go SDK V2。

PHP SDK V2

使用Composer安装SDK。示例使用0.4.0版本。

composer require alibabacloud/oss-v2

示例代码如下。

<?php

require_once __DIR__ . '/vendor/autoload.php';

use AlibabaCloud\Oss\V2 as Oss;

$region = '<region-id>';
$bucket = 'example-bucket';
$key = 'example.txt';
$content = 'Hello OSS';

$config = Oss\Config::loadDefault();
$config->setCredentialsProvider(new Oss\Credentials\EnvironmentVariableCredentialsProvider());
$config->setRegion($region);
$client = new Oss\Client($config);

$uploaded = false;
try {
    $putRequest = new Oss\Models\PutObjectRequest($bucket, $key);
    $putRequest->body = Oss\Utils::streamFor($content);
    $client->putObject($putRequest);
    $uploaded = true;
    echo 'Object uploaded' . PHP_EOL;

    $result = $client->getObject(new Oss\Models\GetObjectRequest($bucket, $key));
    $downloaded = $result->body->getContents();
    if ($downloaded !== $content) {
        throw new RuntimeException('Downloaded content does not match uploaded content');
    }
    echo 'Downloaded content: ' . $downloaded . PHP_EOL;
} finally {
    if ($uploaded) {
        $client->deleteObject(new Oss\Models\DeleteObjectRequest($bucket, $key));
        echo 'Object deleted' . PHP_EOL;
    }
}

echo 'Quick start completed' . PHP_EOL;

更多配置和示例，请参见OSS PHP SDK V2。

C# SDK V2

安装SDK。示例使用0.2.0版本。

dotnet add package AlibabaCloud.OSS.V2

示例代码如下。

using System.Text;
using OSS = AlibabaCloud.OSS.V2;

var region = "<region-id>";
var bucket = "example-bucket";
var key = "example.txt";
var content = "Hello OSS";

var config = OSS.Configuration.LoadDefault();
config.CredentialsProvider = new OSS.Credentials.EnvironmentVariableCredentialsProvider();
config.Region = region;

using var client = new OSS.Client(config);
var uploaded = false;
try
{
    await client.PutObjectAsync(new OSS.Models.PutObjectRequest
    {
        Bucket = bucket,
        Key = key,
        Body = new MemoryStream(Encoding.UTF8.GetBytes(content))
    });
    uploaded = true;
    Console.WriteLine("Object uploaded");

    var result = await client.GetObjectAsync(new OSS.Models.GetObjectRequest
    {
        Bucket = bucket,
        Key = key
    });
    using var body = result.Body ?? throw new InvalidOperationException("The response body is empty");
    using var reader = new StreamReader(body, Encoding.UTF8);
    var downloaded = await reader.ReadToEndAsync();
    if (downloaded != content)
    {
        throw new InvalidOperationException("Downloaded content does not match uploaded content");
    }
    Console.WriteLine($"Downloaded content: {downloaded}");
}
finally
{
    if (uploaded)
    {
        await client.DeleteObjectAsync(new OSS.Models.DeleteObjectRequest
        {
            Bucket = bucket,
            Key = key
        });
        Console.WriteLine("Object deleted");
    }
}

Console.WriteLine("Quick start completed");

更多配置和示例，请参见OSS C# SDK V2。

Node.js SDK

安装SDK。示例使用6.23.0版本。

npm install ali-oss

示例代码如下。

const OSS = require('ali-oss');

const region = 'oss-<region-id>';
const bucket = 'example-bucket';
const key = 'example.txt';
const content = 'Hello OSS';

const client = new OSS({
  region,
  bucket,
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  authorizationV4: true,
});

async function main() {
  let uploaded = false;
  try {
    await client.put(key, Buffer.from(content, 'utf8'));
    uploaded = true;
    console.log('Object uploaded');

    const result = await client.get(key);
    const downloaded = result.content.toString('utf8');
    if (downloaded !== content) {
      throw new Error('Downloaded content does not match uploaded content');
    }
    console.log(`Downloaded content: ${downloaded}`);
  } finally {
    if (uploaded) {
      await client.delete(key);
      console.log('Object deleted');
    }
  }

  console.log('Quick start completed');
}

main().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});

更多配置和示例，请参见OSS Node.js SDK。

查看运行结果

代码成功运行后，输出如下。无论后续验证是否成功，示例都会尝试删除已上传的Object，避免持续占用存储空间。

Object uploaded
Downloaded content: Hello OSS
Object deleted
Quick start completed

SDK快速入门

前提条件

配置访问凭证

macOS或Linux

Windows PowerShell

准备示例参数

SDK示例

Java SDK V2

Python SDK V2

Go SDK V2

PHP SDK V2

C# SDK V2

Node.js SDK

查看运行结果

更多SDK