Todos os produtos
Search
Central de documentação

Object Storage Service:Manage object metadata (OSS SDK for Go 1.0)

Última atualização: Sep 22, 2026

Objetos armazenados no Object Storage Service (OSS) são compostos por chaves, dados e metadados. Os metadados descrevem o objeto e incluem cabeçalhos HTTP padrão e metadados de usuário. Ao configurar cabeçalhos HTTP padrão, você pode crie políticas personalizadas de requisição HTTP, como políticas de cache e de download forçado de objetos. Já os metadados de usuário permitem identificar as finalidades ou os atributos de um objeto.

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 Alibaba Cloud na mesma região, use um endpoint interno. Para obter mais informações sobre regiões e endpoints do OSS, consulte Regions and endpoints.

  • Neste tópico, as credenciais de acesso são obtidas de variáveis de ambiente. Para saber como configure credenciais de acesso, consulte Configure access credentials.

  • Este tópico demonstra como crie uma instância OSSClient usando um endpoint do OSS. Para configurações alternativas, como usar um domínio personalizado ou autenticar com credenciais do Security Token Service (STS), consulte Configure a client (Go SDK V1).

  • Para configure metadados de objetos, você precisa da permissão oss:PutObject. Para consultar metadados de objetos, é necessária a permissão oss:GetObject. Para obter detalhes, consulte Grant a custom policy.

Código de exemplo

Configure metadados de objetos ao fazer upload de um objeto

Aviso

Ao fazer upload de objetos para o OSS, se já existir um objeto com o mesmo nome no bucket, o OSS sobrescreve o objeto existente. Antes de configure metadados de objetos por meio de upload, verifique se o bucket de destino não contém um objeto com o mesmo nome para evitar sobrescrever objetos existentes acidentalmente. Para saber como evitar a sobrescrita de objetos com nomes iguais, consulte Prevent objects with the same names from being overwritten.

package main

import (
	"log"
	"strings"
	"time"

	"github.com/aliyun/aliyun-oss-go-sdk/oss"
)

func main() {
	// Obtain access credentials from environment variables. Before you run the 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 bucket name. Example: examplebucket. 
	bucketName := "examplebucket" // Replace this parameter with the actual name of your bucket.
	bucket, err := client.Bucket(bucketName)
	if err != nil {
		log.Fatalf("Failed to get bucket: %v", err)
	}

	// Configure object metadata. Set the expiration time to 23:00:00 January 10, 2049 in GMT, access control list (ACL) to public-read, and MyProp to MyPropVal as user metadata.
	expires := time.Date(2049, time.January, 10, 23, 0, 0, 0, time.UTC)
	options := []oss.Option{
		oss.Expires(expires),
		oss.ObjectACL(oss.ACLPublicRead),
		oss.Meta("MyProp", "MyPropVal"),
	}

	// Use a data stream to upload the object. 
	// Specify the full path of the object. The full path of the object cannot contain the bucket name. Example: exampledir/exampleobject.txt. 
	objectName := "exampledir/exampleobject.txt" // Replace this parameter with the actual path of the object.
	err = bucket.PutObject(objectName, strings.NewReader("MyObjectValue"), options...)
	if err != nil {
		log.Fatalf("Failed to upload object: %v", err)
	}

	// Query object metadata. 
	props, err := bucket.GetObjectDetailedMeta(objectName)
	if err != nil {
		log.Fatalf("Failed to get object detailed metadata: %v", err)
	}
	log.Printf("Object Meta: %+v\n", props)
}

Modifique metadados de objetos

...

// Modify one object metadata parameter at a time. 
err = bucket.SetObjectMeta(objectName, oss.Meta("MyMeta", "MyMetaValue1"))
if err != nil {
	log.Fatalf("Failed to set single metadata: %v", err)
}

// Modify multiple object metadata parameters at a time. 
options := []oss.Option{
	oss.Meta("MyMeta", "MyMetaValue2"),
	oss.Meta("MyObjectLocation", "HangZhou"),
}
err = bucket.SetObjectMeta(objectName, options...)
if err != nil {
	log.Fatalf("Failed to set multiple metadatas: %v", err)
}

// Query object metadata. 
props, err := bucket.GetObjectDetailedMeta(objectName)
if err != nil {
	log.Fatalf("Failed to get object detailed metadata: %v", err)
}
log.Printf("Object Meta: %+v\n", props)

Consultar metadados de objetos

...

// Query object metadata. 
props, err := bucket.GetObjectDetailedMeta(objectName)
if err != nil {
	log.Fatalf("Failed to get object detailed metadata: %v", err)
}
log.Printf("Object Meta: %+v\n", props)         

Perguntas frequentes

Ao fazer upload de um objeto para um bucket e defina metadados simultaneamente, como evitar a sobrescrita de um objeto existente com o mesmo nome?

Use um dos métodos a seguir para evitar a sobrescrita de objetos com o mesmo nome no bucket:

  • Ative o versionamento

    Se você ative o versionamento para o bucket, o OSS manterá o objeto existente com o mesmo nome como uma versão anterior e armazenará o objeto enviado como a versão atual. É possível restaurar as versões anteriores a qualquer momento. Para obter mais informações, consulte Enable version control.

  • Incluir o cabeçalho x-oss-forbid-overwrite na requisição de upload

    Inclua o cabeçalho x-oss-forbid-overwrite na requisição de upload e defina-o como true. Se o objeto enviado tiver o mesmo nome de um objeto existente, o upload falhará e o OSS retornará o erro FileAlreadyExists. Para obter mais informações, consulte PutObject.

Referências

  • Para acessar o código de exemplo completo de consulta de metadados de objetos, visite GitHub.

  • Para obter mais informações sobre a operação de API usada para configure metadados de objetos durante o upload simples, consulte PutObject.

  • Para saber mais sobre a operação de API que permite modifique os metadados de um objeto existente, consulte CopyObject.

  • Para obter detalhes sobre a operação de API usada para consultar metadados de objetos, consulte GetObjectMeta e HeadObject.