Todos os produtos
Search
Central de documentação

Object Storage Service:Cross-region replication within the same account

Última atualização: Jul 07, 2026

A replicação entre regiões na mesma conta copia automaticamente e de forma assíncrona (quase em tempo real) as operações em objetos, como criação, atualizações e exclusões, de um bucket de origem em uma região para um bucket de destino em outra região sob a mesma conta. Este tópico descreve como configurar a replicação entre regiões na mesma conta.

Pré-requisitos

  • Crie um bucket (Bucket A) em uma região específica para servir como bucket de origem. Anote o ID da conta, o nome do Bucket A e sua região.

  • Crie outro bucket (Bucket B) em uma região diferente sob a mesma conta para servir como bucket de destino. Anote o nome do Bucket B e sua região.

Tipos de função

Ao configurar a replicação entre regiões, especifique uma função que o Object Storage Service (OSS) possa assumir para replicar objetos entre os buckets de origem e de destino. Use qualquer um dos seguintes tipos de função.

Importante

Um usuário RAM precisa ter as permissões ram:CreateRole, ram:GetRole, ram:ListPoliciesForRole e ram:AttachPolicyToRole para criar uma função. No entanto, conceder permissões relacionadas a funções, como ram:CreateRole e ram:GetRole, a um usuário RAM representa um risco de segurança. Para maior segurança, use sua conta Alibaba Cloud para criar a função RAM e conceder as permissões necessárias. O usuário RAM poderá então usar a função diretamente.

(Recomendado) Criar uma nova função

Ao criar uma regra de replicação entre regiões, escolha criar uma nova função. O sistema cria automaticamente uma função com nome no formato oss-replication-{uuid}. A política de permissão anexada a essa função depende da escolha de replicar ou não objetos criptografados com o Key Management Service (KMS).

  • Replicar objetos criptografados pelo KMS

    Após a criação da função, siga as instruções na tela para conceder permissões. Depois de autorizada, a função terá uma política de permissão refinada para replicação do bucket de origem para o bucket de destino, além da política AliyunKMSCryptoUserAccess para gerenciar o Key Management Service (KMS).

  • Não replicar objetos criptografados pelo KMS

    Após a criação da função, siga as instruções na tela para conceder permissões. Depois de autorizada, a função terá uma política de permissão refinada para replicação do bucket de origem para o bucket de destino.

AliyunOSSRole

Ao criar uma regra de replicação entre regiões, selecione AliyunOSSRole para concluir a tarefa de replicação. Se você escolher esta função, diferentes políticas de permissão serão anexadas dependendo da opção de replicar objetos criptografados pelo KMS.

  • Replicar objetos criptografados pelo KMS

    Se você selecionar AliyunOSSRole, as políticas AliyunOSSFullAccess (para gerenciar o Object Storage Service) e AliyunKMSCryptoUserAccess (para gerenciar o Key Management Service) serão anexadas automaticamente à função.

    Aviso

    Esta função tem acesso total a todos os buckets e chaves KMS sob sua conta. Como as permissões são amplas, use esta função com cautela.

  • Não replicar objetos criptografados pelo KMS

    Se você selecionar AliyunOSSRole, a política AliyunOSSFullAccess (para gerenciar o Object Storage Service) será anexada automaticamente à função.

    Aviso

    Esta função tem acesso total a todos os buckets sob sua conta. Como as permissões são amplas, use esta função com cautela.

Função personalizada

Ao criar uma regra de replicação entre regiões, utilize uma função personalizada para concluir a tarefa de replicação. Crie a função personalizada no console RAM e conceda as permissões necessárias a ela.

  1. Crie uma função de serviço regular.

    Durante a criação da função, selecione Alibaba Cloud Service como entidade confiável e OSS como serviço confiável. Para mais informações, consulte Criar uma função de serviço regular.

  2. Conceda permissões à função.

    Conceda permissões à função de uma das seguintes maneiras.

    Anexar política do sistema

    Aviso

    Anexe a política de sistema AliyunOSSFullAccess à função RAM. Por padrão, AliyunOSSFullAccess fornece permissões totais sobre todos os buckets da conta atual. Use esta política com cautela.

    Para replicar objetos criptografados pelo KMS para o bucket de destino, anexe também a política de sistema AliyunKMSFullAccess à função.

    Para mais informações, consulte Gerenciar permissões para uma função RAM.

    Anexar política personalizada

    Utilize uma política RAM para conceder as permissões mínimas necessárias para a replicação do bucket de origem (src-bucket) para o bucket de destino (dest-bucket).

    Nota

    Substitua os nomes dos buckets de origem e de destino pelos nomes reais dos seus buckets.

    {
       "Version":"1",
       "Statement":[
          {
             "Effect":"Allow",
             "Action":[
                "oss:ReplicateList",
                "oss:ReplicateGet"
             ],
             "Resource":[
                "acs:oss:*:*:src-bucket",
                "acs:oss:*:*:src-bucket/*"
             ]
          },
          {
             "Effect":"Allow",
             "Action":[
                "oss:ReplicateList",
                "oss:ReplicateGet",
                "oss:ReplicatePut",
                "oss:ReplicateDelete"
             ],
             "Resource":[
                "acs:oss:*:*:dest-bucket",
                "acs:oss:*:*:dest-bucket/*"
             ]
          }
       ]
    }

    Para mais informações, consulte Gerenciar permissões para uma função RAM.

    Nota

    Para replicar objetos criptografados pelo KMS para o bucket de destino, anexe também a política de sistema AliyunKMSFullAccess à função.

