Todos los productos
Search
Centro de documentos

Object Storage Service:Copia de objetos con OSS SDK for Go 2.0

Última actualización: Sep 24, 2026

Este tema describe cómo copiar objetos grandes mediante el nuevo módulo Copier del SDK for Go V2 de Object Storage Service (OSS).

Notas de uso

  • El código de ejemplo de este tema utiliza el identificador de región cn-hangzhou, correspondiente a China (Hangzhou). De forma predeterminada, se usa el endpoint público para acceder a los recursos de un bucket. Si necesita acceder a los recursos del bucket desde otros servicios de Alibaba Cloud ubicados en la misma región que el bucket, utilice un endpoint interno. Para obtener más información sobre las regiones y los endpoints de OSS, consulte Regions and endpoints.

  • En este tema, las credenciales de acceso se obtienen de variables de entorno. Para obtener más información sobre cómo configurar las credenciales de acceso, consulte Configure access credentials.

  • Para copiar un objeto, debe contar con permisos de lectura sobre el objeto de origen, así como permisos de lectura y escritura en el bucket de destino.

  • El bucket de origen y el bucket de destino deben estar en la misma región. Por ejemplo, no es posible copiar objetos de un bucket ubicado en China (Hangzhou) hacia un bucket ubicado en China (Qingdao).

  • Compruebe que no haya políticas de retención configuradas en el bucket de origen ni en el bucket de destino. De lo contrario, se devuelve el siguiente mensaje de error: The object you specified is immutable.

Métodos

Copier

Si desea copiar un objeto de un bucket a otro o modificar los atributos de un objeto, puede invocar la operación CopyObject o UploadPartCopy. Cada una de estas operaciones es adecuada para escenarios distintos:

  • La operación CopyObject solo sirve para copiar objetos cuyo tamaño sea menor a 5 GiB.

  • La operación UploadPartCopy está diseñada para copiar objetos de 5 GiB o más. Tenga en cuenta que esta operación no admite las directivas x-oss-metadata-directive y x-oss-tagging-directive. Para configurar metadatos y etiquetas durante una copia multiparte, se requiere una implementación adicional.

El módulo Copier oculta las diferencias entre operaciones y los detalles de implementación, por lo que ofrece una solución universal para copiar objetos. Este módulo selecciona automáticamente la operación adecuada según los parámetros de solicitud especificados. A continuación se muestran los métodos comunes del 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 de solicitud

Parámetro

Tipo

Descripción

ctx

context.Context

Contexto de la solicitud. Permite especificar la duración total de la solicitud.

request

*CopyObjectRequest

Parámetros de una operación de API específica. Para obtener más información, consulte CopyObjectRequest.

optFns

...func(*CopierOptions)

Parámetros opcionales. Para obtener más información, consulte CopierOptions.

Parámetros comunes de CopyObjectRequest

Parámetro

Tipo

Descripción

Bucket

*string

Nombre del bucket de destino.

Key

*string

Nombre del objeto de destino.

SourceBucket

*string

Nombre del bucket de origen.

SourceKey

*string

Nombre del objeto de origen.

ForbidOverwrite

*string

Indica si la operación CopyObject impide sobrescribir un objeto que tenga el mismo nombre.

Tagging

*string

Etiquetas del objeto de destino. Puede configurar varias etiquetas para el objeto de destino. Ejemplo: TagA=A&TagB=B.

TaggingDirective

*string

Método utilizado para configurar las etiquetas del objeto de destino. Valores:

  • Copy (predeterminado): las etiquetas del objeto de origen se copian al objeto de destino.

  • Replace: las etiquetas especificadas en la solicitud se agregan al objeto de destino.

Parámetros comunes de CopierOptions

Parámetro

Tipo

Descripción

PartSize

int64

Tamaño de cada parte. El tamaño predeterminado es de 64 MiB.

ParallelNum

int

Número de tareas de carga en paralelo. El valor predeterminado es 3. Esta configuración aplica únicamente a la llamada actual y no de forma global.

MultipartCopyThreshold

int64

Tamaño mínimo del objeto para invocar la operación de copia multiparte. El tamaño predeterminado es de 200 MiB.

LeavePartsOnError

bool

Indica si se conservan las partes copiadas cuando la copia termina con errores. De forma predeterminada, las partes copiadas no se conservan.

DisableShallowCopy

bool

Indica si se deshabilita la copia superficial. De forma predeterminada, la copia superficial está habilitada.

Parámetros de respuesta

Parámetro

Tipo

Descripción

result

*CopyResult

Respuesta de la operación. Este parámetro está disponible cuando el valor de err es nil. Para obtener más información, consulte CopyResult.

err

error

Estado de la solicitud. Si la solicitud termina con errores, el valor de err no es nil.

Código de ejemplo

A continuación se muestra cómo copiar un objeto del bucket de origen a un bucket de destino y modificar sus atributos:

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

Referencias