如何快速上手OSSON雲盒 - Object Storage Service

通過OSS ON雲盒，您可以對本機資料進行資料監控、資料處理等操作。OSS ON雲盒適用於業務要求低延時、多分公司統一管理等情境。本文介紹OSS ON雲盒的基本操作，包括建立雲盒Bucket、在Bucket中上傳檔案（Object）以及下載Object。

前提條件

僅華東1（杭州）、華東2（上海）、華南1（深圳）、華南2（河源）、華北2（北京）、西南1（成都）地區支援使用OSS ON雲盒服務。
已購買雲盒。
已在雲盒內建立Virtual Private Cloud和交換器。
已聯絡支援人員申請建立雲盒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。