Importante

Ao replicar dados entre regiões na mesma conta, o OSS valida apenas a política de permissão da função RAM usada para a replicação. Ele não verifica as políticas de bucket dos buckets de origem ou de destino.

Procedimento

Console do OSS

  1. Faça login no console do OSS.

  2. No painel de navegação à esquerda, clique em Buckets. Em seguida, clique em no nome do bucket de origem.

  3. No painel de navegação à esquerda, escolha Data Management > CRR.

  4. Na aba CRR, clique em CRR.

  5. No painel CRR, configure os parâmetros conforme descrito na tabela a seguir.

    Seção

    Parâmetro

    Descrição

    Configure Destination Bucket

    Source Bucket

    Região e nome do bucket de origem.

    Destination Bucket

    Selecione Select a bucket that belongs to the Alibaba Cloud account. Em seguida, nas listas suspensas, selecione a região e o nome do bucket de destino.

    Objects to Replicate

    Selecione os objetos de origem a serem replicados.

    • Synchronize all files: Replica todos os objetos do bucket de origem para o bucket de destino.

    • Objects with Specified Prefix: Replica objetos com um prefixo especificado para o bucket de destino. Adicione até 10 prefixos. Para aumentar esse limite, entre em contato com o Suporte Técnico para solicitar um aumento até o máximo de 100.

    Object Tagging

    Nota

    Para configurar este parâmetro, atenda às seguintes condições:

    • Você já configurou tags de objeto.

    • As caixas de seleção Replicate Deletion Markers e Replicate Deletions of Specific Object Versions estão desmarcadas.

    Marque a caixa de seleção Configure Rules para replicar objetos com tags específicas para o bucket de destino. Adicione até 10 tags (pares chave-valor). Após adicionar as tags, selecione uma das seguintes políticas de filtragem:

    • Include all tags: Replica um objeto somente se todas as suas tags estiverem incluídas no conjunto de tags definido na regra de filtro.

    • Include any one tag: Replica um objeto se pelo menos uma de suas tags estiver incluída no conjunto de tags definido na regra de filtro.

    Replicate KMS-Encrypted Source Objects

    Indique se deseja replicar objetos criptografados pelo KMS para o bucket de destino.

    • Yes: Selecione esta opção para replicar objetos para o bucket de destino caso os objetos de origem ou o bucket de destino estejam criptografados com uma chave gerenciada pelo KMS (SSE-KMS com um CMK ID especificado).

      Nota

      Chame as operações HeadObject e GetBucketEncryption para consultar o status de criptografia do objeto de origem e do bucket de destino, respectivamente.

    • No: Não replica objetos criptografados pelo KMS para o bucket de destino.

    CMK ID

    Especifique a chave KMS para criptografar os objetos de destino.

    Crie primeiro uma chave KMS no console KMS na mesma região do bucket de destino. Para mais informações, consulte Criar uma chave.

    RAM Role

    Recomendamos selecionar New RAM Role. Na lista suspensa, escolha esta opção e siga as instruções na tela para conceder permissões.

    Também é possível selecionar AliyunOSSRole ou uma função personalizada. Para mais detalhes sobre esses tipos de função, consulte Tipos de função.

    Configure Replication Policy

    Replicate Historical Data

    Defina se deseja replicar objetos existentes que estavam no bucket de origem antes da entrada em vigor da regra de replicação entre regiões.

    • Yes: Replica dados históricos existentes para o bucket de destino.

      Importante

      Ao replicar dados históricos, objetos do bucket de origem podem sobrescrever objetos com o mesmo nome no bucket de destino. Para evitar perda de dados, recomendamos ativar o versionamento tanto no bucket de origem quanto no de destino.

    • No: Replica apenas objetos carregados ou atualizados após a entrada em vigor da regra de replicação entre regiões.

    Copy Delete Operation

    Escolha se deseja replicar operações de exclusão do bucket de origem para o bucket de destino.

    Nota

    Esta opção aparece se o versionamento não estiver ativado no bucket de origem. Caso o versionamento esteja ativado, esta opção é substituída por duas configurações separadas: Copy Delete Marker e Copy Delete Operation of Specified Version.

    • Yes (para cenários onde é necessário compartilhar e acessar o mesmo conjunto de dados): Replica operações de criação, atualização e exclusão de objetos no bucket de origem para o bucket de destino.

      Importante

      Com esta política, todas as operações de criação, atualização e exclusão são replicadas. Ao excluir um objeto do bucket de origem, seja manualmente ou por meio de uma regra de ciclo de vida, o objeto correspondente no bucket de destino também é excluído e não pode ser recuperado.

    • No (para cenários de recuperação de desastres): Replica apenas operações de criação e atualização de objetos no bucket de origem. As operações de exclusão não afetam o bucket de destino.

      Nota

      Isso evita perda acidental de dados no bucket de destino causada por exclusões manuais ou automáticas via regras de ciclo de vida no bucket de origem.

    Copy Delete Marker

    Determine se marcadores de exclusão devem ser replicados do bucket de origem para o bucket de destino.

    • Replicate: Quando um objeto é excluído do bucket de origem sem especificar um ID de versão, o OSS cria um marcador de exclusão no bucket de origem, que é então replicado para o bucket de destino. Adequado para cenários de compartilhamento e acesso ao mesmo conjunto de dados, garantindo consistência entre os buckets.

      Importante

      Com esta política, ao excluir um objeto do bucket de origem, manualmente ou por regra de ciclo de vida, um marcador de exclusão é replicado para o bucket de destino, tornando os dados inacessíveis também nesse local.

    • Do not replicate (para cenários de recuperação de desastres): Marcadores de exclusão criados no bucket de origem não são replicados para o bucket de destino. Isso previne efetivamente a perda de dados no bucket de destino causada por exclusões acidentais ou automáticas no bucket de origem.

    Copy Delete Operation of Specified Version

    Decida se a exclusão permanente de uma versão específica de objeto deve ser replicada do bucket de origem para o bucket de destino.

    Nota

    Após criar uma regra de replicação de dados, alterações na classe de armazenamento de objetos no bucket de origem causadas por regras de ciclo de vida ou operações CopyObject não são sincronizadas com o bucket de destino. Além disso, o atributo de último acesso (x-oss-last-access-time) dos objetos no bucket de origem não é sincronizado.

    • Replicate: Quando uma versão específica de um objeto de origem, incluindo versões atuais e não atuais, é excluída permanentemente, a versão correspondente no bucket de destino também é excluída permanentemente. Ideal para cenários que exigem identidade total entre os dados de origem e destino.

      Importante

      Com esta política, uma versão de objeto excluída permanentemente do bucket de origem não poderá ser recuperada pelo bucket de destino. Escolha esta opção com cautela.

    • Do not replicate (para cenários de recuperação de desastres): Quando uma versão específica de um objeto de origem é excluída permanentemente, a versão correspondente no bucket de destino não é excluída. Isso protege os dados no bucket de destino contra operações de exclusão permanente no bucket de origem.

    Se um objeto for carregado no bucket de origem usando upload multipartido, a operação de upload de cada parte será replicada para o bucket de destino. Por fim, o objeto criado após a execução da operação CompleteMultipartUpload em todas as partes também será replicado para o bucket de destino.

    Para mais informações sobre o comportamento da replicação quando o versionamento é utilizado, consulte Replicação com versionamento.

    Configure Replication Speed

    Acceleration Type

    Somente Transfer Acceleration é compatível. A aceleração de transferência melhora a velocidade da replicação entre regiões dentro e fora da China continental. Ao ativar a aceleração de transferência, uma taxa adicional é cobrada. Para mais informações sobre faturamento, consulte Taxas de aceleração de transferência.

    RTC

    Nota

    O RTC para tarefas CRR só pode ser ativado entre as seguintes regiões na China continental: China (Hangzhou), China (Shanghai), China (Qingdao), China (Beijing), China (Zhangjiakou) e China (Shenzhen).

    O RTC para tarefas CRR só pode ser ativado entre as regiões US (Silicon Valley) e US (Virginia).

    Para tarefas que não envolvem replicação de dados históricos, o RTC entra em vigor 15 minutos após a ativação. Para tarefas que envolvem replicação de dados históricos, o RTC entra em vigor cerca de uma hora após a conclusão da replicação dos dados históricos. Uma vez ativo, o RTC garante que 99,99% dos novos objetos gravados sejam replicados dentro de 10 minutos. A ativação do RTC gera taxas de RTC.

  6. Clique em OK e, na caixa de diálogo exibida, clique em Enable.

    • Após a criação de uma regra de replicação entre regiões, não é possível editá-la ou excluí-la.

    • A tarefa de replicação inicia de 3 a 5 minutos após a configuração da regra de replicação entre regiões. Acompanhe o progresso da replicação na aba CRR do bucket de origem.

    • Como a replicação entre regiões é assíncrona, o tempo necessário para replicar dados para o bucket de destino depende do tamanho dos dados, variando geralmente de alguns minutos a várias horas.

