tencent cloud

Cloud Object Storage

Release Notes and Announcements
Release Notes
Announcements
Product Introduction
Overview
Features
Use Cases
Strengths
Concepts
Regions and Access Endpoints
Specifications and Limits
Service Regions and Service Providers
Billing
Billing Overview
Billing Method
Billable Items
Free Tier
Billing Examples
Viewing and Downloading Bill
Payment Overdue
FAQs
Getting Started
Console
Getting Started with COSBrowser
User Guide
Creating Request
Bucket
Object
Data Management
Batch Operation
Global Acceleration
Monitoring and Alarms
Operations Center
Data Processing
Content Moderation
Smart Toolbox
Data Processing Workflow
Application Integration
User Tools
Tool Overview
Installation and Configuration of Environment
COSBrowser
COSCLI (Beta)
COSCMD
COS Migration
FTP Server
Hadoop
COSDistCp
HDFS TO COS
GooseFS-Lite
Online Tools
Diagnostic Tool
Use Cases
Overview
Access Control and Permission Management
Performance Optimization
Accessing COS with AWS S3 SDK
Data Disaster Recovery and Backup
Domain Name Management Practice
Image Processing
Audio/Video Practices
Workflow
Direct Data Upload
Content Moderation
Data Security
Data Verification
Big Data Practice
COS Cost Optimization Solutions
Using COS in the Third-party Applications
Migration Guide
Migrating Local Data to COS
Migrating Data from Third-Party Cloud Storage Service to COS
Migrating Data from URL to COS
Migrating Data Within COS
Migrating Data Between HDFS and COS
Data Lake Storage
Cloud Native Datalake Storage
Metadata Accelerator
GooseFS
Data Processing
Data Processing Overview
Image Processing
Media Processing
Content Moderation
File Processing Service
File Preview
Troubleshooting
Obtaining RequestId
Slow Upload over Public Network
403 Error for COS Access
Resource Access Error
POST Object Common Exceptions
API Documentation
Introduction
Common Request Headers
Common Response Headers
Error Codes
Request Signature
Action List
Service APIs
Bucket APIs
Object APIs
Batch Operation APIs
Data Processing APIs
Job and Workflow
Content Moderation APIs
Cloud Antivirus API
SDK Documentation
SDK Overview
Preparations
Android SDK
C SDK
C++ SDK
.NET(C#) SDK
Flutter SDK
Go SDK
iOS SDK
Java SDK
JavaScript SDK
Node.js SDK
PHP SDK
Python SDK
React Native SDK
Mini Program SDK
Error Codes
Harmony SDK
Endpoint SDK Quality Optimization
Security and Compliance
Data Disaster Recovery
Data Security
Cloud Access Management
FAQs
Popular Questions
General
Billing
Domain Name Compliance Issues
Bucket Configuration
Domain Names and CDN
Object Operations
Logging and Monitoring
Permission Management
Data Processing
Data Security
Pre-signed URL Issues
SDKs
Tools
APIs
Agreements
Service Level Agreement
Privacy Policy
Data Processing And Security Agreement
Contact Us
Glossary

Listing Objects

PDF
Mode fokus
Ukuran font
Terakhir diperbarui: 2024-02-02 15:51:37

Overview

This document provides an overview of APIs and SDK code samples for listing objects.
API
Operation
Description
Querying objects
Queries some or all the objects in a bucket.
Querying objects and their version history
Queries some or all the objects in a bucket and their version history.

Querying an Object List

Feature description

This API is used to query some or all the objects in a bucket.

Method prototype

func (s *BucketService) Get(ctx context.Context, opt *BucketGetOptions) (*BucketGetResult, *Response, error)

Sample 1: requesting the object list

package main

import (
"context"
"github.com/tencentyun/cos-go-sdk-v5"
"net/http"
"net/url"
"os"
)

func main(){
// Bucket name in the format of `BucketName-APPID` (`APPID` is required), which can be viewed in the COS console at https://console.tencentcloud.com/cos5/bucket.
// Replace it with your region, which can be viewed in the COS console at https://console.tencentcloud.com/. For more information about regions, visit https://www.tencentcloud.com/document/product/436/6224.
u, _ := url.Parse("https://examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com")
b := &cos.BaseURL{BucketURL: u}
client := cos.NewClient(b, &http.Client{
Transport: &cos.AuthorizationTransport{
// Get the key from environment variables
// Environment variable `SECRETID` refers to the user's `SecretId`, which can be viewed in the CAM console at https://console.tencentcloud.com/cam/capi.
SecretID: os.Getenv("SECRETID"), // User `SecretId`. We recommend you use a sub-account key and follow the principle of least privilege to reduce risks. For information about how to obtain a sub-account key, visit https://www.tencentcloud.com/document/product/598/37140?from_cn_redirect=1.
// Environment variable `SECRETKEY` refers to the user's `SecretKey`, which can be viewed in the CAM console at https://console.tencentcloud.com/cam/capi.
SecretKey: os.Getenv("SECRETKEY"), // User `SecretKey`. We recommend you use a sub-account key and follow the principle of least privilege to reduce risks. For information about how to obtain a sub-account key, visit https://www.tencentcloud.com/document/product/598/37140?from_cn_redirect=1.
},
})
opt := &cos.BucketGetOptions{
Prefix: "test",
MaxKeys: 100,
}
_, _, err := client.Bucket.Get(context.Background(), opt)
if err != nil{
panic(err)
}
}

Sample 2: listing all objects in a directory

COS does not have the concept of folder, but you can use slashes (/) as the delimiter to stimulate folders.
package main

import (
"context"
"github.com/tencentyun/cos-go-sdk-v5"
"net/http"
"net/url"
"os"
"fmt"
)

func main(){
// Bucket name in the format of `BucketName-APPID` (`APPID` is required), which can be viewed in the COS console at https://console.tencentcloud.com/cos5/bucket.
// Replace it with your region, which can be viewed in the COS console at https://console.tencentcloud.com/. For more information about regions, visit https://www.tencentcloud.com/document/product/436/6224.
u, _ := url.Parse("https://examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com")
b := &cos.BaseURL{BucketURL: u}
client := cos.NewClient(b, &http.Client{
Transport: &cos.AuthorizationTransport{
// Get the key from environment variables
// Environment variable `SECRETID` refers to the user's `SecretId`, which can be viewed in the CAM console at https://console.tencentcloud.com/cam/capi.
SecretID: os.Getenv("SECRETID"), // User `SecretId`. We recommend you use a sub-account key and follow the principle of least privilege to reduce risks. For information about how to obtain a sub-account key, visit https://www.tencentcloud.com/document/product/598/37140?from_cn_redirect=1.
// Environment variable `SECRETKEY` refers to the user's `SecretKey`, which can be viewed in the CAM console at https://console.tencentcloud.com/cam/capi.
SecretKey: os.Getenv("SECRETKEY"), // User `SecretKey`. We recommend you use a sub-account key and follow the principle of least privilege to reduce risks. For information about how to obtain a sub-account key, visit https://www.tencentcloud.com/document/product/598/37140?from_cn_redirect=1.
},
})
var marker string
opt := &cos.BucketGetOptions{
Prefix: "folder/", // `prefix` indicates the directory to query.
Delimiter: "/", // Set the `delimiter` to "/" to list objects in the current directory. To list all objects, leave this parameter empty.
MaxKeys: 1000, // Set the maximum number of traversed objects (up to 1,000 per `listobject` request).
}
isTruncated := true
for isTruncated {
opt.Marker = marker
v, _, err := client.Bucket.Get(context.Background(), opt)
if err != nil{
fmt.Println(err)
break
}
for _, content := range v.Contents {
fmt.Printf("Object: %v\\n", content.Key)
}
// `common prefix` indicates the paths that end with the `delimiter`. If the `delimiter` is set to "/", the `common prefix` indicates the paths of all subdirectories.
for _, commonPrefix := range v.CommonPrefixes {
fmt.Printf("CommonPrefixes: %v\\n", commonPrefix)
}
isTruncated = v.IsTruncated // Whether any data still exists
marker = v.NextMarker // Set the start `key` for the next request
}
}

Field description

type BucketGetOptions struct {
Prefix string
Delimiter string
EncodingType string
Marker string
MaxKeys int
}
Parameter
Description
Type
Required
Prefix
Filters the object keys prefixed with the value of this parameter. It is left empty by default.
String
No
Delimiter
A separator that is left empty by default. For example, you can specify it as / to indicate folders.
String
No
EncodingType
Specifies the encoding method of the returned value. It is left empty by default. Valid value: url.
String
No
Marker
Marks the starting point of the returned object list. Entries are listed in UTF-8 binary order by default.
String
No
MaxKeys
Maximum number of returned objects. Defaults to 1000.
Int
No

Response description

type BucketGetResult struct {
Name string
Prefix string
Marker string
NextMarker string
Delimiter string
MaxKeys int
IsTruncated bool
Contents []Object
CommonPrefixes []string
EncodingType string
}
Parameter
Description
Type
Name
Bucket name in the format of BucketName-APPID, such as examplebucket-1250000000.
String
Prefix
Filters the object keys prefixed with the value of this parameter. It is left empty by default.
String
Marker
Marks the starting point of the returned object list. Entries are listed in UTF-8 binary order by default.
String
NextMarker
Specifies the object after which the next listing should begin if IsTruncated is set to true.
String
Delimiter
A separator that is left empty by default. For example, you can specify it as / to indicate folders.
String
MaxKeys
Maximum number of returned objects. It defaults to 1000.
Int
IsTruncated
Indicates whether the returned objects are truncated
bool
Contents
Lists the metadata of all objects, including ETag, StorageClass, Key, Owner, LastModified, and Size.
[]Object
CommonPrefixes
Groups all keys starting with Prefix and ending with Delimiter as a common prefix.
[]string
EncodingType
Encoding type of the returned value. The returned value is not encoded by default. Valid value: url
String

Querying an Object Version List

Feature description

This API is used to query some or all objects in a versioning-enabled bucket.

Method prototype

func (s *BucketService) GetObjectVersions(ctx context.Context, opt *BucketGetObjectVersionsOptions) (*BucketGetObjectVersionsResult, *Response, error)

Sample: querying an object version list

//: # (.cssg-snippet-list-objects-versioning)
package main

import (
"context"
"fmt"
"github.com/tencentyun/cos-go-sdk-v5"
"net/http"
"net/url"
"os"
)

func main(){
// Bucket name in the format of `BucketName-APPID` (`APPID` is required), which can be viewed in the COS console at https://console.tencentcloud.com/cos5/bucket.
// Replace it with your region, which can be viewed in the COS console at https://console.tencentcloud.com/. For more information about regions, visit https://www.tencentcloud.com/document/product/436/6224.
u, _ := url.Parse("https://examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com")
b := &cos.BaseURL{BucketURL: u}
client := cos.NewClient(b, &http.Client{
Transport: &cos.AuthorizationTransport{
// Get the key from environment variables
// Environment variable `SECRETID` refers to the user's `SecretId`, which can be viewed in the CAM console at https://console.tencentcloud.com/cam/capi.
SecretID: os.Getenv("SECRETID"), // User `SecretId`. We recommend you use a sub-account key and follow the principle of least privilege to reduce risks. For information about how to obtain a sub-account key, visit https://www.tencentcloud.com/document/product/598/37140?from_cn_redirect=1.
// Environment variable `SECRETKEY` refers to the user's `SecretKey`, which can be viewed in the CAM console at https://console.tencentcloud.com/cam/capi.
SecretKey: os.Getenv("SECRETKEY"), // User `SecretKey`. We recommend you use a sub-account key and follow the principle of least privilege to reduce risks. For information about how to obtain a sub-account key, visit https://www.tencentcloud.com/document/product/598/37140?from_cn_redirect=1.
},
})
keyMarker := ""
versionIdMarker := ""
isTruncated := true
opt := &cos.BucketGetObjectVersionsOptions{}
for isTruncated {
opt.KeyMarker = keyMarker
opt.VersionIdMarker = versionIdMarker
v, _, err := client.Bucket.GetObjectVersions(context.Background(), opt)
if err != nil{
// ERROR
break
}
for _, vc := range v.Version {
fmt.Printf("Version: %v, %v, %v, %v\\n", vc.Key, vc.Size, vc.VersionId, vc.IsLatest)
}
for _, dc := range v.DeleteMarker {
fmt.Printf("DeleteMarker: %v, %v, %v\\n", dc.Key, dc.VersionId, dc.IsLatest)
}
keyMarker = v.NextKeyMarker
versionIdMarker = v.NextVersionIdMarker
isTruncated = v.IsTruncated
}
}

Field description

type BucketGetObjectVersionsOptions struct {
Prefix string
Delimiter string
EncodingType string
KeyMarker string
VersionIdMarker string
MaxKeys int
}
Field
Description
Type
Required
prefix
Key prefix to query objects by
String
No
delimiter
Character delimiter used to group object keys. Keys that contain identical paths between the prefix (or, if no prefix is specified, the beginning of the string) and the first delimiter are grouped and defined as a Prefix node under CommonPrefixes. The grouped object keys will no longer appear in the subsequent object list. For specific scenarios and usage, see the samples below.
String
No
encoding-type
Encoding type of the returned value. Valid value: url, meaning that the returned object keys are URL-encoded (percent-encoded) values. For example, "Tencent Cloud" will be encoded to %E8%85%BE%E8%AE%AF%E4%BA%91.
String
No
key-marker
Marker for the starting object key. Object version entries after this marker will be returned in UTF-8 lexicographical order.
String
No
version-id-marker
Marker for the starting version ID. Object version entries after this marker will be returned. If NextVersionIdMarker is empty in the last ListVersionsResult response, leave this parameter empty.
String
No
max-keys
Maximum number (up to 1,000) of keys returned in a response. Defaults to 1000. Note: This parameter limits the maximum number of keys (the sum of CommonPrefixes, Version, and DeleteMarker’) COS can return in each ListVersionsResult response. If not all objects are listed in a single response, COS will return the NextKeyMarker and NextVersionIdMarker nodes, the values of which can be used to specify key-marker and version-id-marker`, respectively, so that the remaining versions can be listed in your next request.
Int
No

Response description

type BucketGetObjectVersionsResult struct {
Name string
EncodingType string
Prefix string
KeyMarker string
VersionIdMarker string
MaxKeys int
Delimiter string
IsTruncated bool
NextKeyMarker string
NextVersionIdMarker string
CommonPrefixes []string
Version []ListVersionsResultVersion
DeleteMarker []ListVersionsResultDeleteMarker
}
type ListVersionsResultVersion struct {
Key string
VersionId string
IsLatest bool
LastModified string
ETag string
Size int
StorageClass string
Owner *Owner
}
type ListVersionsResultDeleteMarker struct {
Key string
VersionId string
IsLatest bool
LastModified string
Owner *Owner
}
The nodes are described as follows:
Node Name (Keyword)
Parent Node
Description
Type
ListVersionsResult
None
Stores the result of GET Bucket Object versions.
Container
Content of ListVersionsResult:
Node Name (Keyword)
Parent Node
Description
Type
EncodingType
ListVersionsResult
Encoding type, which corresponds to the encoding-type parameter in the request. This node will be returned only when the encoding-type parameter is specified in the request.
string
Name
ListVersionsResult
Bucket name in the format of <BucektName-APPID>, such as examplebucket-1250000000.
string
Prefix
ListVersionsResult
Filters the object keys prefixed with the value of this parameter.
string
KeyMarker
ListVersionsResult
Marks the object key to start with. Object version entries after the marker will be returned in UTF-8 lexicographical order. This node corresponds to the key-marker parameter in the request.
string
VersionIdMarker
ListVersionsResult
Marks the version ID to start with. Object version entries after the marker will be returned. This node corresponds to the version-id-marker parameter in the request.
string
MaxKeys
ListVersionsResult
Maximum number of keys returned in a single response. This node corresponds to the max-keys parameter in the request.
integer
IsTruncated
ListVersionsResult
Indicates whether the returned list is truncated. Valid values: true, false
boolean
NextKeyMarker
ListVersionsResult
This node will be returned only if the returned list is truncated (i.e., the value of IsTruncated is true). The value of this node is the last object key in the current response. If you need to request subsequent entries, the value can be passed in as the value of the key-marker parameter in the next request.
string
NextVersionIdMarker
ListVersionsResult
This node will be returned only if the returned list is truncated (i.e., the value of IsTruncated is true). The value of this node is the last version ID in the current response. If you need to request subsequent entries, the value can be passed in as the value of the version-id-marker parameter in the next request. If this node is left empty, version-id-marker in the next request should also be left empty.
string
Delimiter
ListVersionsResult
Delimiter, which corresponds to the delimiter parameter in the request and will be returned only if the delimiter parameter is specified in the request.
string
CommonPrefixes
ListVersionsResult
The identical paths between the prefix (or, if no prefix is specified, the beginning of the string) and the first delimiter are grouped and defined as a common prefix. This node will be returned only if the delimiter parameter is specified in the request.
Container
Version
ListVersionsResult
Object version entry.
Container
DeleteMarker
ListVersionsResult
Object delete marker entry.
Container
Content of CommonPrefixes:
Node Name (Keyword)
Parent Node
Description
Type
Prefix
ListVersionsResult.CommonPrefixes
A single common prefix
string
Content of Version:
Node Name (Keyword)
Parent Node
Description
Type
Key
ListVersionsResult.Version
Object key.
string
VersionId
ListVersionsResult.Version
Version ID of the object. If versioning is disabled, the value of this node is an empty string. If versioning is enabled, the value of this node is null for an object uploaded before you enable versioning. If versioning is suspended, the value of this node is null for an object uploaded after you suspend versioning. Note that each object can have only one object version whose ID is null.
string
IsLatest
ListVersionsResult.Version
Whether the current version is the latest one of the object.
boolean
LastModified
ListVersionsResult.Version
Last modified time of the current version, in ISO 8601 format (for example, 2019-05-24T10:56:40Z)
date
ETag
ListBucketResult.Contents
Entity tag of the object. It indicates the content of the object when it is created and can be used to verify whether the object content is changed. Example: "8e0b617ca298a564c3331da28dcb50df". The value of ETag is not necessarily the MD5 checksum of the object. The value will be different if the uploaded object is encrypted.
string
Size
ListVersionsResult.Version
Object size, in bytes.
integer
StorageClass
ListVersionsResult.Version
Object storage class, such as STANDARD_IA or ARCHIVE. For enumerated values, see Storage Class Overview.
Enum
StorageTier
ListVersionsResult.Version
Access tier (for INTELLIGENT TIERING) the object is currently stored in. Enumerated values: FREQUENT, INFREQUENT. This node is returned only when StorageClass is set to INTELLIGENT_TIERING.
Enum
Owner
ListVersionsResult.Version
Information of the object owner.
Container
Content of Version.Owner:
Node Name (Keyword)
Parent Node
Description
Type
ID
ListVersionsResult.Version.Owner
APPID of the object owner
string
DisplayName
ListVersionsResult.Version.Owner
Name of the object owner
string
Content of DeleteMarker:
Node Name (Keyword)
Parent Node
Description
Type
Key
ListVersionsResult.DeleteMarker
Object key.
string
VersionId
ListVersionsResult.DeleteMarker
Version ID of the object delete marker.
string
IsLatest
ListVersionsResult.DeleteMarker
Whether the current delete marker is the latest one of the object.
boolean
LastModified
ListVersionsResult.DeleteMarker
Last modified time of the current delete marker, in ISO 8601 format (for example, 2019-05-24T10:56:40Z)
date
Owner
ListVersionsResult.DeleteMarker
Information of the object owner.
Container
Content of DeleteMarker.Owner:
Node Name (Keyword)
Parent Node
Description
Type
ID
ListVersionsResult.DeleteMarker.Owner
APPID of the object owner
string
DisplayName
ListVersionsResult.DeleteMarker.Owner
Name of the object owner
string

Bantuan dan Dukungan

Apakah halaman ini membantu?

masukan