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 obter 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 obter 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 o uso de um domínio personalizado ou autenticação 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 obter 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 básicas
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, é possível 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âmetro
fetchOwnerpara 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 de partida para esta operação de listagem. |
|
fetchOwner |
Especifica se as informações de Owner devem ser incluídas nos resultados.
|
Para obter 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 é 1000. |
|
marker |
O ponto de partida para esta operação de listagem. |
Para obter 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
Listar um número específico de objetos
Listar objetos com um prefixo específico
Listar objetos após um ponto de partida especificado
Listar todos os objetos por página
Listar objetos com um prefixo específico por página
Listar informações sobre todos os objetos em um diretório específico
Listar informações sobre todos os subdiretórios em um diretório específico
Listar objetos e retornar informações de Owner
Pastas
Perguntas frequentes
Posso classificar objetos pela hora da última modificação ao listá-los?
Não. Para classificar objetos pela hora da última modificação, use a indexação de dados.
Referências
Para obter o código de exemplo completo para listar objetos, consulte o exemplo no GitHub.
Para obter mais informações sobre as operações de API para listar objetos, consulte ListObjectsV2 e ListObjects.