API | Operation | Description |
Querying an object list | Queries some or all objects in a bucket | |
Querying objects and their version history | Queries some or all the objects in a bucket and their version history. |
// Create a COSClient instance, which is used to initiate requests later.COSClient createCOSClient() {// Set the user identity information.// Log in to the [CAM console](https://console.tencentcloud.com/cam/capi) to view and manage the `SecretId` and `SecretKey` of your project.String secretId = "SECRETID";String secretKey = "SECRETKEY";COSCredentials cred = new BasicCOSCredentials(secretId, secretKey);// `ClientConfig` contains the COS client configuration for subsequent COS requests.ClientConfig clientConfig = new ClientConfig();// Set the bucket region.// For more information on COS regions, please visit https://www.tencentcloud.com/document/product/436/6224.clientConfig.setRegion(new Region("COS_REGION"));// Set the request protocol, `http` or `https`.// For 5.6.53 and earlier versions, HTTPS is recommended.// Starting from 5.6.54, HTTPS is used by default.clientConfig.setHttpProtocol(HttpProtocol.https);// The following settings are optional.// Set the read timeout period, which is 30s by default.clientConfig.setSocketTimeout(30*1000);// Set the connection timeout period, which is 30s by default.clientConfig.setConnectionTimeout(30*1000);// If necessary, set the HTTP proxy, IP, and port.clientConfig.setHttpProxyIp("httpProxyIp");clientConfig.setHttpProxyPort(80);// Generate a COS client.return new COSClient(cred, clientConfig);}
// Create a COSClient instance, which is used to initiate requests later.COSClient createCOSClient() {// Here, the temporary key information is needed.// For how to generate temporary keys, please visit https://www.tencentcloud.com/document/product/436/14048.String tmpSecretId = "TMPSECRETID";String tmpSecretKey = "TMPSECRETKEY";String sessionToken = "SESSIONTOKEN";COSCredentials cred = new BasicSessionCredentials(tmpSecretId, tmpSecretKey, sessionToken);// `ClientConfig` contains the COS client configuration for subsequent COS requests.ClientConfig clientConfig = new ClientConfig();// Set the bucket region.// For more information on COS regions, please visit https://www.tencentcloud.com/document/product/436/6224.clientConfig.setRegion(new Region("COS_REGION"));// Set the request protocol, `http` or `https`.// For 5.6.53 and earlier versions, HTTPS is recommended.// Starting from 5.6.54, HTTPS is used by default.clientConfig.setHttpProtocol(HttpProtocol.https);// The following settings are optional.// Set the read timeout period, which is 30s by default.clientConfig.setSocketTimeout(30*1000);// Set the connection timeout period, which is 30s by default.clientConfig.setConnectionTimeout(30*1000);// If necessary, set the HTTP proxy, IP, and port.clientConfig.setHttpProxyIp("httpProxyIp");clientConfig.setHttpProxyPort(80);// Generate a COS client.return new COSClient(cred, clientConfig);}
public ObjectListing listObjects(ListObjectsRequest listObjectsRequest) throws CosClientException, CosServiceException;
// Before using the COS API, ensure that the process contains a COSClient instance. If such an instance does not exist, create one.// For the detailed code, see "Simple Operations -> Creating a COSClient instance" on the current page.COSClient cosClient = createCOSClient();// Enter the bucket name in the format of `BucketName-APPID`.String bucketName = "examplebucket-1250000000";ListObjectsRequest listObjectsRequest = new ListObjectsRequest();// Set the bucket namelistObjectsRequest.setBucketName(bucketName);// Set to use `prefix` as the prefix of objected listed.listObjectsRequest.setPrefix("");// Set the maximum number of listed objects (up to 1,000 per `listobject` request).listObjectsRequest.setMaxKeys(1000);// Save the list result.ObjectListing objectListing = null;try {objectListing = cosclient.listObjects(listObjectsRequest);} catch (CosServiceException e) {e.printStackTrace();} catch (CosClientException e) {e.printStackTrace();}// `object summary` is the list of objects listed this time.List<COSObjectSummary> cosObjectSummaries = objectListing.getObjectSummaries();for (COSObjectSummary cosObjectSummary : cosObjectSummaries) {// Object key.String key = cosObjectSummary.getKey();// Object ETag.String etag = cosObjectSummary.getETag();// Object lengthlong fileSize = cosObjectSummary.getSize();// Object storage classString storageClasses = cosObjectSummary.getStorageClass();}if (objectListing.isTruncated()) {// Indicates not all objects are listed and the list is truncated.// Next start position.String nextMarker = objectListing.getNextMarker();}// After confirming that the process does not use the COSClient instance anymore, close it.cosClient.shutdown();
Parameter | Description | Type |
listObjectsRequest | Request for obtaining a file list | ListObjectsRequest |
Request Member | Setting Method | Description | Type |
bucketName | Constructor or set method | String | |
prefix | Constructor or set method | Returns objects prefixed with this value. Default value: "" (left empty), meaning to return all objects in the bucket | String |
marker | Constructor or set method | Marks the starting object of the list. It can be left empty for the first request, but for subsequent requests, it should be set to the nextMarker value in the previous listObjects response | String |
delimiter | Constructor or set method | Indicates that paths that start with the specified "prefix" and end with the first occurrence of the delimiter will be returned | String |
maxKeys | Constructor or set method | Maximum number of returned members (up to 1,000). Default value: 1000 | Integer |
ObjectListing
, including all members and nextMarker
. public ObjectListing listObjects(ListObjectsRequest listObjectsRequest) throws CosClientException, CosServiceException;
// Before using the COS API, ensure that the process contains a COSClient instance. If such an instance does not exist, create one.// For the detailed code, see "Simple Operations -> Creating a COSClient instance" on the current page.COSClient cosClient = createCOSClient();// Enter the bucket name in the format of `BucketName-APPID`.String bucketName = "examplebucket-1250000000";// Next start position.// Obtained by using the requesting the objects on the truncated list. For details, see "Listing objects on the first page" above.String nextMarker = "nextMarker";ListObjectsRequest listObjectsRequest = new ListObjectsRequest();// Set the bucket namelistObjectsRequest.setBucketName(bucketName);// Set to use `prefix` as the prefix of objected listed.listObjectsRequest.setPrefix("");// Set the maximum number of listed objects (up to 1,000 per `listobject` request).listObjectsRequest.setMaxKeys(1000);// Set the position for truncation.listObjectsRequest.setMarker(nextMarker);// Save the list result.ObjectListing objectListing = null;try {objectListing = cosclient.listObjects(listObjectsRequest);} catch (CosServiceException e) {e.printStackTrace();} catch (CosClientException e) {e.printStackTrace();}// `object summary` is the list of objects listed this time.List<COSObjectSummary> cosObjectSummaries = objectListing.getObjectSummaries();for (COSObjectSummary cosObjectSummary : cosObjectSummaries) {// Object key.String key = cosObjectSummary.getKey();// Object ETag.String etag = cosObjectSummary.getETag();// Object lengthlong fileSize = cosObjectSummary.getSize();// Object storage classString storageClasses = cosObjectSummary.getStorageClass();}if (objectListing.isTruncated()) {// Indicates not all objects are listed and the list is truncated.// Next start position.String nextMarker = objectListing.getNextMarker();}// After confirming that the process does not use the COSClient instance anymore, close it.cosClient.shutdown();
Parameter | Description | Type |
listObjectsRequest | Request for obtaining a file list | ListObjectsRequest |
Request Member | Setting Method | Description | Type |
bucketName | Constructor or set method | String | |
prefix | Constructor or set method | Returns objects prefixed with this value. Default value: "" (left empty), meaning to return all objects in the bucket | String |
marker | Constructor or set method | Marks the starting object of the list. It can be left empty for the first request, but for subsequent requests, it should be set to the nextMarker value in the previous listObjects response | String |
delimiter | Constructor or set method | Indicates that paths that start with the specified "prefix" and end with the first occurrence of the delimiter will be returned | String |
maxKeys | Constructor or set method | Maximum number of returned members (up to 1,000). Default value: 1000 | Integer |
ObjectListing
, including all members and nextMarker
. public ObjectListing listObjects(ListObjectsRequest listObjectsRequest) throws CosClientException, CosServiceException;
// Before using the COS API, ensure that the process contains a COSClient instance. If such an instance does not exist, create one.// For the detailed code, see "Simple Operations -> Creating a COSClient instance" on the current page.COSClient cosClient = createCOSClient();// Enter the bucket name in the format of `BucketName-APPID`.String bucketName = "examplebucket-1250000000";ListObjectsRequest listObjectsRequest = new ListObjectsRequest();// Set the bucket namelistObjectsRequest.setBucketName(bucketName);// `prefix` indicates to use `prefix` as the prefix of objected listed.// Here, enter the path of the listed directory relative to `bucket`.listObjectsRequest.setPrefix("/dir/");// `delimiter` is the directory truncation symbol. For example, `/` indicates that an object name with `/` is considered a level-1 directory.listObjectsRequest.setDelimiter("/");// Set the maximum number of objects to be traversed, which can be up to 1,000 in one listobject operationlistObjectsRequest.setMaxKeys(1000);// Save each list result.ObjectListing objectListing = null;do {try {objectListing = cosclient.listObjects(listObjectsRequest);} catch (CosServiceException e) {e.printStackTrace();return;} catch (CosClientException e) {e.printStackTrace();return;}// Save the subdirectories listed.List<String> commonPrefixes = objectListing.getCommonPrefixes();for (String commonPrefix : commonPrefixes) {System.out.println(commonPrefix);}// Save the list of listed objects.List<COSObjectSummary> cosObjectSummaries = objectListing.getObjectSummaries();for (COSObjectSummary cosObjectSummary : cosObjectSummaries) {// Object key.String key = cosObjectSummary.getKey();// Object ETag.String etag = cosObjectSummary.getETag();// Object lengthlong fileSize = cosObjectSummary.getSize();// Object storage classString storageClasses = cosObjectSummary.getStorageClass();}// Next start position.String nextMarker = objectListing.getNextMarker();listObjectsRequest.setMarker(nextMarker);} while (objectListing.isTruncated());// After confirming that the process does not use the COSClient instance anymore, close it.cosClient.shutdown();
Parameter | Description | Type |
listObjectsRequest | Request for obtaining a file list | ListObjectsRequest |
Request Member | Setting Method | Description | Type |
bucketName | Constructor or set method | String | |
prefix | Constructor or set method | Returns objects prefixed with this value. Default value: "" (left empty), meaning to return all objects in the bucket | String |
marker | Constructor or set method | Marks the starting object of the list. It can be left empty for the first request, but for subsequent requests, it should be set to the nextMarker value in the previous listObjects response | String |
delimiter | Constructor or set method | Indicates that paths that start with the specified "prefix" and end with the first occurrence of the delimiter will be returned | String |
maxKeys | Constructor or set method | Maximum number of returned members (up to 1,000). Default value: 1000 | Integer |
ObjectListing
, including all members and nextMarker
. public VersionListing listVersions(ListVersionsRequest listVersionsRequest)throws CosClientException, CosServiceException;
// Before using the COS API, ensure that the process contains a COSClient instance. If such an instance does not exist, create one.// For the detailed code, see "Simple Operations -> Creating a COSClient instance" on the current page.COSClient cosClient = createCOSClient();// Enter the bucket name in the format of `BucketName-APPID`.String bucketName = "examplebucket-1250000000";ListVersionsRequest listVersionsRequest = new ListVersionsRequest();// Set the bucket namelistVersionsRequest.setBucketName(bucketName);// `prefix` indicates to use `prefix` as the prefix of objected listed.// Here, enter the path of the listed directory relative to `bucket`.listVersionsRequest.setPrefix("");// `delimiter` is the directory truncation symbol. For example, `/` indicates that an object name with `/` is considered a level-1 directory.listVersionsRequest.setDelimiter("/");// Set the maximum number of objects to be traversed, which can be up to 1,000 in one listobject operationlistVersionsRequest.setMaxKeys(1000);VersionListing versionListing = null;do {try {versionListing = cosclient.listVersions(listVersionsRequest);} catch (CosServiceException e) {e.printStackTrace();return;} catch (CosClientException e) {e.printStackTrace();return;}List<COSVersionSummary> cosVersionSummaries = versionListing.getVersionSummaries();for (COSVersionSummary cosVersionSummary : cosVersionSummaries) {System.out.println(cosVersionSummary.getKey() + ":" + cosVersionSummary.getVersionId());}// The next start position has 2 flags: object name and object version.String keyMarker = versionListing.getNextKeyMarker();String versionIdMarker = versionListing.getNextVersionIdMarker();listVersionsRequest.setKeyMarker(keyMarker);listVersionsRequest.setVersionIdMarker(versionIdMarker);} while (versionListing.isTruncated());// After confirming that the process does not use the COSClient instance anymore, close it.cosClient.shutdown();
Parameter | Description | Type |
listVersionsRequest | Request for obtaining object version information | ListVersionsRequest |
Request Member | Setting Method | Description | Type |
bucketName | Constructor or set method | String | |
prefix | Constructor or set method | Returns objects prefixed with this value. Default value: "" (left empty), meaning to return all objects in the bucket | String |
keyMarker | Constructor or set method | Marks the starting object of the list. It can be left empty for the first request, but for subsequent requests, it should be set to the nextKeyMarker value in the previous listObjects response | String |
versionIdMarker | Constructor or set method | Marks the starting object of the list. It can be left empty for the first request, but for subsequent requests, it should be set to the nextVersionIdMarker value in the previous listObjects response | String |
delimiter | Constructor or set method | Indicates that paths that start with the specified "prefix" and end with the first occurrence of the delimiter will be returned | String |
maxResults | Constructor or set method | Maximum number of returned members (up to 1,000). Default value: 1000 | Integer |
ObjectListing
, including all members and nextKeyMarker
and nextVersionIdMarker
.
Was this page helpful?