如何快速上手OSS ON云盒 - 对象存储 OSS

通过OSS ON云盒，您可以对本地数据进行数据监控、数据处理等操作。OSS ON云盒适用于业务要求低延时、多分支机构统一管理等场景。本文介绍OSS ON云盒的基本操作，包括创建云盒Bucket、在Bucket中上传文件（Object）以及下载Object。

前提条件

仅华东1（杭州）、华东2（上海）、华南1（深圳）、华南2（河源）、华北2（北京）、西南1（成都）地域支持使用OSS ON云盒服务。
已购买云盒。
已在云盒内创建专有网络VPC和交换机。
已联系技术支持申请创建云盒VPC内网SingleTunnel网络类型。

步骤一：创建云盒Bucket

使用OSS控制台

登录OSS管理控制台。
在左侧导航栏，选择数据服务 > 云盒Bucket，然后单击左上角的创建 Bucket。
在创建 Bucket页面，填写Bucket名称，其他参数保留默认配置，然后单击确定。

Bucket名称的命名规则如下：
- 指定的Bucket名称不能与云盒中已存在Bucket名称重复。
- 只能包括小写字母、数字和短划线（-）。
- 必须以小写字母或者数字开头和结尾。
- 长度必须在3~63字符之间。

使用阿里云SDK

支持通过Java、Python、Go SDK创建云盒Bucket（Java SDK要求3.15.0及以上版本，Python SDK V2要求1.1.1及以上版本，Go SDK V2要求v1.2.1及以上版本）。云盒场景下，Python、Go SDK的操作调用方式与公共云OSS一致，创建客户端的方式请参见SDK支持。

Java

import com.aliyun.oss.ClientException;
import com.aliyun.oss.OSS;
import com.aliyun.oss.OSSClientBuilder;
import com.aliyun.oss.OSSException;
import com.aliyun.oss.model.CreateBucketRequest;
import com.aliyun.oss.common.auth.DefaultCredentialProvider;
import com.aliyun.oss.common.comm.SignVersion;
import com.aliyun.oss.ClientBuilderConfiguration;
import com.aliyun.oss.common.auth.CredentialsProviderFactory;
import com.aliyun.oss.common.auth.EnvironmentVariableCredentialsProvider;

public class Demo {

    public static void main(String[] args) throws Exception {
        // 填写云盒Bucket的数据域名。
        String endpoint = "https://cb-f8z7yvzgwfkl9q0h****.cn-hangzhou.oss-cloudbox.aliyuncs.com";
        // 从环境变量中获取访问凭证。运行本代码示例之前，请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
        EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
        // 填写云盒Bucket名称，例如examplebucket。
        String bucketName = "examplebucket";
        // 填写云盒Bucket所在地域。
        String region = "cn-hangzhou";
        // 填写云盒ID。
        String cloudBoxId = "cb-f8z7yvzgwfkl9q0h****";


        // 创建OSSClient实例。
        // 当OSSClient实例不再使用时，调用shutdown方法以释放资源。
        ClientBuilderConfiguration conf = new ClientBuilderConfiguration();
        conf.setSignatureVersion(SignVersion.V4);
        OSS ossClient = OSSClientBuilder.create()
                .endpoint(endpoint)
                .credentialsProvider(new DefaultCredentialProvider(credentialsProvider.getCredentials()))
                .clientConfiguration(conf)
                .region(region)
                .cloudBoxId(cloudBoxId)
                .build();

        try {
            // 创建CreateBucketRequest对象。
            CreateBucketRequest createBucketRequest = new CreateBucketRequest(bucketName);            
                       
            // 设置云盒Bucket的读写权限为公共读，默认为私有。
            //createBucketRequest.setCannedACL(CannedAccessControlList.PublicRead);

            // 创建云盒Bucket。
            ossClient.createBucket(createBucketRequest);
        } catch (OSSException oe) {
            System.out.println("Caught an OSSException, which means your request made it to OSS, "
                    + "but was rejected with an error response for some reason.");
            System.out.println("Error Message:" + oe.getErrorMessage());
            System.out.println("Error Code:" + oe.getErrorCode());
            System.out.println("Request ID:" + oe.getRequestId());
            System.out.println("Host ID:" + oe.getHostId());
        } catch (ClientException ce) {
            System.out.println("Caught an ClientException, which means the client encountered "
                    + "a serious internal problem while trying to communicate with OSS, "
                    + "such as not being able to access the network.");
            System.out.println("Error Message:" + ce.getMessage());
        } finally {
            if (ossClient != null) {
                ossClient.shutdown();
            }
        }
    }
}

