Utilize a operação PutBucketReplication para definir uma regra de replicação de dados em um bucket. O OSS oferece suporte à replicação entre regiões (CRR) e à replicação na mesma região (SRR).
Observações de uso
A replicação de dados copia objetos de forma assíncrona de um bucket de origem para um bucket de destino, abrangendo operações como criação, atualização e exclusão de objetos. Ao utilizar a replicação de dados, observe os seguintes pontos:
O processo de replicação é assíncrono. O tempo necessário para replicar os dados no bucket de destino varia conforme o volume de informações, podendo levar de alguns minutos a várias horas.
Os buckets de origem e de destino não podem ter o mesmo nome.
Na replicação entre regiões, os buckets de origem e de destino devem estar em data centers diferentes. Já na replicação na mesma região, ambos os buckets precisam residir no mesmo data center.
Para obter mais detalhes sobre a replicação de dados, consulte Introduction to cross-region replication e Introduction to same-region replication.
Sintaxe da solicitação
POST /?replication&comp=add HTTP/1.1
Date: GMT Date
Content-Length: ContentLength
Content-Type: application/xml
Authorization: SignatureValue
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
<?xml version="1.0" encoding="UTF-8"?>
<ReplicationConfiguration>
<Rule>
<RTC>
<Status>enabled or disabled</Status>
</RTC>
<PrefixSet>
<Prefix>prefix_1</Prefix>
<Prefix>prefix_2</Prefix>
</PrefixSet>
<Action>ALL or PUT</Action>
<Destination>
<Bucket>destbucket</Bucket>
<Location>oss-cn-hangzhou</Location>
<TransferType>oss_acc</TransferType>
</Destination>
<HistoricalObjectReplication>enabled or disabled</HistoricalObjectReplication>
<SyncRole>aliyunramrole</SyncRole>
<UserTaggings>
<FilterType>AND or OR</FilterType>
<UserTagging>
<Key>key1</Key>
<Value>value1</Value>
</UserTagging>
...
</UserTaggings>
</Rule>
</ReplicationConfiguration>Elementos da solicitação
|
Nome |
Tipo |
Obrigatório |
Exemplo |
Descrição |
|
ReplicationConfiguration |
Container |
Sim |
N/A |
Contêiner que armazena as regras de replicação de dados de um bucket. Nó pai: Nenhum Nó filho: Rule |
|
Rule |
Container |
Sim |
N/A |
Contêiner de uma regra de replicação de dados. Nó pai: ReplicationConfiguration Nós filhos: Destination, HistoricalObjectReplication, ID, UserTaggings, entre outros |
|
ID |
String |
Não |
first |
Identificador exclusivo da regra de replicação de dados. Nó pai: Rule Nós filhos: Nenhum |
|
PrefixSet |
Container |
Não |
N/A |
Contêiner para prefixos. É possível especificar até 10 prefixos em cada regra de replicação de dados. Nó pai: Rule Nó filho: Prefix |
|
Prefix |
String |
Não |
source1 |
Prefixo dos objetos a serem replicados. Somente os objetos correspondentes ao prefixo serão copiados para o bucket de destino.
Nó pai: PrefixSet Nós filhos: Nenhum |
|
Action |
String |
Não |
ALL |
Operações a serem replicadas no bucket de destino. Caso você defina uma ação, os dados recém-gravados e os históricos seguirão essa configuração. Especifique um ou mais dos valores válidos abaixo. Valores válidos:
Nó pai: Rule Nós filhos: Nenhum |
|
Destination |
Container |
Sim |
N/A |
Contêiner com as informações do bucket de destino. Nó pai: Rule Nós filhos: Bucket e Location |
|
Bucket |
String |
Sim |
destbucket |
Bucket de destino da replicação de dados. Nó pai: Destination Nós filhos: Nenhum |
|
Location |
String |
Sim |
oss-cn-hangzhou |
Região onde o bucket de destino está localizado. Nó pai: Destination Nós filhos: Nenhum |
|
TransferType |
String |
Sim |
oss_acc |
Link de transmissão utilizado na replicação de dados. Valores válidos:
Nó pai: Destination Nós filhos: Nenhum |
|
HistoricalObjectReplication |
String |
Não |
disabled |
Define se os dados históricos devem ser replicados. Determina se o conteúdo existente no bucket de origem antes da ativação da replicação será copiado para o destino. Valores válidos:
Nó pai: Rule Nós filhos: Nenhum |
|
SyncRole |
String |
Sim |
aliyunramrole |
Função do RAM autorizada pelo OSS para executar a replicação de dados. A replicação pode ocorrer dentro da mesma conta ou entre contas distintas. Em ambos os casos, conceda as permissões necessárias à função do RAM; caso contrário, a tarefa falhará. Para mais informações, consulte Data replication permissions. Nó pai: Rule Nós filhos: Nenhum |
|
SourceSelectionCriteria |
Container |
Não |
N/A |
Contêiner para condições adicionais de filtro que identificam os objetos de origem a replicar. Atualmente, o OSS permite definir filtros apenas para objetos criptografados com SSE-KMS. Nó pai: Rule Nó filho: SseKmsEncryptedObjects |
|
SseKmsEncryptedObjects |
Container |
Não |
N/A |
Contêiner para filtragem de objetos criptografados via SSE-KMS. Este elemento é obrigatório quando SourceSelectionCriteria é especificado na regra de replicação. Nó pai: SourceSelectionCriteria Nó filho: Status |
|
Status |
String |
Não |
Enabled |
Indica se o OSS deve replicar objetos criados com criptografia SSE-KMS. Valores válidos:
Nó pai: SseKmsEncryptedObjects Nós filhos: Nenhum |
|
EncryptionConfiguration |
Container |
Não |
N/A |
Configuração de criptografia para os objetos de destino. Obrigatório quando Status estiver definido como Enabled. Nó pai: Rule Nó filho: ReplicaKmsKeyID |
|
ReplicaKmsKeyID |
String |
Não |
c4d49f85-ee30-426b-a5ed-95e9139d**** |
ID da chave SSE-KMS. Campo obrigatório se Status for Enabled. Nó pai: EncryptionConfiguration Nós filhos: Nenhum |
|
RTC |
Container |
Não |
N/A |
Status do recurso de controle de tempo de replicação (RTC). Nó pai: Rule Nó filho: Status |
|
Status |
String |
Não |
Enabled |
Ativa ou desativa o recurso RTC. Configurável apenas em replicações entre regiões. Valores válidos:
Nó pai: RTC Nós filhos: Nenhum Nota
Para verificar quais regiões suportam o recurso RTC, consulte Regions that support RTC. |
|
UserTaggings |
Container |
Não |
N/A |
Contêiner para regras de filtro de tags. Após configurar este elemento, somente objetos com as tags especificadas serão replicados no bucket de destino. Ao definir UserTaggings, é obrigatório especificar FilterType e UserTagging. Nó pai: Rule Nós filhos: FilterType e UserTagging |
|
FilterType |
String |
Não |
OR |
Política de filtro de tags. Valor sensível a maiúsculas e minúsculas. Opções válidas:
Nó pai: UserTaggings Nós filhos: Nenhum |
|
UserTagging |
Container |
Não |
N/A |
Contêiner para um único par chave-valor de tag. Limite máximo de 10 tags. Não é permitido duplicar pares chave-valor. Nó pai: UserTaggings Nós filhos: Key e Value |
|
Key |
String |
Não |
env |
Chave da tag. Comprimento máximo de 128 caracteres, sensível a maiúsculas e minúsculas. Aceita letras, dígitos, espaços e os caracteres especiais: +‑=._:/ Nó pai: UserTagging Nós filhos: Nenhum |
|
Value |
String |
Não |
test |
Valor da tag. Comprimento máximo de 256 caracteres, sensível a maiúsculas e minúsculas. Aceita letras, dígitos, espaços e os caracteres especiais: +‑=._:/ Nó pai: UserTagging Nós filhos: Nenhum |
Esta operação também requer cabeçalhos comuns de solicitação, como Host e Date. Consulte Common request headers para mais detalhes.
Cabeçalhos de resposta
A operação retorna apenas cabeçalhos de resposta comuns. Veja Common response headers para mais informações.
Exemplos
Exemplo de solicitação 1 (política de filtro OR)
POST /?replication&comp=add HTTP/1.1
Host: oss-example.oss-cn-hangzhou.aliyuncs.com
Content-Type: application/xml
Content-Length: 186
Date: Thu, 17 Apr 2025 15:39:12 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=content-length,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
<?xml version="1.0" encoding="UTF-8"?>
<ReplicationConfiguration>
<Rule>
<RTC>
<Status>enabled</Status>
</RTC>
<PrefixSet>
<Prefix>source1</Prefix>
<Prefix>video</Prefix>
</PrefixSet>
<Action>PUT</Action>
<Destination>
<Bucket>destbucket</Bucket>
<Location>oss-cn-beijing</Location>
<TransferType>oss_acc</TransferType>
</Destination>
<HistoricalObjectReplication>enabled</HistoricalObjectReplication>
<SyncRole>aliyunramrole</SyncRole>
<SourceSelectionCriteria>
<SseKmsEncryptedObjects>
<Status>Enabled</Status>
</SseKmsEncryptedObjects>
</SourceSelectionCriteria>
<EncryptionConfiguration>
<ReplicaKmsKeyID>c4d49f85-ee30-426b-a5ed-95e9139d****</ReplicaKmsKeyID>
</EncryptionConfiguration>
<UserTaggings>
<FilterType>OR</FilterType>
<UserTagging>
<Key>env</Key>
<Value>test</Value>
</UserTagging>
<UserTagging>
<Key>dept</Key>
<Value>dev</Value>
</UserTagging>
</UserTaggings>
</Rule>
</ReplicationConfiguration>Exemplo de solicitação 2 (política de filtro AND)
POST /?replication&comp=add HTTP/1.1
Host: oss-example.oss-cn-hangzhou.aliyuncs.com
Content-Type: application/xml
Content-Length: 350
Date: Thu, 17 Apr 2025 16:00:00 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=content-length,Signature=b8d4e5f6a7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4
<?xml version="1.0" encoding="UTF-8"?>
<ReplicationConfiguration>
<Rule>
<PrefixSet>
<Prefix>source1</Prefix>
<Prefix>video</Prefix>
</PrefixSet>
<Action>PUT</Action>
<Destination>
<Bucket>destbucket</Bucket>
<Location>oss-cn-beijing</Location>
<TransferType>oss_acc</TransferType>
</Destination>
<HistoricalObjectReplication>disabled</HistoricalObjectReplication>
<SyncRole>aliyunramrole</SyncRole>
<UserTaggings>
<FilterType>AND</FilterType>
<UserTagging>
<Key>env</Key>
<Value>production</Value>
</UserTagging>
<UserTagging>
<Key>dept</Key>
<Value>finance</Value>
</UserTagging>
</UserTaggings>
</Rule>
</ReplicationConfiguration>Exemplo de resposta
HTTP/1.1 200 OK
x-oss-request-id: 534B371674E88A4D8906****
Date: Thu, 24 Sep 2025 15:39:12 GMT
Content-Length: 0
Connection: close
Server: AliyunOSSSDK
Confira abaixo os SDKs disponíveis para esta operação em diversas linguagens:
Ferramenta de linha de comando ossutil
Para consultar o comando ossutil equivalente a esta operação, veja put-bucket-replication.
Códigos de erro
|
Código de erro |
Código de status HTTP |
Descrição |
|
InvalidTargetBucket |
400 BadRequest |
Este erro ocorre pelos seguintes motivos:
|
|
InvalidTargetLocation |
400 BadRequest |
A localização do bucket de destino difere daquela especificada no XML da solicitação. |
|
BucketReplicationAlreadyExist |
400 BadRequest |
Já existe uma relação de replicação configurada do bucket de origem para o de destino. Para criar uma nova regra, remova primeiro a regra existente. |
|
BadReplicationLocation |
400 BadRequest |
O data center de destino informado é inválido. Utilize a operação GetBucketReplicationLocation para listar os data centers de destino válidos. |
|
NoReplicationLocation |
400 BadRequest |
Em replicações entre regiões, o data center do bucket de origem não possui um par compatível para esse tipo de replicação. Consulte Endpoints and data centers para ver a lista de data centers pareados para replicação entre regiões. |
|
TooManyReplicationRules |
400 BadRequest |
Mais de uma regra de replicação foi detectada na solicitação. Configure apenas uma regra de replicação de dados por solicitação. |
|
TooManyIncomingReplication |
400 BadRequest |
O bucket atingiu o limite máximo de 100 regras de replicação. Remova as regras desnecessárias e tente novamente. Cada bucket suporta até 100 regras de replicação. Se sua demanda superar esse limite, entre em contato com o suporte técnico. |
|
TooManyOutgoingReplication |
400 BadRequest |
O bucket atingiu o teto de 100 regras de replicação configuradas. Exclua as regras obsoletas antes de prosseguir. É permitido configurar até 100 regras de replicação por bucket. Caso precise ultrapassar esse limite, abra um chamado com o suporte técnico. |
|
MissingArgument |
400 BadRequest |
O link de transmissão de dados não foi especificado. |
|
InvalidArgument |
400 BadRequest |
O link de transmissão de dados informado não é suportado. |
|
ReplicationLocationNotSupportRtc |
400 BadRequest |
O recurso RTC não pode ser ativado nesta região. Verifique as regiões compatíveis com RTC em RTC regions. |
|
TooManyTaggings |
400 BadRequest |
A regra de replicação do bucket excede o limite de 10 tags permitidas. |
|
DuplicateReplicationRuleTaggings |
400 BadRequest |
A regra de replicação configurada contém tags com pares de chave e valor duplicados. |
|
DuplicateReplicationRuleTaggingKeys |
400 BadRequest |
FilterType está definido como AND na regra de replicação, mas existem chaves de tag duplicadas. |