SDK do Alibaba Cloud

Somente os SDKs Java, Python e Go oferecem suporte à replicação entre regiões na mesma conta.

Java

import com.aliyun.oss.*;
import com.aliyun.oss.common.auth.*;
import com.aliyun.oss.common.comm.SignVersion;
import com.aliyun.oss.model.AddBucketReplicationRequest;

public class Demo {

    public static void main(String[] args) throws Exception {
        // The endpoint of the China (Hangzhou) region is used in this example. Replace it with the actual endpoint of your region.
        String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
        // Specify the region that corresponds to the endpoint, for example, cn-hangzhou.
        String region = "cn-hangzhou";
        // We strongly recommend that you do not hard-code your access credential in your code. This can lead to credential leaks and compromise the security of all resources in your account. This example uses environment variables to obtain the access credential. Before running this code, configure the environment variables.
        EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
        // Specify the name of the source bucket.
        String bucketName = "src-bucket";
        // Specify the destination bucket to which you want to replicate data. The destination and source buckets must belong to the same account.
        String targetBucketName = "dest-bucket";
        // Specify the region where the destination bucket is located. The destination and source buckets must be in different regions.
        String targetBucketLocation = "oss-cn-shanghai";

        // Create an OSSClient instance.
        // Call the shutdown method to release resources when the OSSClient instance is no longer used.
        ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
        // Explicitly declare the use of the V4 signature algorithm.
        clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);
        OSS ossClient = OSSClientBuilder.create()
                .endpoint(endpoint)
                .credentialsProvider(credentialsProvider)
                .clientConfiguration(clientBuilderConfiguration)
                .region(region)
                .build();

