DocsICP FilingConsole
Documentation
Home Page Object Storage Service Developer Reference SDK reference OSS SDK for Java 2.0 (preview) Agentic Bucket (OSS SDK for Java 2.0)

Agentic Bucket (OSS SDK for Java 2.0)

Updated at:
Copy as MD
Product
My Favorites

This topic describes how to use the OSS SDK for Java 2.0 to create and manage Agentic Buckets, bind and unbind wildcard CNAMEs, and create Bucket Spaces and upload objects.

Usage notes

  • To use Agentic Bucket features, you must install alibabacloud-oss-v2 (OSS SDK for Java 2.0).

  • The sample code in this topic uses the region ID cn-hangzhou of the China (Hangzhou) region as an example and uses the public endpoint by default. To access OSS from other Alibaba Cloud services in the same region as OSS, use the internal endpoint. For more information about the mappings between the regions and endpoints supported by OSS, see Regions and endpoints.

  • When you use the OSSAgenticBucketClient or BucketSpaceClient, you must set both of the following in the client builder: region and accountId. In the request, the bucket parameter is the bucket name prefix, and the SDK automatically resolves it to the full name. The full name of an Agentic Bucket is {prefix}-{accountId}-{region}-ab-apsr, and the full name of a Bucket Space is {prefix}-{accountId}-{region}-bs-apsr.

  • You can access a Bucket Space in either of the following ways: Use BucketSpaceClient. In the request, the bucket parameter is set to the Bucket Space name prefix, and the SDK automatically resolves it to the full name. Or, use BucketSpaceHelper and the standard client OSSClient. First, call its toBucketName method to convert the name prefix to the full name, and then access the Bucket Space through the standard client. In this case, the bucket parameter in the request must be set to the full name. When you use BucketSpaceHelper, you must also provide accountId and region.

  • CNAME-related operations (creating a CnameToken, getting a CnameToken, binding a CNAME, listing CNAMEs, and deleting a CNAME) are provided by the standard client OSSClient. In the request, the bucket parameter must be set to the full name of the Agentic Bucket, which is {prefix}-{accountId}-{region}-ab-apsr.

  • In wildcard CNAME requests, the domain or cname parameter must be set to the base domain name (without the *. prefix). The base domain name must contain at least three segments (for example, example.com is invalid, and foo.example.com is valid). Before you bind a wildcard CNAME, you must apply for a CnameToken for the base domain name and complete domain ownership verification. If you bind a certificate, the certificate must be a wildcard certificate that matches *.base-domain. For more information about the complete rules for wildcard CNAMEs, see PutCname.

Sample code

Create an Agentic Bucket

The following code creates an 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);
        }
    }
}

Query Agentic Bucket information

The following code queries the information about a specified 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);
        }
    }
}

List Agentic Buckets

The following code lists all Agentic Buckets of the current account in a specified region.

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);
        }
    }
}

Delete an Agentic Bucket

The following code deletes a specified 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);
        }
    }
}

Create a CnameToken (wildcard domain name)

The following code applies for a CnameToken for the base domain name of a wildcard CNAME on an Agentic Bucket.

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);
        }
    }
}

Get a CnameToken (wildcard domain name)

The following code gets the CnameToken of a wildcard CNAME on an Agentic Bucket.

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);
        }
    }
}

Bind a wildcard CNAME

The following code binds a wildcard CNAME to an Agentic Bucket.

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);
        }
    }
}

List CNAME records

The following code lists the CNAME records of an Agentic Bucket.

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);
        }
    }
}

Delete a wildcard CNAME

The following code deletes a wildcard CNAME from an Agentic Bucket.

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);
        }
    }
}

Create a Bucket Space

The following code creates a Bucket Space under a specified Agentic Bucket. The SDK provides two ways to access a Bucket Space. The following samples demonstrate each way, and you can choose one as needed.

Method 1: Use BucketSpaceClient. In the request, the bucket parameter is set to the Bucket Space name prefix.

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);
        }
    }
}

Method 2: Use BucketSpaceHelper and the standard client OSSClient. In the request, the bucket parameter is set to the converted full name of the Bucket Space.

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);
        }
    }
}

Upload an object to a Bucket Space

The following code uploads an object to a specified Bucket Space. The following samples demonstrate the two access methods.

Method 1: Use BucketSpaceClient. In the request, the bucket parameter is set to the Bucket Space name prefix.

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);
        }
    }
}

Method 2: Use BucketSpaceHelper and the standard client OSSClient. In the request, the bucket parameter is set to the converted full name of the Bucket Space.

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);
        }
    }
}
Previous：Logging (Java SDK V2)Next：AI VibeFlow (Java SDK V2)