文档中心

快速入门（Android SDK）

最近更新时间：2024.02.04 18:31:00

首次发布时间：2022.12.01 16:31:39

本文介绍如何通过 TOS Android SDK 来完成常见的操作，如创建桶，上传、下载和删除对象等。

前提条件

客户端通用示例

Android SDK 当前只提供了同步请求接口，使用时需要进行异步化封装，才能在 Android APP 中正常发起请求。以下代码展示了异步使用 SDK 的通用示例。

import androidx.appcompat.app.AppCompatActivity;
import android.os.Bundle;
import android.util.Log;

import com.volcengine.tos.TOSV2;
import com.volcengine.tos.TOSV2ClientBuilder;
import com.volcengine.tos.TosClientException;
import com.volcengine.tos.TosServerException;
import com.volcengine.tos.model.object.PutObjectBasicInput;
import com.volcengine.tos.model.object.PutObjectInput;
import com.volcengine.tos.model.object.PutObjectOutput;

import java.io.ByteArrayInputStream;

public class DisplayMessageActivity extends AppCompatActivity {
    private TOSV2 tos;
    String endpoint = "your endpoint";
    String region = "your region";
    String accessKey = "your access key";
    String secretKey = "your secret key";
    String securityToken = "your security token";

    String bucketName = "your bucket name";
    String objectKey = "your object key";

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_display_message);
        tos = new TOSV2ClientBuilder().build(region, endpoint, accessKey, secretKey, securityToken);

        Thread tosThread = new Thread(new Runnable() {
            @Override
            public void run() {
                try  {
                    String data = "1234567890abcdefghijklmnopqrstuvwxyz~!@#$%^&*()_+<>?,./   :'1234567890abcdefghijklmnopqrstuvwxyz~!@#$%^&*()_+<>?,./   :'";
                    ByteArrayInputStream stream = new ByteArrayInputStream(data.getBytes());
                    PutObjectBasicInput basicInput = new PutObjectBasicInput().setBucket(bucketName).setKey(objectKey);
                    PutObjectInput putObjectInput = new PutObjectInput().setPutObjectBasicInput(basicInput).setContent(stream);
                    PutObjectOutput output = tos.putObject(putObjectInput);
                    Log.i("putObject", "object's etag is " + output.getEtag());
                    Log.i("putObject", "object's crc64 is " + output.getHashCrc64ecma());
                } catch (TosServerException e) {
                    Log.e("TosServerException", e.toString());
                } catch (TosClientException e) {
                    Log.e("TosClientException", e.toString());
                } catch (Throwable t) {
                    t.printStackTrace();
                }
            }
        });

        tosThread.start();
    }
}

创建桶

桶（bucket）是 TOS 的全局唯一的命名空间，相当于数据的容器，用来储存对象数据。如下代码展示如何创建一个新的桶。

import android.os.Bundle;
import android.util.Log;

import androidx.appcompat.app.AppCompatActivity;

import com.volcengine.tos.TOSV2;
import com.volcengine.tos.TOSV2ClientBuilder;
import com.volcengine.tos.TosException;
import com.volcengine.tos.model.bucket.CreateBucketV2Input;
import com.volcengine.tos.model.bucket.CreateBucketV2Output;

public class CreateBucketExample extends AppCompatActivity {

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        String endpoint = "your endpoint";
        String region = "your region";
        String accessKey = "your access key";
        String secretKey = "your secret key";
        String securityToken = "your security token";

        String bucketName = "your bucket name";
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_display_message);
        TOSV2 tos = new TOSV2ClientBuilder().build(region, endpoint, accessKey, secretKey, securityToken);

        Thread tosThread = new Thread(new Runnable() {
            @Override
            public void run() {
                try{
                    CreateBucketV2Input input = new CreateBucketV2Input().setBucket(bucketName);
                    CreateBucketV2Output output = tos.createBucket(input);
                    Log.i("bucket created: ", output.getLocation());
                } catch (TosException e) {
                    e.printStackTrace();
                }
            }
        });

        tosThread.start();
    }
}

上传对象

新建桶成功后，可以往桶中上传对象，如下展示如何上传一个对象到已创建的桶中。

import android.os.Bundle;
import android.util.Log;

import androidx.appcompat.app.AppCompatActivity;