        try {
            AddBucketReplicationRequest request = new AddBucketReplicationRequest(bucketName);
            request.setTargetBucketName(targetBucketName);
            request.setTargetBucketLocation(targetBucketLocation);
            // By default, historical data is replicated. Set this to false to disable historical data replication.
            request.setEnableHistoricalObjectReplication(false);
            // Specify the name of the role that authorizes OSS to perform data replication. This role must have been granted permissions to perform cross-region replication on the source bucket and to receive replicated objects in the destination bucket.
            request.setSyncRole("yourRole");
            // Specify whether OSS replicates objects created with SSE-KMS encryption.
            //request.setSseKmsEncryptedObjectsStatus("Enabled");
            // Specify the SSE-KMS key ID. This element is required if Status is set to Enabled.
            //request.setReplicaKmsKeyID("3542abdd-5821-4fb5-a425-90adca***");
            //List prefixes = new ArrayList();
            //prefixes.add("image/");
            //prefixes.add("video");
            //prefixes.add("a");
            //prefixes.add("A");
            // Specify the prefix of the objects to be replicated. If you specify a prefix, only objects with that prefix are replicated to the destination bucket.
            //request.setObjectPrefixList(prefixes);
            //List actions = new ArrayList();
            //actions.add(AddBucketReplicationRequest.ReplicationAction.PUT);
            // Replicate create and update operations on objects in the source bucket to the destination bucket.
            //request.setReplicationActionList(actions);
            ossClient.addBucketReplication(request);
        } catch (OSSException oe) {
            System.out.println("Caught an OSSException, which means your request made it to OSS, "
                    + "but was rejected with an error response for some reason.");
            System.out.println("Error Message:" + oe.getErrorMessage());
            System.out.println("Error Code:" + oe.getErrorCode());
            System.out.println("Request ID:" + oe.getRequestId());
            System.out.println("Host ID:" + oe.getHostId());
        } catch (ClientException ce) {
            System.out.println("Caught an ClientException, which means the client encountered "
                    + "a serious internal problem while trying to communicate with OSS, "
                    + "such as not being able to access the network.");
            System.out.println("Error Message:" + ce.getMessage());
        } finally {
            if (ossClient != null) {
                ossClient.shutdown();
            }
        }
    }
}        

