Todos os produtos
Search
Central de documentação

Object Storage Service:Gerencie metadados de objetos (OSS SDK for Go 1.0)

Última atualização: Jul 03, 2026

Os objetos armazenados no Object Storage Service (OSS) consistem em chaves, dados e metadados. Os metadados descrevem o objeto e incluem cabeçalhos HTTP padrão e metadados de usuário. Configure cabeçalhos HTTP padrão para criar políticas personalizadas de requisição HTTP, como políticas de cache e de download forçado de objetos. Além disso, configure metadados de usuário para identificar a finalidade ou os atributos do objeto.

Observações

  • Este tópico usa 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, use 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 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 uso de domínio personalizado ou autenticação com credenciais do Security Token Service (STS), consulte Configurar um cliente (Go SDK V1).

  • Para configurar metadados de objetos, você deve ter a permissão oss:PutObject. Para consultar metadados de objetos, você deve ter a permissão oss:GetObject. Para obter mais informações, consulte Conceder uma política personalizada.

Código de exemplo

Configure metadados ao fazer upload de um objeto

Aviso

Ao fazer upload de objetos para o OSS, se um objeto armazenado tiver o mesmo nome do objeto enviado, o OSS substituirá o objeto existente pelo novo. Antes de configurar metadados fazendo upload de um objeto, verifique se o bucket de destino não contém um objeto com o mesmo nome para evitar substituições acidentais. Para obter mais informações sobre como impedir a substituição de objetos com o mesmo nome, consulte Impedir a substituição de objetos com o mesmo nome.

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

Como impedir que um objeto existente com o mesmo nome seja substituído ao fazer upload e definir metadados simultaneamente?

Use um dos métodos a seguir para impedir a substituição de objetos com o mesmo nome no bucket:

  • Ative o controle de versão

    Se você ativar o controle de versão 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 Ativar controle de versão.

  • 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 você fizer upload de um objeto com 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 obter o código de exemplo completo usado para consultar metadados de objetos, visite o GitHub.

  • Para obter mais informações sobre a operação de API que você pode chamar para configurar metadados de objetos durante um upload simples, consulte PutObject.

  • Para obter mais informações sobre a operação de API para modificar os metadados de um objeto existente, consulte CopyObject.

  • Para obter mais informações sobre as operações de API que você pode chamar para consultar metadados de objetos, consulte GetObjectMeta e HeadObject.