import com.volcengine.tos.TOSV2;
import com.volcengine.tos.TOSV2ClientBuilder;
import com.volcengine.tos.TosException;
import com.volcengine.tos.model.object.PutObjectBasicInput;
import com.volcengine.tos.model.object.PutObjectInput;
import com.volcengine.tos.model.object.PutObjectOutput;

import java.io.ByteArrayInputStream;

public class PutObjectBasicExample extends AppCompatActivity {

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        String endpoint = "your endpoint";
        String region = "your region";
        String accessKey = "your access key";
        String secretKey = "your secret key";
        String securityToken = "your security token";

        String bucketName = "your bucket name";
        String objectKey = "your object key";
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_display_message);
        TOSV2 tos = new TOSV2ClientBuilder().build(region, endpoint, accessKey, secretKey, securityToken);

        Thread tosThread = new Thread(new Runnable() {
            @Override
            public void run() {
                try{
                    String data = "1234567890abcdefghijklmnopqrstuvwxyz~!@#$%^&*()_+<>?,./   :'1234567890abcdefghijklmnopqrstuvwxyz~!@#$%^&*()_+<>?,./   :'";
                    ByteArrayInputStream stream = new ByteArrayInputStream(data.getBytes());
                    PutObjectBasicInput basicInput = new PutObjectBasicInput().setBucket(bucketName).setKey(objectKey);
                    PutObjectInput putObjectInput = new PutObjectInput().setPutObjectBasicInput(basicInput).setContent(stream);
                    PutObjectOutput output = tos.putObject(putObjectInput);
                    Log.i("putObject", "succeed, object's etag is " + output.getEtag());
                    Log.i("putObject", "succeed, object's crc64 is " + output.getHashCrc64ecma());
                } catch (TosException e) {
                    Log.e("putObject",  "failed");
                    e.printStackTrace();
                }
            }
        });

        tosThread.start();
    }
}

说明

如果您希望上传对象到某个文件夹（对象存储的逻辑概念）下，可以为对象名添加以 / 结尾的前缀，且支持多级文件夹，例如对象名 folder1/folder2/objectName 是指将 objectName 上传到 folder1 文件夹下的 folder2 文件夹下。
上传对象到某个文件夹时，由于文件夹只是对象存储的逻辑概念，因此实际上不会在对象存储服务端生成真实的文件夹。
下载对象时，必须使用带前缀的全路径，例如下载对象时需要传入的对象名同样为 folder1/folder2/objectName。
上传对象的更多示例，请参见普通上传。

下载对象

如下展示如何从桶中下载一个已经存在的对象。

import android.os.Bundle;
import android.util.Log;

import androidx.appcompat.app.AppCompatActivity;

import com.volcengine.tos.TOSV2;
import com.volcengine.tos.TOSV2ClientBuilder;
import com.volcengine.tos.TosException;
import com.volcengine.tos.model.object.GetObjectV2Input;
import com.volcengine.tos.model.object.GetObjectV2Output;

import java.io.FileOutputStream;
import java.io.IOException;

public class GetObjectBasicExample extends AppCompatActivity {

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        String endpoint = "your endpoint";
        String region = "your region";
        String accessKey = "your access key";
        String secretKey = "your secret key";
        String securityToken = "your security token";

        String bucketName = "your bucket name";
        String objectKey = "your object key";
        String filePath = "your file path";
        
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_display_message);
        TOSV2 tos = new TOSV2ClientBuilder().build(region, endpoint, accessKey, secretKey, securityToken);

        Thread tosThread = new Thread(new Runnable() {
            @Override
            public void run() {
                try{
                    GetObjectV2Input input = new GetObjectV2Input().setBucket(bucketName).setKey(objectKey);
                    // 以下代码展示如何将数据下载到本地文件
                    try(FileOutputStream fileOutputStream = new FileOutputStream(filePath);
                        GetObjectV2Output output = tos.getObject(input)) {
                        byte[] buffer = new byte[1024];
                        int length;
                        while ((length = output.getContent().read(buffer)) != -1) {
                            fileOutputStream.write(buffer, 0, length);
                        }
                        Log.i("getObject", "succeed, object's metadata is " + output.getGetObjectBasicOutput());
                    } catch (IOException e) {
                        Log.e("IOException", "write data to file failed");
                        e.printStackTrace();
                    }
                } catch (TosException e) {
                    if (e.getStatusCode() == 404) {
                        // 下载不存在的对象会返回404
                        Log.e("TosException", "the object you want to download is not found");
                        e.printStackTrace();
                    } else {
                        Log.e("TosException", "getObject failed");
                        e.printStackTrace();
                    }
                }
            }
        });

        tosThread.start();
    }
}

