Todos os produtos
Search
Central de documentação

Object Storage Service:Prevent objects from being overwritten by objects that have the same names (OSS SDK for Go 1.0)

Última atualização: Sep 22, 2026

Por padrão, ao fazer upload de um objeto com o mesmo nome de um objeto existente, o sistema sobrescreve o objeto existente. Este tópico descreve como configurar o cabeçalho de requisição x-oss-forbid-overwrite para impedir a sobrescrita de objetos existentes por objetos com o mesmo nome ao copiar objetos ou realizar upload simples ou upload multipart.

Observações

  • Neste tópico, utiliza-se 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 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 mais informações sobre como configurar credenciais de acesso, consulte Configure access credentials.

  • Este tópico demonstra como criar uma instância OSSClient usando 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 Configure a client (Go SDK V1).

Código de exemplo

O código de exemplo a seguir mostra como impedir a sobrescrita de objetos existentes por objetos com o mesmo nome durante um upload simples:

package main

import (
	"log"
	"strings"

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

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

	// Specify whether to overwrite an existing object with the same name. 
        // By default, if you do not specify oss.ForbidOverWrite, an object that has the same name is overwritten. 
        // If you set oss.ForbidOverWrite to false, an object that has the same name is overwritten. 
        // If you set oss.ForbidOverWrite to true, an object that has the same name is not overwritten. If such an object exists, an error is reported. 
	forbidWrite := oss.ForbidOverWrite(true)

	// Upload the string. 
        // Specify the full path of the object. Do not include the bucket name in the full path. 
	objectName := "yourObjectName"
	objectValue := "yourObjectValue"
	err = bucket.PutObject(objectName, strings.NewReader(objectValue), forbidWrite)
	if err != nil {
		log.Fatalf("Failed to upload object '%s': %v", objectName, err)
	}

	log.Printf("Successfully uploaded object '%s' with value '%s'", objectName, objectValue)
}

Cenários comuns

Evitar sobrescrita em uma tarefa de cópia de objetos

O código de exemplo a seguir demonstra como impedir a sobrescrita de objetos existentes por objetos copiados com o mesmo nome:

package main

import (
	"log"

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

func main() {
	// Obtain access credentials from environment variables. Before you run the sample 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 name of your bucket. 
	bucketName := "yourBucketName"
	// Specify the full path of the source object. Do not include the bucket name in the full path.
	objectName := "yourObjectName"
	// Specify the full path of the destination object. Do not include the bucket name in the full path.
	destObjectName := "yourDestObjectName"

	// Specify the name of the bucket.
	bucket, err := client.Bucket(bucketName)
	if err != nil {
		log.Fatalf("Failed to get bucket '%s': %v", bucketName, err)
	}

	// Specify whether to overwrite an existing object with the same name. 
	// By default, if you do not specify oss.ForbidOverWrite, an object that has the same name is overwritten. 
	// If you set oss.ForbidOverWrite to false, an object that has the same name is overwritten. 
	// If you set oss.ForbidOverWrite to true, an object that has the same name is not overwritten. If such an object exists, an error is reported. 
	forbidWrite := oss.ForbidOverWrite(true)

	// Create a copy of the object within the bucket.
	_, err = bucket.CopyObject(objectName, destObjectName, forbidWrite)
	if err != nil {
		log.Fatalf("Failed to copy object from '%s' to '%s': %v", objectName, destObjectName, err)
	}

	log.Printf("Successfully copied object from '%s' to '%s'", objectName, destObjectName)
}

Evitar sobrescrita em uma tarefa de upload multipart

O código de exemplo a seguir ilustra como impedir que um objeto existente seja sobrescrito por um objeto com o mesmo nome durante o upload multipart:

package main

import (
	"log"
	"os"

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

func main() {
	// Obtain access credentials from environment variables. Before you run the sample 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 name of the bucket. 
	bucketName := "yourBucketName"
	// Specify the full path of the object. Do not include the bucket name in the full path. 
	objectName := "yourObjectName"
	// Specify the full path of the local file. 
	localFilename := "yourLocalFilename"

	// Specify the name of the bucket.
	bucket, err := client.Bucket(bucketName)
	if err != nil {
		log.Fatalf("Failed to get bucket '%s': %v", bucketName, err)
	}

	// Split the object into multiple chunks.
	chunks, err := oss.SplitFileByPartNum(localFilename, 3)
	if err != nil {
		log.Fatalf("Failed to split file: %v", err)
	}

	// Open the local file.
	fd, err := os.Open(localFilename)
	if err != nil {
		log.Fatalf("Failed to open local file '%s': %v", localFilename, err)
	}
	defer fd.Close()

	// Specify whether to overwrite an existing object with the same name. 
	// By default, if you do not specify oss.ForbidOverWrite, an object that has the same name is overwritten. 
	// If you set oss.ForbidOverWrite to false, an object that has the same name is overwritten. 
	// If you set oss.ForbidOverWrite to true, an object that has the same name is not overwritten. If such an object exists, an error is reported. 
	forbidWrite := oss.ForbidOverWrite(true)

	// Step 1: Initiate a multipart upload task. 
	imur, err := bucket.InitiateMultipartUpload(objectName, forbidWrite)
	if err != nil {
		log.Fatalf("Failed to initiate multipart upload for '%s': %v", objectName, err)
	}

	// Step 2: Upload the parts. 
	var parts []oss.UploadPart
	for _, chunk := range chunks {
		fd.Seek(chunk.Offset, os.SEEK_SET)
		// Call the UploadPart method to upload each part. 
		part, err := bucket.UploadPart(imur, fd, chunk.Size, chunk.Number)
		if err != nil {
			log.Fatalf("Failed to upload part %d of '%s': %v", chunk.Number, objectName, err)
		}
		parts = append(parts, part)
	}

	// Step 3: Complete the multipart upload task. Disable overwrites between objects that have the same names. 
	cmur, err := bucket.CompleteMultipartUpload(imur, parts, forbidWrite)
	if err != nil {
		log.Fatalf("Failed to complete multipart upload for '%s': %v", objectName, err)
	}

	log.Printf("Multipart upload completed successfully for '%s'. cmur: %v", objectName, cmur)
}

Referências