Todos os produtos
Search
Central de documentação

Object Storage Service:Copiar objetos (SDK for Go V2)

Última atualização: Aug 25, 2026

Utilize o método CopyObject do SDK for Go V2 para copiar um objeto com tamanho inferior a 5 GiB entre um bucket de origem e um bucket de destino na mesma região. Os buckets de origem e de destino podem ser iguais ou diferentes.

Precauções

  • O código de exemplo neste tópico utiliza o ID da região China (Hangzhou) cn-hangzhou e um endpoint público por padrão. Caso deseje acessar o OSS a partir de outro service da Alibaba Cloud na mesma região, utilize um endpoint interno. Para consultar o mapeamento entre regiões e endpoints do OSS, consulte Regions and endpoints.

  • Este tópico exemplifica a leitura de credenciais de acesso por meio de variáveis de ambiente. Para obter informações sobre como configurar credenciais de acesso, consulte Configure access credentials.

  • A cópia de um objeto exige permissão de leitura no objeto de origem, além de permissões de leitura e gravação no bucket de destino.

  • Não há suporte para cópia entre regiões. Por exemplo, não é possível copiar um objeto de um bucket na região China (Hangzhou) para um bucket na região China (Qingdao).

  • Ao copiar um objeto, certifique-se de que nem o bucket de origem nem o bucket de destino possuam uma política de retenção configurada. Caso contrário, a operação falhará e retornará o erro: The object you specified is immutable.

Permissões

Por padrão, uma conta Alibaba Cloud possui permissões totais. Usuários RAM ou funções RAM vinculados a uma conta Alibaba Cloud não possuem permissões por padrão. A conta Alibaba Cloud ou o administrador da conta deve conceder as permissões operacionais por meio de RAM policies ou Bucket Policy.

API

Action

Description

CopyObject

oss:GetObject

Copia objetos dentro de um bucket ou entre buckets na mesma região.

oss:PutObject

oss:GetObjectVersion

Necessária também caso você especifique a versão do objeto de origem por meio do versionId.

oss:GetObjectTagging

Obrigatórias quando tags de objeto são copiadas via x-oss-tagging.

oss:PutObjectTagging

oss:GetObjectVersionTagging

Também exigida se as tags de uma versão específica do objeto de origem forem definidas pelo versionId.

kms:GenerateDataKey

Ambas as permissões são necessárias durante a cópia se os metadados do objeto de destino contiverem X-Oss-Server-Side-Encryption: KMS.

kms:Decrypt

Assinatura do método

func (c *Client) CopyObject(ctx context.Context, request *CopyObjectRequest, optFns ...func(*Options)) (*CopyObjectResult, error)

Parâmetros da solicitação

Parâmetro

Tipo

Descrição

ctx

context.Context

Contexto da solicitação. Permite definir o tempo limite geral da requisição.

request

*CopyObjectRequest

Parâmetros necessários para esta operação. Para mais detalhes, consulte CopyObjectRequest

optFns

...func(*Options)

(Opcional) Opções de configuração adicionais. Consulte Options para mais informações

A tabela a seguir descreve os parâmetros comuns do CopyObjectRequest:

Parameter

Type

Description

Bucket

*string

Define o nome do bucket de destino.

Key

*string

Indica o nome do objeto de destino.

SourceBucket

*string

Especifica o nome do bucket de origem.

SourceKey

*string

Determina o nome do objeto de origem.

ForbidOverwrite

*string

Controla se o objeto de destino com o mesmo nome será sobrescrito durante a operação CopyObject.

Tagging

*string

Estabelece as tags do objeto. É possível definir múltiplas tags simultaneamente, por exemplo, TagA=A&TagB=B.

TaggingDirective

*string

Define como as tags do objeto de destino serão tratadas. Valores válidos:

  • Copy (padrão): replica as tags do objeto de origem para o objeto de destino.

  • Replace: descarta as tags do objeto de origem e aplica aquelas especificadas na solicitação.

Parâmetros de resposta

Valor de retorno

Tipo

Descrição

result

*CopyObjectResult

Resultado da operação, válido apenas quando err é nil. Veja mais em CopyObjectResult

err

error

Status da solicitação. Se houver falha, err não será nil.

Código de exemplo

Utilize o código abaixo para copiar um objeto menor que 5 GiB de um bucket de origem para um bucket de destino.

package main

import (
	"context"
	"flag"
	"log"

	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
)

// Specify the global variables.
var (
	region         string // The region in which the bucket is located.
	srcBucketName  string // The name of the source bucket.
	srcObjectName  string // The name of the source object.
	destBucketName string // The name of the destination bucket.
	destObjectName string // The name of the destination object.
)

// Specify the init function used to initialize command line parameters.
func init() {
	flag.StringVar(&region, "region", "", "The region in which the bucket is located.")
	flag.StringVar(&srcBucketName, "src-bucket", "", "The name of the source bucket.")
	flag.StringVar(&srcObjectName, "src-object", "", "The name of the source object.")
	flag.StringVar(&destBucketName, "dest-bucket", "", "The name of the destination bucket.")
	flag.StringVar(&destObjectName, "dest-object", "", "The name of the destination object.")
}

func main() {
	// Parse the command line parameters.
	flag.Parse()

	// Check whether the source bucket name is empty.
	if len(srcBucketName) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, source bucket name required")
	}

	// Check whether the region is empty.
	if len(region) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, region required")
	}

	// If the destination bucket name is not specified, use the source bucket name.
	if len(destBucketName) == 0 {
		destBucketName = srcBucketName
	}

	// Check whether the source object name is empty.
	if len(srcObjectName) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, source object name required")
	}

	// Check whether the destination object name is empty.
	if len(destObjectName) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, destination object name required")
	}

	// Load the default configuration and specify the credential provider and region.
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion(region)

	// Create an OSS client.
	client := oss.NewClient(cfg)

	// Create a request for copying the object.
	request := &oss.CopyObjectRequest{
		Bucket:       oss.Ptr(destBucketName), // The name of the destination bucket.
		Key:          oss.Ptr(destObjectName), // The name of the destination object.
		SourceKey:    oss.Ptr(srcObjectName),  // The name of the source object.
		SourceBucket: oss.Ptr(srcBucketName),  // The name of the source bucket.
	}

	// Perform the copy object operation and handle the result.
	result, err := client.CopyObject(context.TODO(), request)
	if err != nil {
		log.Fatalf("failed to copy object %v", err)
	}
	log.Printf("copy object result:%#v\n", result)
}

Referências

  • Para acessar o código de exemplo completo sobre cópia de objetos, consulte o exemplo no GitHub.

  • Para detalhes sobre a operação de API utilizada na cópia de objetos, veja CopyObject.