Python

import alibabacloud_oss_v2 as oss

# 从环境变量获取访问凭证，运行前请先配置 OSS_ACCESS_KEY_ID 和 OSS_ACCESS_KEY_SECRET。
credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()
cfg = oss.config.load_default()
cfg.credentials_provider = credentials_provider
# 云盒所在地域，例如 cn-hangzhou。
cfg.region = "cn-hangzhou"
# 云盒数据域名，格式为 CloudboxId.Region.oss-cloudbox.aliyuncs.com。
cfg.endpoint = "cb-xxxx.cn-hangzhou.oss-cloudbox.aliyuncs.com"
# 云盒 ID。
cfg.cloud_box_id = "cb-xxxx"

client = oss.Client(cfg)

# 创建存储空间（Bucket），Bucket 名称需全局唯一。
result = client.put_bucket(oss.PutBucketRequest(
    bucket="examplebucket",
    acl="private",
))
print(f"status code: {result.status_code}, request id: {result.request_id}")

package main

import (
    "context"
    "log"

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

func main() {
    // 云盒所在地域，例如 cn-hangzhou。
    region := "cn-hangzhou"

    // 从环境变量获取访问凭证，运行前请先配置 OSS_ACCESS_KEY_ID 和 OSS_ACCESS_KEY_SECRET。
    cfg := oss.LoadDefaultConfig().
        WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
        WithRegion(region).
        // 云盒数据域名，格式为 CloudboxId.Region.oss-cloudbox.aliyuncs.com。
        WithEndpoint("cb-xxxx.cn-hangzhou.oss-cloudbox.aliyuncs.com").
        // 云盒 ID。
        WithCloudBoxId("cb-xxxx")

    client := oss.NewClient(cfg)

    // 创建存储空间（Bucket），Bucket 名称需全局唯一。
    result, err := client.PutBucket(context.TODO(), &oss.PutBucketRequest{
        Bucket: oss.Ptr("examplebucket"),
    })
    if err != nil {
        log.Fatalf("failed to put bucket %v", err)
    }
    log.Printf("put bucket result:%#v\n", result)
}

使用命令行工具ossutil

关于使用ossutil创建云盒Bucket的具体步骤，请参见put-bucket。

使用REST API

如果您的程序自定义要求较高，您可以直接发起REST API请求。直接发起REST API请求需要手动编写代码计算签名。更多信息，请参见PutBucket。

步骤二：上传Object

使用阿里云SDK

支持通过Java、Python、Go SDK将本地文件上传至云盒Bucket（Java SDK要求3.15.0及以上版本，Python SDK V2要求1.1.1及以上版本，Go SDK V2要求v1.2.1及以上版本）。云盒场景下，Python、Go SDK的操作调用方式与公共云OSS一致，创建客户端的方式请参见SDK支持。

Java

import com.aliyun.oss.ClientException;
import com.aliyun.oss.OSS;
import com.aliyun.oss.OSSClientBuilder;
import com.aliyun.oss.OSSException;
import com.aliyun.oss.model.PutObjectRequest;
import java.io.File;
import com.aliyun.oss.common.auth.DefaultCredentialProvider;
import com.aliyun.oss.common.comm.SignVersion;
import com.aliyun.oss.ClientBuilderConfiguration;
import com.aliyun.oss.common.auth.CredentialsProviderFactory;
import com.aliyun.oss.common.auth.EnvironmentVariableCredentialsProvider;

public class Demo {

    public static void main(String[] args) throws Exception {
        // 填写云盒Bucket的数据域名。
        String endpoint = "https://cb-f8z7yvzgwfkl9q0h****.cn-hangzhou.oss-cloudbox.aliyuncs.com";
        // 从环境变量中获取访问凭证。运行本代码示例之前，请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
        EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
        // 填写云盒Bucket名称，例如examplebucket。
        String bucketName = "examplebucket";
        // 填写云盒Bucket所在地域。
        String region = "cn-hangzhou";
        // 填写云盒ID。
        String cloudBoxId = "cb-f8z7yvzgwfkl9q0h****";
        // 填写Object完整路径，完整路径中不能包含Bucket名称，例如exampledir/exampleobject.txt。
        String objectName = "exampledir/exampleobject.txt";
        // 填写本地文件的完整路径，例如D:\\localpath\\examplefile.txt。
        // 如果未指定本地路径，则默认从示例程序所属项目对应本地路径中上传文件。
        String filePath= "D:\\localpath\\examplefile.txt";

        // 创建OSSClient实例。
        // 当OSSClient实例不再使用时，调用shutdown方法以释放资源。
        ClientBuilderConfiguration conf = new ClientBuilderConfiguration();
        conf.setSignatureVersion(SignVersion.V4);
        OSS ossClient = OSSClientBuilder.create()
                .endpoint(endpoint)
                .credentialsProvider(new DefaultCredentialProvider(credentialsProvider.getCredentials()))
                .clientConfiguration(conf)
                .region(region)
                .cloudBoxId(cloudBoxId)
                .build();

        try {
            // 创建PutObjectRequest对象。
            PutObjectRequest putObjectRequest = new PutObjectRequest(bucketName, objectName, new File(filePath));
            // 如果需要上传时设置存储类型和访问权限，请参考以下示例代码。
            // ObjectMetadata metadata = new ObjectMetadata();
            // metadata.setHeader(OSSHeaders.OSS_STORAGE_CLASS, StorageClass.Standard.toString());
            // metadata.setObjectAcl(CannedAccessControlList.Private);
            // putObjectRequest.setMetadata(metadata);

            // 上传文件。
            ossClient.putObject(putObjectRequest);
        } catch (OSSException oe) {
            System.out.println("Caught an OSSException, which means your request made it to OSS, "
                    + "but was rejected with an error response for some reason.");
            System.out.println("Error Message:" + oe.getErrorMessage());
            System.out.println("Error Code:" + oe.getErrorCode());
            System.out.println("Request ID:" + oe.getRequestId());
            System.out.println("Host ID:" + oe.getHostId());
        } catch (ClientException ce) {
            System.out.println("Caught an ClientException, which means the client encountered "
                    + "a serious internal problem while trying to communicate with OSS, "
                    + "such as not being able to access the network.");
            System.out.println("Error Message:" + ce.getMessage());
        } finally {
            if (ossClient != null) {
                ossClient.shutdown();
            }
        }
    }
}

Python

import alibabacloud_oss_v2 as oss

# 从环境变量获取访问凭证，运行前请先配置 OSS_ACCESS_KEY_ID 和 OSS_ACCESS_KEY_SECRET。
credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()
cfg = oss.config.load_default()
cfg.credentials_provider = credentials_provider
# 云盒所在地域，例如 cn-hangzhou。
cfg.region = "cn-hangzhou"
# 云盒数据域名，格式为 CloudboxId.Region.oss-cloudbox.aliyuncs.com。
cfg.endpoint = "cb-xxxx.cn-hangzhou.oss-cloudbox.aliyuncs.com"
# 云盒 ID。
cfg.cloud_box_id = "cb-xxxx"

client = oss.Client(cfg)

# 上传数据到指定 Object。
result = client.put_object(oss.PutObjectRequest(
    bucket="examplebucket",
    key="exampledir/exampleobject.txt",
    body=b"Hello OSS",
))
print(f"status code: {result.status_code}, etag: {result.etag}")

package main

import (
    "context"
    "log"
    "strings"

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

func main() {
    // 云盒所在地域，例如 cn-hangzhou。
    region := "cn-hangzhou"

    // 从环境变量获取访问凭证，运行前请先配置 OSS_ACCESS_KEY_ID 和 OSS_ACCESS_KEY_SECRET。
    cfg := oss.LoadDefaultConfig().
        WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
        WithRegion(region).
        // 云盒数据域名，格式为 CloudboxId.Region.oss-cloudbox.aliyuncs.com。
        WithEndpoint("cb-xxxx.cn-hangzhou.oss-cloudbox.aliyuncs.com").
        // 云盒 ID。
        WithCloudBoxId("cb-xxxx")

    client := oss.NewClient(cfg)

    // 上传数据到指定 Object。
    result, err := client.PutObject(context.TODO(), &oss.PutObjectRequest{
        Bucket: oss.Ptr("examplebucket"),
        Key:    oss.Ptr("exampledir/exampleobject.txt"),
        Body:   strings.NewReader("Hello OSS"),
    })
    if err != nil {
        log.Fatalf("failed to put object %v", err)
    }
    log.Printf("put object result:%#v\n", result)
}

使用命令行工具ossutil

关于使用ossutil简单上传的具体操作，请参见cp（上传文件）。

使用REST API

如果您的程序自定义要求较高，您可以直接发起REST API请求。直接发起REST API请求需要手动编写代码计算签名。更多信息，请参见PutObject。

步骤三：下载Object

使用阿里云SDK

支持通过Java、Python、Go SDK下载Object（Java SDK要求3.15.0及以上版本，Python SDK V2要求1.1.1及以上版本，Go SDK V2要求v1.2.1及以上版本）。云盒场景下，Python、Go SDK的操作调用方式与公共云OSS一致，创建客户端的方式请参见SDK支持。以下代码示例分别以Java、Python、Go SDK为例。

Java

package com.aliyun.oss.demo;

import com.aliyun.oss.ClientException;
import com.aliyun.oss.OSS;
import com.aliyun.oss.common.auth.*;
import com.aliyun.oss.OSSClientBuilder;
import com.aliyun.oss.OSSException;
import com.aliyun.oss.model.GetObjectRequest;
import java.io.File;
import com.aliyun.oss.common.auth.DefaultCredentialProvider;
import com.aliyun.oss.common.comm.SignVersion;
import com.aliyun.oss.ClientBuilderConfiguration;
import com.aliyun.oss.common.auth.CredentialsProviderFactory;
import com.aliyun.oss.common.auth.EnvironmentVariableCredentialsProvider;

public class Demo {

    public static void main(String[] args) throws Exception {
        // 填写云盒Bucket的数据域名。
        String endpoint = "https://cb-f8z7yvzgwfkl9q0h****.cn-hangzhou.oss-cloudbox.aliyuncs.com";
        // 从环境变量中获取访问凭证。运行本代码示例之前，请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
        EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
        // 填写云盒Bucket名称，例如examplebucket。
        String bucketName = "examplebucket";
        // 填写云盒Bucket所在地域。
        String region = "cn-hangzhou";
        // 填写云盒ID。
        String cloudBoxId = "cb-f8z7yvzgwfkl9q0h****";
        // 填写Object完整路径，完整路径中不能包含Bucket名称，例如exampledir/exampleobject.txt。
        String objectName = "exampledir/exampleobject.txt";
        // 填写本地文件完整路径。
        String pathName = "D:\\localpath\\examplefile.txt";

        // 创建OSSClient实例。
        // 当OSSClient实例不再使用时，调用shutdown方法以释放资源。
        ClientBuilderConfiguration conf = new ClientBuilderConfiguration();
        conf.setSignatureVersion(SignVersion.V4);
        OSS ossClient = OSSClientBuilder.create()
                .endpoint(endpoint)
                .credentialsProvider(new DefaultCredentialProvider(credentialsProvider.getCredentials()))
                .clientConfiguration(conf)
                .region(region)
                .cloudBoxId(cloudBoxId)
                .build();

        try {
            // 下载Object到本地文件，并保存到指定的本地路径中。如果指定的本地文件存在会覆盖，不存在则新建。
            // 如果未指定本地路径，则下载后的文件默认保存到示例程序所属项目对应本地路径中。
            ossClient.getObject(new GetObjectRequest(bucketName, objectName), new File(pathName));
        } catch (OSSException oe) {
            System.out.println("Caught an OSSException, which means your request made it to OSS, "
                    + "but was rejected with an error response for some reason.");
            System.out.println("Error Message:" + oe.getErrorMessage());
            System.out.println("Error Code:" + oe.getErrorCode());
            System.out.println("Request ID:" + oe.getRequestId());
            System.out.println("Host ID:" + oe.getHostId());
        } catch (ClientException ce) {
            System.out.println("Caught an ClientException, which means the client encountered "
                    + "a serious internal problem while trying to communicate with OSS, "
                    + "such as not being able to access the network.");
            System.out.println("Error Message:" + ce.getMessage());
        } finally {
            if (ossClient != null) {
                ossClient.shutdown();
            }
        }
    }
}

Python

import alibabacloud_oss_v2 as oss

# 从环境变量获取访问凭证，运行前请先配置 OSS_ACCESS_KEY_ID 和 OSS_ACCESS_KEY_SECRET。
credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()
cfg = oss.config.load_default()
cfg.credentials_provider = credentials_provider
# 云盒所在地域，例如 cn-hangzhou。
cfg.region = "cn-hangzhou"
# 云盒数据域名，格式为 CloudboxId.Region.oss-cloudbox.aliyuncs.com。
cfg.endpoint = "cb-xxxx.cn-hangzhou.oss-cloudbox.aliyuncs.com"
# 云盒 ID。
cfg.cloud_box_id = "cb-xxxx"

client = oss.Client(cfg)

# 下载 Object 到本地文件。
result = client.get_object_to_file(oss.GetObjectRequest(
    bucket="examplebucket",
    key="exampledir/exampleobject.txt",
), "download.txt")
print(f"status code: {result.status_code}, content length: {result.content_length}")

package main

import (
    "context"
    "io"
    "log"

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

func main() {
    // 云盒所在地域，例如 cn-hangzhou。
    region := "cn-hangzhou"

    // 从环境变量获取访问凭证，运行前请先配置 OSS_ACCESS_KEY_ID 和 OSS_ACCESS_KEY_SECRET。
    cfg := oss.LoadDefaultConfig().
        WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
        WithRegion(region).
        // 云盒数据域名，格式为 CloudboxId.Region.oss-cloudbox.aliyuncs.com。
        WithEndpoint("cb-xxxx.cn-hangzhou.oss-cloudbox.aliyuncs.com").
        // 云盒 ID。
        WithCloudBoxId("cb-xxxx")

    client := oss.NewClient(cfg)

    // 下载指定 Object。
    result, err := client.GetObject(context.TODO(), &oss.GetObjectRequest{
        Bucket: oss.Ptr("examplebucket"),
        Key:    oss.Ptr("exampledir/exampleobject.txt"),
    })
    if err != nil {
        log.Fatalf("failed to get object %v", err)
    }
    defer result.Body.Close()
    data, _ := io.ReadAll(result.Body)
    log.Printf("get object content length:%d\n", len(data))
}

使用命令行工具ossutil

关于使用ossutil简单下载的具体操作，请参见cp（下载文件）。

使用REST API

如果您的程序自定义要求较高，您可以直接发起REST API请求。直接发起REST API请求需要手动编写代码计算签名。更多信息，请参见GetObject。