AI 助理
文档备案控制台
官方文档
首页 对象存储 开发参考 SDK参考 OSS Java SDK V2 Agentic Bucket（Java SDK V2）

Agentic Bucket（Java SDK V2）

更新时间：
复制 MD 格式
产品详情
我的收藏

本文介绍如何使用OSS Java SDK V2完成Agentic Bucket的创建与管理、泛域名CNAME的绑定与解绑，以及Bucket Space的创建与文件上传。

注意事项

  • 使用Agentic Bucket相关功能，您需要安装0.6.0及以上版本的alibabacloud-oss-v2（Java SDK V2）。

  • 本文示例代码以华东1（杭州）的地域IDcn-hangzhou为例，默认使用外网Endpoint，如果您希望通过与OSS同地域的其他阿里云产品访问OSS，请使用内网Endpoint。关于OSS支持的Region与Endpoint的对应关系，请参见地域和Endpoint。

  • 使用OSSAgenticBucketClient或BucketSpaceClient时，必须在客户端构建器中同时设置region和accountId。请求中的bucket参数为Bucket名称前缀，SDK会自动将其解析为完整名称：Agentic Bucket对应的完整名称为{prefix}-{accountId}-{region}-ab-apsr，BucketSpace对应的完整名称为{prefix}-{accountId}-{region}-bs-apsr。

  • 访问BucketSpace有两种方式，可按需选择：一是使用BucketSpaceClient，请求中的bucket参数传入BucketSpace名称前缀，SDK自动将其解析为完整名称；二是使用BucketSpaceHelper和标准客户端OSSClient，先通过其toBucketName方法将名称前缀转换为完整名称，再通过标准客户端访问BucketSpace，此方式下请求中的bucket参数须传入完整名称。使用BucketSpaceHelper时，同样必须提供accountId和region。

  • CNAME相关操作（创建CnameToken、获取CnameToken、绑定CNAME、列举CNAME、删除CNAME）由标准客户端OSSClient提供，请求中的bucket参数须传入Agentic Bucket的完整名称，即{prefix}-{accountId}-{region}-ab-apsr。

  • 泛域名CNAME相关请求中，domain或cname参数须传入泛域名基础域（不含*.前缀），且基础域至少包含3段（例如example.com不合法，foo.example.com合法）。绑定泛域名CNAME前，需先为该基础域申请CnameToken并完成域名所有权验证；如果绑定证书，证书须为与*.基础域匹配的通配符证书。关于泛域名CNAME的完整规则，请参见PutCname。

示例代码

创建Agentic Bucket

以下代码用于创建Agentic Bucket。

import com.aliyun.sdk.service.oss2.agentic.OSSAgenticBucketClient;
import com.aliyun.sdk.service.oss2.agentic.models.*;
import com.aliyun.sdk.service.oss2.credentials.CredentialsProvider;
import com.aliyun.sdk.service.oss2.credentials.EnvironmentVariableCredentialsProvider;

public class CreateAgenticBucketSample {
    public static void main(String[] args) throws Exception {
        String region = "cn-hangzhou";
        String accountId = "1234567890123456";
        String bucket = "my-agentic";

        CredentialsProvider provider = new EnvironmentVariableCredentialsProvider();

        try (OSSAgenticBucketClient client = OSSAgenticBucketClient.newBuilder()
                .credentialsProvider(provider)
                .region(region)
                .accountId(accountId)
                .build()) {

            CreateAgenticBucketResult result = client.createAgenticBucket(CreateAgenticBucketRequest.newBuilder()
                    .bucket(bucket)
                    .createAgenticBucketConfiguration(CreateAgenticBucketConfiguration.newBuilder()
                            .storageClass("Standard")
                            .dataRedundancyType("LRS")
                            .build())
                    .build());

            System.out.printf("status code:%d, request id:%s%n",
                    result.statusCode(), result.requestId());

        } catch (Exception e) {
            System.out.printf("error:%n%s", e);
        }
    }
}

