Este tópico descreve como listar objetos em um bucket com versionamento ativado. Os exemplos incluem a listagem de todos os objetos, de objetos cujos nomes contêm um prefixo específico e de objetos e subpastas em uma pasta específica.
Observações
Este tópico utiliza o endpoint público da região China (Hangzhou). Para acessar o OSS a partir de outros serviços da Alibaba Cloud na mesma região, utilize um endpoint interno. Para mais informações sobre regiões e endpoints do OSS, consulte Regiões e endpoints.
As credenciais de acesso neste tópico são obtidas de variáveis de ambiente. Para saber mais sobre como configurar credenciais de acesso, consulte Configurar credenciais de acesso.
Este tópico demonstra a criação de uma instância OSSClient com um endpoint do OSS. Para configurações alternativas, como o uso de domínio personalizado ou autenticação com credenciais do Security Token Service (STS), consulte Configurar um cliente (Go SDK V1).
Para listar objetos, é necessária a permissão
oss:ListObjectVersions. Para mais detalhes, consulte Conceder uma política personalizada.
Cenários
A figura a seguir mostra as pastas e os objetos em um bucket chamado examplebucket.
examplebucket
└── fun
└── exampleobject.jpg
└── examplefile.txt
└── destfolder
└── image1.jpg
└── image2.png
└── srcfile.txt
└── oss.jpg
As seções a seguir descrevem como listar diferentes objetos mediante a especificação de condições.
Para mais informações sobre os parâmetros configuráveis durante a listagem de objetos, consulte ListObjectVersions (GetBucketVersions).
Código de exemplo
O código abaixo exemplifica como listar as versões de todos os objetos, incluindo marcadores de exclusão, em um bucket especificado:
package main
import (
"log"
"github.com/aliyun/aliyun-oss-go-sdk/oss"
)
func main() {
// Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured.
provider, err := oss.NewEnvironmentVariableCredentialsProvider()
if err != nil {
log.Fatalf("Failed to create credentials provider: %v", err)
}
// Create an OSSClient instance.
// Specify the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com. Specify your actual endpoint.
// Specify the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the region to cn-hangzhou. Specify the actual region.
clientOptions := []oss.ClientOption{oss.SetCredentialsProvider(&provider)}
clientOptions = append(clientOptions, oss.Region("yourRegion"))
// Specify the version of the signature algorithm.
clientOptions = append(clientOptions, oss.AuthVersion(oss.AuthV4))
client, err := oss.New("yourEndpoint", "", "", clientOptions...)
if err != nil {
log.Fatalf("Failed to create OSS client: %v", err)
}
// Specify the name of the bucket.
bucketName := "examplebucket"
bucket, err := client.Bucket(bucketName)
if err != nil {
log.Fatalf("Failed to get bucket '%s': %v", bucketName, err)
}
// List the versions of all objects including delete markers in the bucket.
keyMarker := oss.KeyMarker("")
versionIdMarker := oss.VersionIdMarker("")
for {
lor, err := bucket.ListObjectVersions(keyMarker, versionIdMarker)
if err != nil {
log.Fatalf("Failed to list object versions: %v", err)
}
// Display the version IDs of the objects.
for _, objVersion := range lor.ObjectVersions {
log.Printf("Versionid: %s", objVersion.VersionId)
log.Printf("Key: %s", objVersion.Key)
log.Printf("Is Latest: %t", objVersion.IsLatest)
}
// Display the versions of the listed delete markers.
for _, deleteMarker := range lor.ObjectDeleteMarkers {
log.Printf("Delete Marker Versionid: %s", deleteMarker.VersionId)
log.Printf("Delete Marker Key: %s", deleteMarker.Key)
}
// Check whether the required versions are listed. If the versions are incompletely listed, the list operation continues. If the versions are completely listed, the list operation stops.
keyMarker = oss.KeyMarker(lor.NextKeyMarker)
versionIdMarker = oss.VersionIdMarker(lor.NextVersionIdMarker)
if !lor.IsTruncated {
break
}
}
}
Resposta de exemplo:
Versionid: CAEQChiBgIDHzNPEthciIDYzZGQ5M2VjOTU2ODRmMzA4ZWM4ODk0NjVmMWEx****
Key: fun/
Is Latest true
Versionid: CAEQChiBgID61tnEthciIDNmOGM2MTQ3ZjU1NTQ2MGFhYWJjNjQxMTQxZWZh****
Key: fun/destfolder/
Is Latest true
Versionid: CAEQChiBgMDczt3EthciIDEwYjliZmQ4MDNiMDQ2Njk4YWMxM2NhM2E5NzQ3****
Key: fun/destfolder/image1.jpg
Is Latest true
Versionid: CAEQChiBgIDszt3EthciIGU5OWU0ZTllMGY3NTRmMmU5NzVjZmJkYmE3ZWYy****
Key: fun/destfolder/image2.png
Is Latest true
Versionid: CAEQChiBgICditzEthciIDBiNTg1ZTZkMDRlMzRjNDdiMjRjMTBlOGUzMTM0****
Key: fun/examplefile.txt
Is Latest true
Versionid: CAEQChiBgMC.itzEthciIDEzNWVlYjNhYzNmMjQ4NWM5Nzc2NzllY2FiYmQ3****
Key: fun/exampleobject.jpg
Is Latest true
Versionid: CAEQChiBgIDMgdbEthciIDUyMGI0NmZlNThkODQwY2ZhNmZhNTQ1Njk4ZTdj****
Key: oss.jpg
Is Latest true
Versionid: CAEQChiBgICIgdbEthciIDdlM2Q1YjYxZDIyZDQyMzI4MTRkNzVmYzdiMTBh****
Key: srcfile.txt
Is Latest true
Cenários comuns
Listar versões de objetos cujos nomes contêm um prefixo especificado
Listar versões de um número específico de objetos
Listar versões de todos os objetos por página
Listar objetos em uma pasta
O OSS armazena objetos em uma estrutura plana. Uma pasta é um objeto de zero bytes cujo nome termina com uma barra (/). É possível fazer upload e download de pastas. Por padrão, o console do OSS exibe qualquer objeto cujo nome termine com barra (/) como uma pasta.
Para listar objetos por pasta, especifique os parâmetros delimiter e prefix na solicitação.
Ao definir prefix como o nome de uma pasta na solicitação, o sistema lista objetos e subpastas cujos nomes contenham esse prefixo.
Caso você especifique um prefixo e defina delimiter como barra (/) na solicitação, serão listados apenas os objetos e subpastas cujos nomes comecem com o prefixo indicado dentro daquela pasta. Cada subpasta aparece como um único elemento de resultado em CommonPrefixes, sem listar os objetos e pastas contidos nela.
Os exemplos a seguir mostram como listar objetos em pastas simuladas.
-
Listar versões de objetos na pasta raiz de um bucket
O código abaixo exemplifica como listar as versões dos objetos localizados na pasta raiz de um bucket:
package main import ( "fmt" "os" "github.com/aliyun/aliyun-oss-go-sdk/oss" ) func HandleError(err error) { fmt.Println("Error:", err) os.Exit(-1) } func main() { // 从环境变量中获取访问凭证。运行本代码示例之前,请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。 provider, err := oss.NewEnvironmentVariableCredentialsProvider() if err != nil { fmt.Println("Error:", err) os.Exit(-1) } // 创建OSSClient实例。 // yourEndpoint填写Bucket对应的Endpoint,以华东1(杭州)为例,填写为https://oss-cn-hangzhou.aliyuncs.com。其它Region请按实际情况填写。 // yourRegion填写Bucket所在地域,以华东1(杭州)为例,填写为cn-hangzhou。其它Region请按实际情况填写。 clientOptions := []oss.ClientOption{oss.SetCredentialsProvider(&provider)} clientOptions = append(clientOptions, oss.Region("yourRegion")) // 设置签名版本 clientOptions = append(clientOptions, oss.AuthVersion(oss.AuthV4)) client, err := oss.New("yourEndpoint", "", "", clientOptions...) if err != nil { fmt.Println("Error:", err) os.Exit(-1) } // 填写Bucket名称。 bucketName := "examplebucket" bucket, err := client.Bucket(bucketName) if err != nil { HandleError(err) } // 通过指定delimiter为正斜线(/),实现列举根目录下的Object的版本信息以及文件夹名称。 delimiter := oss.Delimiter("/") keyMarker := oss.KeyMarker("") versionIdMarker := oss.VersionIdMarker("") for { lor, err := bucket.ListObjectVersions(keyMarker, delimiter, versionIdMarker) if err != nil { HandleError(err) } // 查看Object的版本信息。 for _, dirName := range lor.ObjectVersions { fmt.Println("Versionid:", dirName.VersionId) fmt.Println("Key:", dirName.Key) fmt.Println("Is Latest", dirName.IsLatest) } // 查看以正斜线(/)结尾的文件夹名称。 for _, common_prefix := range lor.CommonPrefixes { fmt.Println("common_prefix:", common_prefix) } // 查看列举结果是否完整。如果结果不完整,则继续列举。如果结果已完整,则退出循环。 if lor.IsTruncated { keyMarker = oss.KeyMarker(lor.NextKeyMarker) versionIdMarker = oss.VersionIdMarker(lor.NextVersionIdMarker) } else { break } } }Resposta de exemplo:
Versionid: CAEQChiBgIDMgdbEthciIDUyMGI0NmZlNThkODQwY2ZhNmZhNTQ1Njk4ZTdj**** Key: oss.jpg Is Latest true Versionid: CAEQChiBgICIgdbEthciIDdlM2Q1YjYxZDIyZDQyMzI4MTRkNzVmYzdiMTBh**** Key: srcfile.txt Is Latest true common_prefix: fun/ -
Listar objetos e subpastas em uma pasta
O exemplo a seguir demonstra como listar os objetos e as subpastas existentes em uma pasta específica do bucket:
package main import ( "fmt" "os" "github.com/aliyun/aliyun-oss-go-sdk/oss" ) func HandleError(err error) { fmt.Println("Error:", err) os.Exit(-1) } func main() { // 从环境变量中获取访问凭证。运行本代码示例之前,请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。 provider, err := oss.NewEnvironmentVariableCredentialsProvider() if err != nil { fmt.Println("Error:", err) os.Exit(-1) } // 创建OSSClient实例。 // yourEndpoint填写Bucket对应的Endpoint,以华东1(杭州)为例,填写为https://oss-cn-hangzhou.aliyuncs.com。其它Region请按实际情况填写。 // yourRegion填写Bucket所在地域,以华东1(杭州)为例,填写为cn-hangzhou。其它Region请按实际情况填写。 clientOptions := []oss.ClientOption{oss.SetCredentialsProvider(&provider)} clientOptions = append(clientOptions, oss.Region("yourRegion")) // 设置签名版本 clientOptions = append(clientOptions, oss.AuthVersion(oss.AuthV4)) client, err := oss.New("yourEndpoint", "", "", clientOptions...) if err != nil { fmt.Println("Error:", err) os.Exit(-1) } // 填写Bucket名称。 bucketName := "examplebucket" bucket, err := client.Bucket(bucketName) if err != nil { HandleError(err) } // 设置Prefix参数来获取fun目录下的所有文件与文件夹,同时设置delimiter参数为正斜线(/)作为文件夹的分隔符。 prefix := oss.Prefix("fun/") delimiter := oss.Delimiter("/") keyMarker := oss.KeyMarker("") versionIdMarker := oss.VersionIdMarker("") for { lor, err := bucket.ListObjectVersions(prefix, delimiter, keyMarker, versionIdMarker) if err != nil { HandleError(err) } // 查看Object的版本信息。 for _, dirName := range lor.ObjectVersions { fmt.Println("Versionid:", dirName.VersionId) fmt.Println("Key:", dirName.Key) fmt.Println("Is Latest:", dirName.IsLatest) } // 查看以正斜线(/)结尾的文件夹名称。 for _, common_prefix := range lor.CommonPrefixes { fmt.Println("common_prefix:", common_prefix) } // 查看列举结果是否完整。如果结果不完整,则继续列举。如果结果已完整,则退出循环。 if lor.IsTruncated { keyMarker = oss.KeyMarker(lor.NextKeyMarker) versionIdMarker = oss.VersionIdMarker(lor.NextVersionIdMarker) } else { break } } }Resposta de exemplo:
Versionid: CAEQChiBgIDHzNPEthciIDYzZGQ5M2VjOTU2ODRmMzA4ZWM4ODk0NjVmMWEx**** Key: fun/ Is Latest: true Versionid: CAEQChiBgICditzEthciIDBiNTg1ZTZkMDRlMzRjNDdiMjRjMTBlOGUzMTM0**** Key: fun/examplefile.txt Is Latest: true Versionid: CAEQChiBgMC.itzEthciIDEzNWVlYjNhYzNmMjQ4NWM5Nzc2NzllY2FiYmQ3**** Key: fun/exampleobject.jpg Is Latest: true common_prefix: fun/destfolder/
Referência
Para mais informações sobre a operação de API usada para listar as versões de todos os objetos em um bucket, consulte ListObjectVersions.