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 Policies

To use Oracle Cloud Infrastructure, you must be granted security access in a policy  by an administrator. This access is required whether you're using the Console or the REST API with an SDK, CLI, or other tool. If you get a message that you don’t have permission or are unauthorized, verify with your administrator what type of access you have and which compartment  you should work in.

If you're new to policies, see Getting Started with Policies and Common Policies.

Caution

Object copy does 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

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.

For administrators:

  • You can create a policy that lets the specified IAM group manage Object Storage namespaces, buckets, and their associated objects in all compartments in the tenancy:

    Allow group <IAM_group_name> to manage object-family in tenancy
  • Alternatively, you can create policies that reduce the scope of access. For example, to let the specified group manage only buckets and objects in a particular compartment in the tenancy:

    Allow group <IAM_group_name> to manage buckets in compartment <compartment_name>

For more information about other alternatives for writing policies, see Details for Object Storage, Archive Storage, and Data Transfer.

Service Permissions

Because Object Storage is a regional service, you must authorize the Object Storage service for each region carrying out copy operations on your behalf. For example, you might authorize the Object Storage service in region US East (Ashburn) to manage objects on your behalf. Once you authorize the Object Storage service, you can copy an object stored in a US East (Ashburn) bucket to a bucket in another region.

To determine the region identifier value of an Oracle Cloud Infrastructure region, see Regions and Availability Domains.

For administrators:

To enable object copy, you must authorize the service to manage objects on your behalf:

  • You can create a policy that authorizes the service in the specified region to manage Object Storage namespaces, buckets, and their associated objects in all compartments in the tenancy:

    Allow service objectstorage-<region_identifier> to manage object-family in tenancy
  • Instead of using the policy verb manage, you can create a policy that reduces the scope of access by instead using one of the following statements:

    Allow service objectstorage-<region_identifier> to manage object-family where any {request.permission='OBJECT_READ', request.permission='OBJECT_INSPECT', request.permission='OBJECT_CREATE', request.permission='OBJECT_OVERWRITE', request.permission='OBJECT_DELETE'} in tenancy
    Allow service objectstorage-<region_identifier> to manage object-family in compartment <compartment_name> where any {request.permission='OBJECT_READ', request.permission='OBJECT_INSPECT', request.permission='OBJECT_CREATE', request.permission='OBJECT_OVERWRITE', request.permission='OBJECT_DELETE'}

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 when 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 copy is in progress.
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 because of overwrite rules or insufficient user authorizations are assigned the failed status.
You can determine the reason a copy failed in the following ways:

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 want 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 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: Use this option if you want the copy operation successful only 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.
Caution

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 objects into an Archive Storage bucket, the copy of the object is immediately archived.
  • Specify an existing target bucket for the copy request. The copy operation does not automatically create buckets.
  • When an object is copied, the destination object receives a new ETag value.
  • If you rename, overwrite, or delete a source object during a copy operation, the copy operation fails and the destination object is not created or overwritten.
  • Bulk copying is not supported. Identify a single object in the copy request.

Using the Console

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

To make a copy of an object
  1. Open the navigation menu. Under Core Infrastructure, click Object Storage.
  2. Choose the compartment that contains the bucket that contains your object.

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

  4. Click Objects under Resources to display a list of objects in the bucket.
  5. For the object you want to copy (the source object), click the Actions icon (three dots), and then click Copy.

  6. 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 for you to copy an object to a bucket in that region.
    • Destination Bucket: The name of the destination bucket for your copied object. Specify an existing target bucket. The copy operation does not automatically create buckets.
    • Destination Object Name: Optionally, you can specify a different destination object name. By default, the Destination Object Name is the same name as the object you are copying.
    • Overwrite Rule: Select the overwrite rule appropriate for your copy request. See Copy Object Overwrite Rules for information on the overwrite rule options.
  7. Click Copy Object.

    A dialog confirms that your copy request was submitted successfully.

To monitor the status of an object copy work request
  1. Open the navigation menu. Under Core Infrastructure, click Object Storage.
  2. Choose the compartment containing your bucket.

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

  4. Click Work Requests under Resources.

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

Using the Command Line Interface (CLI)

For information about using the CLI, see Command Line Interface (CLI). For a complete list of flags and options available for CLI commands, see the Command Line Reference.

To make a copy of an object
oci os object copy --namespace-name <object_storage_namespace> --bucket-name <source_bucket_name> --source-object-name <source_object> --destination-namespace <destination_namespace_string> --destination-region <destination_region> --destination-bucket <destination_bucket_name> --destination-object-name <destination_object_name>

For example:

oci os object copy --namespace-name ansh8lvru1zp  --bucket-name photos --source-object-name hummingbird.jpg --destination-namespace ansh8lvru1zp --destination-region uk-london-1 --destination-bucket UK_photos --destination-object-name hummingbird.jpg
To get the status of an object copy work request
oci os work-request get --work-request-id <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, see To get a list of work requests for a compartment.

To obtain the details of a failed copy work request
oci os work-request-errors list --work-request-id <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, see To get a list of work requests for a compartment.

To get a list of work requests for a compartment
oci os work-request list --compartment-id <compartment_id>
To cancel a copy object work request
oci os work-request cancel --work-request-id <request_id>