查询Agentic Bucket信息

以下代码用于查询指定Agentic Bucket的信息。

import com.aliyun.sdk.service.oss2.agentic.OSSAgenticBucketClient;
import com.aliyun.sdk.service.oss2.agentic.models.*;
import com.aliyun.sdk.service.oss2.credentials.CredentialsProvider;
import com.aliyun.sdk.service.oss2.credentials.EnvironmentVariableCredentialsProvider;

public class GetAgenticBucketSample {
    public static void main(String[] args) throws Exception {
        String region = "cn-hangzhou";
        String accountId = "1234567890123456";
        String bucket = "my-agentic";

        CredentialsProvider provider = new EnvironmentVariableCredentialsProvider();

        try (OSSAgenticBucketClient client = OSSAgenticBucketClient.newBuilder()
                .credentialsProvider(provider)
                .region(region)
                .accountId(accountId)
                .build()) {

            GetAgenticBucketResult result = client.getAgenticBucket(GetAgenticBucketRequest.newBuilder()
                    .bucket(bucket)
                    .build());

            AgenticBucketInfo info = result.agenticBucketInfo();
            if (info != null) {
                System.out.printf("agentic bucket: name:%s, region:%s, storage class:%s, status:%s, create time:%s%n",
                        info.name(), info.region(), info.storageClass(), info.status(), info.createTime());
            }

        } catch (Exception e) {
            System.out.printf("error:%n%s", e);
        }
    }
}

列举Agentic Bucket

以下代码用于列举当前账号在指定地域下的所有Agentic Bucket。

import com.aliyun.sdk.service.oss2.agentic.OSSAgenticBucketClient;
import com.aliyun.sdk.service.oss2.agentic.models.*;
import com.aliyun.sdk.service.oss2.credentials.CredentialsProvider;
import com.aliyun.sdk.service.oss2.credentials.EnvironmentVariableCredentialsProvider;

public class ListAgenticBucketsSample {
    public static void main(String[] args) throws Exception {
        String region = "cn-hangzhou";
        String accountId = "1234567890123456";

        CredentialsProvider provider = new EnvironmentVariableCredentialsProvider();

        try (OSSAgenticBucketClient client = OSSAgenticBucketClient.newBuilder()
                .credentialsProvider(provider)
                .region(region)
                .accountId(accountId)
                .build()) {

            ListAgenticBucketsIterable paginator = client.listAgenticBucketsPaginator(
                    ListAgenticBucketsRequest.newBuilder()
                            .build());

            for (ListAgenticBucketsResult result : paginator) {
                if (result.agenticBuckets() == null) {
                    continue;
                }
                for (AgenticBucketSummary info : result.agenticBuckets()) {
                    System.out.printf("agentic bucket: name:%s, storage class:%s, data redundancy type:%s, create time:%s%n",
                            info.name(), info.storageClass(), info.dataRedundancyType(), info.createTime());
                }
            }

        } catch (Exception e) {
            System.out.printf("error:%n%s", e);
        }
    }
}

删除Agentic Bucket

以下代码用于删除指定的Agentic Bucket。

import com.aliyun.sdk.service.oss2.agentic.OSSAgenticBucketClient;
import com.aliyun.sdk.service.oss2.agentic.models.*;
import com.aliyun.sdk.service.oss2.credentials.CredentialsProvider;
import com.aliyun.sdk.service.oss2.credentials.EnvironmentVariableCredentialsProvider;

