Copying Objects

This topic describes how to copy objects in Object Storage. You can copy objects to other buckets in the same region and to buckets in other regions.

Required IAM Policy

Warning

Object copy will not work if you do not authorize the Object Storage service to copy objects on your behalf. See Service Permissions for more information.

User Permissions

To use Oracle Cloud Infrastructure, you must be given the required type of access in a An IAM document that specifies who has what type of access to your resources. It is used in different ways: to mean an individual statement written in the policy language; to mean a collection of statements in a single, named "policy" document (which has an Oracle Cloud ID (OCID) assigned to it); and to mean the overall body of policies your organization uses to control access to resources. written by an administrator, whether you're using the Console or the REST API with an SDK, CLI, or other tool. If you try to perform an action and get a message that you don’t have permission or are unauthorized, confirm with your administrator the type of access you've been granted and which A collection of related resources that can be accessed only by certain groups that have been given permission by an administrator in your organization. you should work in.

You must have the required access to both the source and destination buckets when performing an object copy. You must also have permissions to manage objects in the source and destination buckets.

Service Permissions

To enable object copy, you must authorize the service to manage objects on your behalf. To do so, create the following policy:

allow service objectstorage-<region_name> to manage object-family in compartment <compartment_name>

Because Object Storage is a regional service, you must authorize the Object Storage service for each region that will be carrying out copy operations on your behalf. For example, you might authorize the Object Storage service in region us-ashburn-1 to manage objects on your behalf. Once you do this, you will be able to initiate the copy of an object stored in a us-ashburn-1 bucket to a bucket in any region, assuming that your user account has the required permissions to manage objects within the source and destination buckets.

Copy Object Work Requests

The Object Storage service handles copy requests asynchronously. The service creates a queue for copy requests, and then processes the requests as system resources become available. To provide visibility for in-progress copy operations, Object Storage creates a work request. You can track the progress of the copy operation by monitoring the status of the work request.

The work request statuses are:

accepted

The copy request is in the work request queue to be processed.

in progress

The object is currently being copied.

succeeded

The copy operation has successfully completed.

canceling

The copy request is in the process of being canceled.

canceled

The copy request has been canceled.

failed

The copy operation has failed. Work requests that do not complete due to overwrite rules or insufficient user authorizations are assigned the failed status.

Copy Object Overwrite Rules

You can use overwrite rules to control the copying of objects based on their entity tag (ETag) values.

Overwrite destination object: Use this option when you do not wish to limit a copy operation by an ETag value. This option is the default. This option can be used for any copy operation, regardless of whether or not it involves overwriting an existing object.

Do not overwrite any destination object: Use this option to prevent the overwriting an existing copy of an object in the destination location, regardless of the destination object's ETag value.

Overwrite destination object only if it matches the specified ETag: Use this option to prevent the accidental overwriting of an object in the destination location that does not have the specified ETag. When you use this option, the copy operation only succeeds if the ETag you supply when initiating the copy request matches the ETag of the destination object.

Copy object only if the source matches the specified ETag: When you use this option, the copy operation only succeeds if the ETag you supply when initiating the copy request matches the ETag of the source object. For objects that are intentionally updated and overwritten as part of data management activity, this option ensures that only the specified version of the object (as indicated by the ETag) is allowed to be copied. If the object's ETag value changes after the copy work request is created, but before the copy operation is executed, the copy operation will not complete.

Warning

If you overwrite an object, the operation cannot be undone.

Scope and Constraints

Objects cannot be copied directly from Archive Storage. To copy objects that are currently in Archive Storage, you must first restore the object to the standard Object Storage tier. Objects can be copied directly to Archive Storage tier buckets from the standard Object Storage tier. When you copy an objects into an Archive Storage bucket, the copy of the object is immediately archived.

You must specify an existing target bucket for the copy request. Buckets cannot be created automatically by the copy operation.

When an object is copied, the destination object receives a new ETag value.

If you rename, overwrite, or delete a source object while a copy operation is taking place, the copy operation fails and the destination object is not created or overwritten.

For copy operations that overwrite an existing destination object, if you rename, overwrite, or delete the source object independently of the ongoing copy operation, the copy operation fails.

Bulk copying is not supported. You must identify a single object in the request to be copied.

Using the Console

The Oracle Cloud InfrastructureConsole consumes the REST API and is subject to the same considerations as any OCI client.

Open the navigation menu. Under Core Infrastructure, click Object Storage.

Choose the compartment that contains the bucket that contains your object.

Select the bucket containing the object that you want to copy.

Click Objects under Resources to display a list of objects in the bucket.

For the object you want to copy (the source object), click the Actions icon (three dots), and then click Copy.

In the Copy dialog, enter the following:

Destination Namespace: The Object Storage Namespace of the destination bucket for your copied object. The namespace string of your tenancy is supplied as the default value.

Destination Region: The Oracle Cloud Infrastructure region containing the destination bucket for your copied object. Your tenancy must be subscribed to a region in order for you to copy an object to a bucket in that region.

Destination Bucket:The destination bucket for your copied object. This bucket must already exist. The copy operation cannot create a new bucket for the destination object.

Etag Match (optional): Enter an ETag if you wish to use an overwrite rule that requires an ETag match on the source or destination object. This field is only enabled for copy requests that contain ETag matching overwrite rules.

Click Copy Object.

A Work request submitted dialog confirms that your copy request was submitted successfully.

Open the navigation menu. Under Core Infrastructure, click Object Storage.

Choose the compartment containing your bucket.

Click the bucket name of the bucket containing the object being copied.

Click Work Requests under Resources.

A list of work requests is displayed. The status of each work request is displayed, along with request details including object name, request ID, and the destination bucket's name, region, and namespace.

Use the work-request get command to get the status of an object copy work request using the work request ID. If you do not have the work request ID, you can get a list of work requests, including the request IDs, for a specified compartment using the work-request list command.

Open a command prompt and run oci os work-request get to get the status of a work request: