Este tópico descreve como listar todos os objetos, objetos com um prefixo específico e objetos e subdiretórios em um diretório específico dentro de um bucket do Object Storage Service (OSS).
Observações
-
Neste tópico, é utilizado o endpoint público da região China (Hangzhou). Se você deseja acessar o OSS a partir de outros serviços da Alibaba Cloud na mesma região do OSS, utilize um endpoint interno. Para mais informações sobre regiões e endpoints do OSS, consulte Regiões e endpoints.
-
Neste tópico, as credenciais de acesso são obtidas a partir de variáveis de ambiente. Para mais informações 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 usar um domínio personalizado ou autenticar com credenciais do Security Token Service (STS), consulte Configurar um cliente (Go SDK V1).
-
Para listar objetos, você deve ter a permissão
oss:ListObjects. Para mais informações, consulte Conceder uma política personalizada. -
O OSS SDK for Go 2.2.5 e versões posteriores suportam o retorno de informações RestoreInfo.
Informações de fundo
Você pode chamar a operação ListObjectsV2 ou ListObjects para listar até 1.000 objetos em um bucket por vez. Ao especificar diferentes parâmetros, você pode implementar diversos recursos de listagem, como listar todos os objetos após uma posição inicial especificada, listar objetos e subdiretórios em um diretório especificado e paginar os resultados da listagem. As principais diferenças entre essas duas operações são as seguintes:
-
Ao usar a operação
ListObjectsV2, você deve usar o parâmetrofetchOwnerpara especificar se as informações de Owner dos objetos devem ser incluídas nos resultados. -
Ao usar a operação
ListObjects, as informações de Owner dos objetos são incluídas nos resultados por padrão.NotaPara buckets com versionamento habilitado, você deve usar a operação ListObjectsV2 para listar objetos.
As seções a seguir descrevem os parâmetros para listar objetos usando os métodos ListObjectsV2 e ListObjects.
ListObjectsV2
A tabela a seguir descreve os parâmetros para listar objetos usando o método ListObjectsV2.
|
Parâmetro |
Descrição |
|
prefix |
O prefixo que os nomes dos objetos retornados devem conter. |
|
delimiter |
Um caractere para agrupar nomes de objetos. Todos os nomes de objetos que contêm a mesma string do prefixo até a primeira ocorrência do delimitador são agrupados como um único elemento (commonPrefixes). |
|
startAfter |
O ponto inicial para esta operação de listagem. |
|
fetchOwner |
Especifica se as informações de Owner devem ser incluídas nos resultados.
|
Para mais informações, consulte ListObjectsV2.
ListObjects
A tabela a seguir descreve os parâmetros para listar objetos usando o método ListObjects.
|
Parâmetro |
Descrição |
|
delimiter |
Um caractere para agrupar nomes de objetos. Todos os nomes de objetos que contêm a mesma string do prefixo até a primeira ocorrência do delimitador são agrupados como um único elemento (commonPrefixes). |
|
prefix |
O prefixo que os nomes dos objetos retornados devem conter. |
|
maxKeys |
O número máximo de objetos a serem retornados. O valor padrão é 100. O valor máximo é 1.000. |
|
marker |
O ponto inicial para esta operação de listagem. |
Para mais informações, consulte ListObjects.
Exemplos
ListObjectsV2
O código de exemplo a seguir mostra como usar o método ListObjectsV2 para listar 100 objetos em um bucket.
package main
import (
"log"
"time"
"github.com/aliyun/aliyun-oss-go-sdk/oss"
)
func main() {
// Obtain access credentials from environment variables. Before you run this sample code, ensure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are set.
provider, err := oss.NewEnvironmentVariableCredentialsProvider()
if err != nil {
log.Fatalf("Failed to create credentials provider: %v", err)
}
// Create an OSSClient instance.
// Set yourEndpoint to the endpoint of the bucket. For example, if the bucket is in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com. For other regions, use the actual endpoint.
// Set yourRegion to the region of the bucket. For example, if the bucket is in the China (Hangzhou) region, set the region to cn-hangzhou. For other regions, use the actual region.
client, err := oss.New("yourEndpoint", "", "", oss.SetCredentialsProvider(&provider), oss.Region("yourRegion"), oss.AuthVersion(oss.AuthV4))
if err != nil {
log.Fatalf("Failed to create OSS client: %v", err)
}
// Specify the bucket name.
bucketName := "yourBucketName" // Replace with the actual bucket name.
bucket, err := client.Bucket(bucketName)
if err != nil {
log.Fatalf("Failed to get bucket: %v", err)
}
// The initial continuation token.
continueToken := ""
for {
// List all objects.
lsRes, err := bucket.ListObjectsV2(oss.ContinuationToken(continueToken))
if err != nil {
log.Fatalf("Failed to list objects: %v", err)
}
// Print the results. By default, 100 records are returned at a time.
for _, object := range lsRes.Objects {
log.Printf("Object Key: %s, Type: %s, Size: %d, ETag: %s, LastModified: %s, StorageClass: %s\n",
object.Key, object.Type, object.Size, object.ETag, object.LastModified.Format(time.RFC3339), object.StorageClass)
}
// If more objects need to be listed, update the continuation token and continue the loop.
if lsRes.IsTruncated {
continueToken = lsRes.NextContinuationToken
} else {
break
}
}
log.Println("All objects have been listed.")
}
ListObjects
O código de exemplo a seguir mostra como usar o método ListObjects para listar 100 objetos em um bucket.
package main
import (
"log"
"github.com/aliyun/aliyun-oss-go-sdk/oss"
)
func main() {
// Obtain access credentials from environment variables. Before you run this sample code, ensure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are set.
provider, err := oss.NewEnvironmentVariableCredentialsProvider()
if err != nil {
log.Fatalf("Failed to create credentials provider: %v", err)
}
// Create an OSSClient instance.
// Set yourEndpoint to the endpoint of the bucket. For example, if the bucket is in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com. For other regions, use the actual endpoint.
// Set yourRegion to the region of the bucket. For example, if the bucket is in the China (Hangzhou) region, set the region to cn-hangzhou. For other regions, use the actual region.
client, err := oss.New("yourEndpoint", "", "", oss.SetCredentialsProvider(&provider), oss.Region("yourRegion"), oss.AuthVersion(oss.AuthV4))
if err != nil {
log.Fatalf("Failed to create OSS client: %v", err)
}
// Specify the bucket name.
bucketName := "yourBucketName" // Replace with the actual bucket name.
bucket, err := client.Bucket(bucketName)
if err != nil {
log.Fatalf("Failed to get bucket: %v", err)
}
// List all objects.
marker := ""
for {
lsRes, err := bucket.ListObjects(oss.Marker(marker))
if err != nil {
log.Fatalf("Failed to list objects: %v", err)
}
// Print the results. By default, 100 records are returned at a time.
for _, object := range lsRes.Objects {
log.Printf("Object Name: %s\n", object.Key)
}
// If more objects need to be listed, update the marker and continue the loop.
if lsRes.IsTruncated {
marker = lsRes.NextMarker
} else {
break
}
}
log.Println("All objects have been listed.")
}
Cenários comuns
Perguntas frequentes
Posso ordenar objetos pela última modificação ao listá-los?
Não. Para ordenar objetos pela última modificação, use a indexação de dados.
Referências
-
Para o código de exemplo completo de listagem de objetos, consulte o exemplo no GitHub.
-
Para mais informações sobre as operações de API para listagem de objetos, consulte ListObjectsV2 e ListObjects.