public class DeleteAgenticBucketSample {
    public static void main(String[] args) throws Exception {
        String region = "cn-hangzhou";
        String accountId = "1234567890123456";
        String bucket = "my-agentic";

        CredentialsProvider provider = new EnvironmentVariableCredentialsProvider();

        try (OSSAgenticBucketClient client = OSSAgenticBucketClient.newBuilder()
                .credentialsProvider(provider)
                .region(region)
                .accountId(accountId)
                .build()) {

            DeleteAgenticBucketResult result = client.deleteAgenticBucket(DeleteAgenticBucketRequest.newBuilder()
                    .bucket(bucket)
                    .build());

            System.out.printf("status code:%d, request id:%s%n",
                    result.statusCode(), result.requestId());

        } catch (Exception e) {
            System.out.printf("error:%n%s", e);
        }
    }
}

创建CnameToken（泛域名）

以下代码用于为Agentic Bucket上的泛域名基础域申请CnameToken。

import com.aliyun.sdk.service.oss2.OSSClient;
import com.aliyun.sdk.service.oss2.OSSClientBuilder;
import com.aliyun.sdk.service.oss2.credentials.CredentialsProvider;
import com.aliyun.sdk.service.oss2.credentials.EnvironmentVariableCredentialsProvider;
import com.aliyun.sdk.service.oss2.models.*;

public class CreateCnameTokenSample {
    public static void main(String[] args) throws Exception {
        String region = "cn-hangzhou";
        String accountId = "1234567890123456";
        String bucketPrefix = "my-agentic";
        String domain = "foo.example.com";

        CredentialsProvider provider = new EnvironmentVariableCredentialsProvider();

        try (OSSClient client = OSSClient.newBuilder()
                .credentialsProvider(provider)
                .region(region)
                .build()) {

            String bucket = String.format("%s-%s-%s-ab-apsr", bucketPrefix, accountId, region);

            Cname cname = Cname.newBuilder()
                    .domain(domain)
                    .isWildCard(true)
                    .build();

            CreateCnameTokenRequest request = CreateCnameTokenRequest.newBuilder()
                    .bucket(bucket)
                    .bucketCnameConfiguration(BucketCnameConfiguration.newBuilder()
                            .cname(cname)
                            .build())
                    .build();

            CreateCnameTokenResult result = client.createCnameToken(request);

            System.out.printf("status code:%d, request id:%s%n",
                    result.statusCode(), result.requestId());
            System.out.printf("bucket:%s%n", result.cnameToken().bucket());
            System.out.printf("cname:%s%n", result.cnameToken().cname());
            System.out.printf("token:%s%n", result.cnameToken().token());

        } catch (Exception e) {
            System.out.printf("error:%n%s", e);
        }
    }
}

获取CnameToken（泛域名）

以下代码用于获取AgenticBucket上泛域名CNAME的CnameToken。

import com.aliyun.sdk.service.oss2.OSSClient;
import com.aliyun.sdk.service.oss2.OSSClientBuilder;
import com.aliyun.sdk.service.oss2.credentials.CredentialsProvider;
import com.aliyun.sdk.service.oss2.credentials.EnvironmentVariableCredentialsProvider;
import com.aliyun.sdk.service.oss2.models.*;

public class GetCnameTokenSample {
    public static void main(String[] args) throws Exception {
        String region = "cn-hangzhou";
        String accountId = "1234567890123456";
        String bucketPrefix = "my-agentic";
        String domain = "foo.example.com";

        CredentialsProvider provider = new EnvironmentVariableCredentialsProvider();

        try (OSSClient client = OSSClient.newBuilder()
                .credentialsProvider(provider)
                .region(region)
                .build()) {

            String bucket = String.format("%s-%s-%s-ab-apsr", bucketPrefix, accountId, region);

            GetCnameTokenRequest request = GetCnameTokenRequest.newBuilder()
                    .bucket(bucket)
                    .cname(domain)
                    .wildcard(true)
                    .build();

            GetCnameTokenResult result = client.getCnameToken(request);

            System.out.printf("status code:%d, request id:%s%n",
                    result.statusCode(), result.requestId());
            System.out.printf("cname:%s%n", result.cnameToken().cname());
            System.out.printf("token:%s%n", result.cnameToken().token());

        } catch (Exception e) {
            System.out.printf("error:%n%s", e);
        }
    }
}