Python

# -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider
from oss2.models import ReplicationRule
# Obtain the access credential from environment variables. Before running this example code, ensure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are set.
auth = oss2.ProviderAuth(EnvironmentVariableCredentialsProvider())
# Specify the endpoint of the region where the source bucket is located. For example, for the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com.
# Specify the name of the source bucket, for example, src-bucket.
bucket = oss2.Bucket(auth, 'https://oss-cn-hangzhou.aliyuncs.com', 'src-bucket')
replica_config = ReplicationRule(
    # Specify the destination bucket to which you want to replicate data. The destination and source buckets must belong to the same account.
    target_bucket_name='dest-bucket',
    # Specify the region where the destination bucket is located. The destination and source buckets must be in different regions.
    target_bucket_location='oss-cn-shanghai',
    # Specify the name of the role that authorizes OSS to perform data replication. This role must have been granted permissions to perform cross-region replication on the source bucket and to receive replicated objects in the destination bucket.
    sync_role_name='roleNameTest',
)

# Specify the prefix of the objects to be replicated. If you specify a prefix, only objects with that prefix are replicated to the destination bucket.
# prefix_list = ['prefix1', 'prefix2']
# Configure the data replication rule.
# replica_config = ReplicationRule(
     # prefix_list=prefix_list,
     # Replicate create and update operations on objects in the source bucket to the destination bucket.
     # action_list=[ReplicationRule.PUT],
     # Specify the destination bucket to which you want to replicate data. The destination and source buckets must belong to the same account.
     # target_bucket_name='dest-bucket',
     # Specify the region where the destination bucket is located. The destination and source buckets must be in different regions.
     # target_bucket_location='yourTargetBucketLocation',
     # By default, historical data is replicated. Set this to `False` to disable historical data replication.
     # is_enable_historical_object_replication=False,
     # Specify the data transfer link used for data replication.
     # target_transfer_type='oss_acc',    
  #)

# Enable data replication.
bucket.put_bucket_replication(replica_config)

Go

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 global variables.
var (
	region     string // Region in which the bucket is located.
	bucketName string // Name of the bucket.
)

// 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(&bucketName, "bucket", "", "The name of the bucket.")
}

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

	var (
		targetBucket   = "target bucket name" // Name of the destination bucket.
		targetLocation = "oss-cn-beijing"     // Region in which the destination bucket is located.
	)

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

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

	// Load the default configurations 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 to enable data replication for the bucket.
	request := &oss.PutBucketReplicationRequest{
		Bucket: oss.Ptr(bucketName), // Name of the bucket.
		ReplicationConfiguration: &oss.ReplicationConfiguration{
			Rules: []oss.ReplicationRule{
				{
					RTC: &oss.ReplicationTimeControl{
						Status: oss.Ptr("enabled"), // Enable the RTC feature.
					},
					Destination: &oss.ReplicationDestination{
						Bucket:       oss.Ptr(targetBucket),   // Name of the destination bucket.
						Location:     oss.Ptr(targetLocation), // Region in which the destination bucket is located.
						TransferType: oss.TransferTypeOssAcc,  // Type of transfer.
					},
					HistoricalObjectReplication: oss.HistoricalObjectReplicationEnabled, // Enable the historical data replication feature.
				},
			},
		},
	}

	// Enable data replication.
	result, err := client.PutBucketReplication(context.TODO(), request)
	if err != nil {
		log.Fatalf("failed to put bucket replication %v", err)
	}

	// Display the result.
	log.Printf("put bucket replication result:%#v\n", result)
}

CLI ossutil

Para instruções detalhadas sobre como usar a ferramenta de linha de comando ossutil para ativar a replicação entre regiões, consulte put-bucket-replication.

API REST

Caso sua aplicação tenha requisitos específicos, faça solicitações diretas à API REST. Isso exige escrever código manualmente para calcular a assinatura. Para mais informações, consulte PutBucketReplication.

Tópicos relacionados