说明

下载对象的更多示例，请参见普通下载。

列举对象

如下展示如何从桶中列举已上传的对象。

import android.os.Bundle;
import android.util.Log;

import androidx.appcompat.app.AppCompatActivity;

import com.volcengine.tos.TOSV2;
import com.volcengine.tos.TOSV2ClientBuilder;
import com.volcengine.tos.TosException;
import com.volcengine.tos.model.object.ListObjectsV2Input;
import com.volcengine.tos.model.object.ListObjectsV2Output;
import com.volcengine.tos.model.object.ListedObjectV2;

public class ListObjectBasicExample extends AppCompatActivity {

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        String endpoint = "your endpoint";
        String region = "your region";
        String accessKey = "your access key";
        String secretKey = "your secret key";
        String securityToken = "your security token";

        String bucketName = "your bucket name";
        int maxKeys = 10;

        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_display_message);
        TOSV2 tos = new TOSV2ClientBuilder().build(region, endpoint, accessKey, secretKey, securityToken);

        Thread tosThread = new Thread(new Runnable() {
            @Override
            public void run() {
                try{
                    ListObjectsV2Input input = new ListObjectsV2Input()
                            // 必须设置 bucket name
                            .setBucket(bucketName).setMaxKeys(maxKeys);
                    ListObjectsV2Output output = tos.listObjects(input);
                    Log.i("listObjects", "listObjects succeed, is truncated? " + output.isTruncated() + "next marker is " + output.getNextMarker());
                    if (output.getContents() != null) {
                        for (int i = 0; i < output.getContents().size(); i++) {
                            ListedObjectV2 object = output.getContents().get(i);
                            Log.i("listObjects", "No." + (i+1) + " listed object is " + object);
                        }
                    }
                    // list by next marker
                    input = new ListObjectsV2Input().setBucket(bucketName).setMaxKeys(maxKeys).setMarker(output.getNextMarker());
                    output = tos.listObjects(input);
                    Log.i("listObjects", "listObjects succeed, is truncated? " + output.isTruncated() + "next marker is " + output.getNextMarker());
                    if (output.getContents() != null) {
                        for (int i = 0; i < output.getContents().size(); i++) {
                            ListedObjectV2 object = output.getContents().get(i);
                            Log.i("listObjects", "No." + (i+1) + " listed object is " + object);
                        }
                    }
                } catch (TosException e) {
                    Log.e("TosException", "listObjects failed");
                    e.printStackTrace();
                }
            }
        });

        tosThread.start();
    }
}

说明

列举对象的更多示例，请参见列举对象。

删除对象

如下展示如何从桶中删除一个已经存在的对象。

import android.os.Bundle;
import android.util.Log;

import androidx.appcompat.app.AppCompatActivity;

import com.volcengine.tos.TOSV2;
import com.volcengine.tos.TOSV2ClientBuilder;
import com.volcengine.tos.TosException;
import com.volcengine.tos.model.object.DeleteObjectInput;
import com.volcengine.tos.model.object.DeleteObjectOutput;

public class DeleteObjectBasicExample extends AppCompatActivity {

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        String endpoint = "your endpoint";
        String region = "your region";
        String accessKey = "your access key";
        String secretKey = "your secret key";
        String securityToken = "your security token";

        String bucketName = "your bucket name";
        String objectKey = "your object key";
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_display_message);
        TOSV2 tos = new TOSV2ClientBuilder().build(region, endpoint, accessKey, secretKey, securityToken);

        Thread tosThread = new Thread(new Runnable() {
            @Override
            public void run() {
                try{
                    DeleteObjectInput input = new DeleteObjectInput().setBucket(bucketName).setKey(objectKey);
                    DeleteObjectOutput output = tos.deleteObject(input);
                    Log.i("deleteObject", "succeed, " + output);
                } catch (TosException e) {
                    Log.e("TosException", "deleteObject failed");
                    e.printStackTrace();
                }
            }
        });

        tosThread.start();
    }
}

说明

删除对象的更多示例，请参见删除对象。

前提条件

客户端通用示例

创建桶

上传对象

下载对象

列举对象

删除对象

对象存储

快速入门（Android SDK）

前提条件

客户端通用示例

创建桶

上传对象

下载对象

列举对象

删除对象