绑定泛域名CNAME

以下代码用于为Agentic Bucket绑定泛域名CNAME。

import com.aliyun.sdk.service.oss2.OSSClient;
import com.aliyun.sdk.service.oss2.OSSClientBuilder;
import com.aliyun.sdk.service.oss2.credentials.CredentialsProvider;
import com.aliyun.sdk.service.oss2.credentials.EnvironmentVariableCredentialsProvider;
import com.aliyun.sdk.service.oss2.models.*;

public class PutCnameSample {
    public static void main(String[] args) throws Exception {
        String region = "cn-hangzhou";
        String accountId = "1234567890123456";
        String bucketPrefix = "my-agentic";
        String domain = "foo.example.com";

        CredentialsProvider provider = new EnvironmentVariableCredentialsProvider();

        try (OSSClient client = OSSClient.newBuilder()
                .credentialsProvider(provider)
                .region(region)
                .build()) {

            String bucket = String.format("%s-%s-%s-ab-apsr", bucketPrefix, accountId, region);

            Cname cname = Cname.newBuilder()
                    .domain(domain)
                    .isWildCard(true)
                    .build();

            PutCnameRequest request = PutCnameRequest.newBuilder()
                    .bucket(bucket)
                    .bucketCnameConfiguration(BucketCnameConfiguration.newBuilder()
                            .cname(cname)
                            .build())
                    .build();

            PutCnameResult result = client.putCname(request);

            System.out.printf("status code:%d, request id:%s%n",
                    result.statusCode(), result.requestId());

        } catch (Exception e) {
            System.out.printf("error:%n%s", e);
        }
    }
}

列举CNAME记录

以下代码用于列举AgenticBucket下的CNAME记录。

import com.aliyun.sdk.service.oss2.OSSClient;
import com.aliyun.sdk.service.oss2.OSSClientBuilder;
import com.aliyun.sdk.service.oss2.credentials.CredentialsProvider;
import com.aliyun.sdk.service.oss2.credentials.EnvironmentVariableCredentialsProvider;
import com.aliyun.sdk.service.oss2.models.*;
import java.util.List;

public class ListCnameSample {
    public static void main(String[] args) throws Exception {
        String region = "cn-hangzhou";
        String accountId = "1234567890123456";
        String bucketPrefix = "my-agentic";

        CredentialsProvider provider = new EnvironmentVariableCredentialsProvider();

        try (OSSClient client = OSSClient.newBuilder()
                .credentialsProvider(provider)
                .region(region)
                .build()) {

            String bucket = String.format("%s-%s-%s-ab-apsr", bucketPrefix, accountId, region);

            ListCnameResult result = client.listCname(ListCnameRequest.newBuilder()
                    .bucket(bucket)
                    .build());

            System.out.printf("status code:%d, request id:%s%n",
                    result.statusCode(), result.requestId());

            List<CnameInfo> cnames = result.cnames();
            if (cnames != null) {
                for (CnameInfo info : cnames) {
                    System.out.printf("domain:%s, status:%s, last modified time:%s%n",
                            info.domain(), info.status(), info.lastModified());
                }
            }

        } catch (Exception e) {
            System.out.printf("error:%n%s", e);
        }
    }
}

删除泛域名CNAME

以下代码用于删除Agentic Bucket上的泛域名CNAME。

import com.aliyun.sdk.service.oss2.OSSClient;
import com.aliyun.sdk.service.oss2.OSSClientBuilder;
import com.aliyun.sdk.service.oss2.credentials.CredentialsProvider;
import com.aliyun.sdk.service.oss2.credentials.EnvironmentVariableCredentialsProvider;
import com.aliyun.sdk.service.oss2.models.*;

