Todos os produtos
Search
Central de documentação

Object Storage Service:Copier com o OSS SDK for Go 2.0

Última atualização: Jul 03, 2026

Este tópico descreve como copiar objetos grandes usando o novo módulo Copier do Object Storage Service (OSS) SDK for Go V2.

Observações de uso

  • O código de exemplo neste tópico usa o ID da região cn-hangzhou, correspondente à região China (Hangzhou). Por padrão, o acesso aos recursos de um bucket ocorre via endpoint público. Para acessar os recursos do bucket a partir de outros serviços da Alibaba Cloud na mesma região do bucket, use 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 de variáveis de ambiente. Para saber como configurar as credenciais de acesso, consulte Configurar credenciais de acesso.

  • Para copiar um objeto, você precisa ter permissões de leitura no objeto de origem e permissões de leitura e gravação no bucket de destino.

  • Os buckets de origem e de destino devem estar na mesma região. Por exemplo, não é possível copiar objetos de um bucket na região China (Hangzhou) para um bucket na região China (Qingdao).

  • Verifique se não há políticas de retenção configuradas nos buckets de origem e de destino. Caso contrário, o sistema retorna a seguinte mensagem de erro: The object you specified is immutable.

Métodos

Copier

Para copiar um objeto entre buckets ou modificar seus atributos, chame a operação CopyObject ou UploadPartCopy. Cada uma atende a cenários específicos:

  • A operação CopyObject serve apenas para copiar objetos menores que 5 GiB.

  • A operação UploadPartCopy é indicada para objetos com tamanho igual ou superior a 5 GiB. Essa operação não suporta as diretivas x-oss-metadata-directive e x-oss-tagging-directive. Para definir metadados e tags durante uma cópia multipart, implemente uma lógica adicional.

O módulo Copier abstrai as diferenças operacionais e os detalhes de implementação, oferecendo uma solução universal para cópia de objetos. O Copier seleciona automaticamente a operação adequada com base nos parâmetros da solicitação. Veja a seguir os métodos comuns do módulo Copier:

type Copier struct {
  ...
}

// Create a Copier.
func (c *Client) NewCopier(optFns ...func(*CopierOptions)) *Copier

// // Copy objects.
func (c *Copier) Copy(ctx context.Context, request *CopyObjectRequest, optFns ...func(*CopierOptions)) (*CopyResult, error)

Parâmetros da solicitação

Parâmetro

Tipo

Descrição

ctx

context.Context

Contexto da solicitação. Use este parâmetro para especificar a duração total da requisição.

request

*CopyObjectRequest

Parâmetros da operação da API. Para mais detalhes, consulte CopyObjectRequest.

optFns

...func(*CopierOptions)

Parâmetros opcionais. Para mais informações, consulte CopierOptions.

Parâmetros comuns do CopyObjectRequest

Parâmetro

Tipo

Descrição

Bucket

*string

Nome do bucket de destino.

Key

*string

Nome do objeto de destino.

SourceBucket

*string

Nome do bucket de origem.

SourceKey

*string

Nome do objeto de origem.

ForbidOverwrite

*string

Define se a operação CopyObject impede a sobrescrita de um objeto com o mesmo nome.

Tagging

*string

Tags do objeto de destino. Configure várias tags para o objeto de destino. Exemplo: TagA=A&TagB=B.

TaggingDirective

*string

Método usado para configurar as tags do objeto de destino. Valores:

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

  • Replace: adiciona as tags especificadas na solicitação ao objeto de destino.

Parâmetros comuns do CopierOptions

Parâmetro

Tipo

Descrição

PartSize

int64

Tamanho da parte. O valor padrão é 64 MiB.

ParallelNum

int

Número de tarefas de upload em paralelo. O valor padrão é 3. Esta configuração aplica-se apenas a esta chamada específica e não é global.

MultipartCopyThreshold

int64

Tamanho mínimo do objeto para acionar a operação de cópia multipart. O valor padrão é 200 MiB.

LeavePartsOnError

bool

Define se as partes copiadas devem ser mantidas em caso de falha na cópia. Por padrão, as partes não são retidas.

DisableShallowCopy

bool

Define se a cópia superficial (shallow copy) deve ser desativada. Por padrão, a cópia superficial está ativada.

Parâmetros de resposta

Parâmetro

Tipo

Descrição

result

*CopyResult

Resposta da operação. Este parâmetro fica disponível quando o valor de err é nil. Para mais detalhes, consulte CopyResult.

err

error

Status da solicitação. Se a requisição falhar, o valor de err não será nil.

Código de exemplo

O exemplo a seguir mostra como copiar um objeto do bucket de origem para um bucket de destino e modificar os atributos do objeto:

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"
)

// Define the global variables.
var (
	region         string // The region.
	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.
)

// Use the init function to initialize 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 parameters.
	flag.Parse()

	// Check whether the source bucket name is empty.
	if len(srcBucketName) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, 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, the source bucket name is used.
	if len(destBucketName) == 0 {
		destBucketName = srcBucketName
	}

	// Check whether the source object name is empty.
	if len(srcObjectName) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, src 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")
	}

	// Create an OSS client configuration.
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion(region)

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

	// Create a Copier.
	c := client.NewCopier()

	// Create a request to copy 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.
		StorageClass: oss.StorageClassStandard, // Set the storage class of the destination object to Standard.
		MetadataDirective: oss.Ptr("Replace"), // Ignore the metadata of the source object.
		TaggingDirective:  oss.Ptr("Replace"),       // Ignore the tags of the source object.
	}

	// Copy the object.
	result, err := c.Copy(context.TODO(), request)
	if err != nil {
		log.Fatalf("failed to copy object %v", err) // In case of an error, log the error and exit the operation.
	}

	// Display the result of the operation.
	log.Printf("copy object result:%#v\n", result)
}

Referências