public class DeleteCnameSample {
    public static void main(String[] args) throws Exception {
        String region = "cn-hangzhou";
        String accountId = "1234567890123456";
        String bucketPrefix = "my-agentic";
        String domain = "foo.example.com";

        CredentialsProvider provider = new EnvironmentVariableCredentialsProvider();

        try (OSSClient client = OSSClient.newBuilder()
                .credentialsProvider(provider)
                .region(region)
                .build()) {

            String bucket = String.format("%s-%s-%s-ab-apsr", bucketPrefix, accountId, region);

            Cname cname = Cname.newBuilder()
                    .domain(domain)
                    .isWildCard(true)
                    .build();

            DeleteCnameRequest request = DeleteCnameRequest.newBuilder()
                    .bucket(bucket)
                    .bucketCnameConfiguration(BucketCnameConfiguration.newBuilder()
                            .cname(cname)
                            .build())
                    .build();

            DeleteCnameResult result = client.deleteCname(request);

            System.out.printf("status code:%d, request id:%s%n",
                    result.statusCode(), result.requestId());

        } catch (Exception e) {
            System.out.printf("error:%n%s", e);
        }
    }
}

创建BucketSpace

以下代码用于在指定的AgenticBucket下创建BucketSpace。SDK提供两种访问BucketSpace的方式，以下示例分别演示，您可按需选择。

方式一：使用BucketSpaceClient，请求中的bucket参数传入BucketSpace名称前缀。

import com.aliyun.sdk.service.oss2.ClientConfiguration;
import com.aliyun.sdk.service.oss2.OSSClient;
import com.aliyun.sdk.service.oss2.agentic.BucketSpaceClient;
import com.aliyun.sdk.service.oss2.credentials.CredentialsProvider;
import com.aliyun.sdk.service.oss2.credentials.EnvironmentVariableCredentialsProvider;
import com.aliyun.sdk.service.oss2.models.*;

public class BucketSpacePutBucketSample {
    public static void main(String[] args) throws Exception {
        String region = "cn-hangzhou";
        String accountId = "1234567890123456";
        String agenticBucketPrefix = "my-agentic";
        String bucketSpacePrefix = "my-space";

        CredentialsProvider provider = new EnvironmentVariableCredentialsProvider();

        try (OSSClient client = BucketSpaceClient.create(ClientConfiguration.newBuilder()
                .credentialsProvider(provider)
                .region(region)
                .accountId(accountId)
                .build())) {

            PutBucketResult result = client.putBucket(PutBucketRequest.newBuilder()
                    .bucket(bucketSpacePrefix)
                    .agenticBucket(String.format("%s-%s-%s-ab-apsr", agenticBucketPrefix, accountId, region))
                    .build());

            System.out.printf("status code:%d, request id:%s%n",
                    result.statusCode(), result.requestId());

        } catch (Exception e) {
            System.out.printf("error:%n%s", e);
        }
    }
}

方式二：使用BucketSpaceHelper和标准客户端OSSClient，请求中的bucket参数传入转换后的BucketSpace完整名称。

import com.aliyun.sdk.service.oss2.OSSClient;
import com.aliyun.sdk.service.oss2.OSSClientBuilder;
import com.aliyun.sdk.service.oss2.agentic.BucketSpaceHelper;
import com.aliyun.sdk.service.oss2.credentials.CredentialsProvider;
import com.aliyun.sdk.service.oss2.credentials.EnvironmentVariableCredentialsProvider;
import com.aliyun.sdk.service.oss2.models.*;

public class BucketSpacePutBucketWithHelperSample {
    public static void main(String[] args) throws Exception {
        String region = "cn-hangzhou";
        String accountId = "1234567890123456";
        String agenticBucketPrefix = "my-agentic";
        String bucketSpacePrefix = "my-space";

        CredentialsProvider provider = new EnvironmentVariableCredentialsProvider();

        try (OSSClient client = OSSClient.newBuilder()
                .credentialsProvider(provider)
                .region(region)
                .build()) {

            BucketSpaceHelper helper = new BucketSpaceHelper(accountId, region);

            PutBucketResult result = client.putBucket(PutBucketRequest.newBuilder()
                    .bucket(helper.toBucketName(bucketSpacePrefix))
                    .agenticBucket(String.format("%s-%s-%s-ab-apsr", agenticBucketPrefix, accountId, region))
                    .build());

            System.out.printf("status code:%d, request id:%s%n",
                    result.statusCode(), result.requestId());

        } catch (Exception e) {
            System.out.printf("error:%n%s", e);
        }
    }
}

向BucketSpace上传文件

以下代码用于向指定的BucketSpace上传文件（Object）。以下示例分别演示两种访问方式。

方式一：使用BucketSpaceClient，请求中的bucket参数传入BucketSpace名称前缀。

import com.aliyun.sdk.service.oss2.ClientConfiguration;
import com.aliyun.sdk.service.oss2.OSSClient;
import com.aliyun.sdk.service.oss2.agentic.BucketSpaceClient;
import com.aliyun.sdk.service.oss2.credentials.CredentialsProvider;
import com.aliyun.sdk.service.oss2.credentials.EnvironmentVariableCredentialsProvider;
import com.aliyun.sdk.service.oss2.models.*;

public class BucketSpacePutObjectSample {
    public static void main(String[] args) throws Exception {
        String region = "cn-hangzhou";
        String accountId = "1234567890123456";
        String bucketSpacePrefix = "my-space";
        String key = "exampleobject";

        CredentialsProvider provider = new EnvironmentVariableCredentialsProvider();

        try (OSSClient client = BucketSpaceClient.create(ClientConfiguration.newBuilder()
                .credentialsProvider(provider)
                .region(region)
                .accountId(accountId)
                .build())) {

            PutObjectResult result = client.putObject(PutObjectRequest.newBuilder()
                    .bucket(bucketSpacePrefix)
                    .key(key)
                    .body(BinaryData.fromString("Hello OSS"))
                    .build());

            System.out.printf("status code:%d, request id:%s, eTag:%s%n",
                    result.statusCode(), result.requestId(), result.eTag());

        } catch (Exception e) {
            System.out.printf("error:%n%s", e);
        }
    }
}

方式二：使用BucketSpaceHelper和标准客户端OSSClient，请求中的bucket参数传入转换后的BucketSpace完整名称。

import com.aliyun.sdk.service.oss2.OSSClient;
import com.aliyun.sdk.service.oss2.OSSClientBuilder;
import com.aliyun.sdk.service.oss2.agentic.BucketSpaceHelper;
import com.aliyun.sdk.service.oss2.credentials.CredentialsProvider;
import com.aliyun.sdk.service.oss2.credentials.EnvironmentVariableCredentialsProvider;
import com.aliyun.sdk.service.oss2.models.*;

public class BucketSpacePutObjectWithHelperSample {
    public static void main(String[] args) throws Exception {
        String region = "cn-hangzhou";
        String accountId = "1234567890123456";
        String bucketSpacePrefix = "my-space";
        String key = "exampleobject";

        CredentialsProvider provider = new EnvironmentVariableCredentialsProvider();

        try (OSSClient client = OSSClient.newBuilder()
                .credentialsProvider(provider)
                .region(region)
                .build()) {

            BucketSpaceHelper helper = new BucketSpaceHelper(accountId, region);

            PutObjectResult result = client.putObject(PutObjectRequest.newBuilder()
                    .bucket(helper.toBucketName(bucketSpacePrefix))
                    .key(key)
                    .body(BinaryData.fromString("Hello OSS"))
                    .build());

            System.out.printf("status code:%d, request id:%s, eTag:%s%n",
                    result.statusCode(), result.requestId(), result.eTag());

        } catch (Exception e) {
            System.out.printf("error:%n%s", e);
        }
    }
}
上一篇：日志转存（Java SDK V2）下一篇：AI VibeFlow（Java SDK V2）