edit-icon download-icon

Manage objects

Last Updated: Sep 10, 2018

You can use the Python SDK to list, delete, and copy objects, view object information, and change object metadata.

List objects

The Python SDK provides a series of iterators for you to list objects and perform multipart upload.

Simple list

The following code lists 10 files in a bucket:

  1. # -*- coding: utf-8 -*-
  2. import oss2
  3. from itertools import islice
  4. auth = oss2.Auth ('Your AccessKeyID', 'Your AccessKeySecret')
  5. bucket = oss2.Bucket (auth, 'Your endpoint', 'your bucket name')
  6. for b in islice(oss2.ObjectIterator(bucket), 10):
  7. print(b.key)

List objects by prefix

The following code only lists all the objects prefixed with img-:

  1. for obj in oss2.ObjectIterator(bucket, prefix='img-'):
  2. print(obj.key)

Simulate a folder

A bucket on OSS is flat-structured, because OSS has no folders or directories. You can add / to the object name to stimulate a folder. When listing objects, you must set the delimiter parameter (the directory delimiter) to /, and OSS determines whether it is a folder by identifying whether it is a CommonPrefix. For more information, see Folder simulation.

The following code lists all the content under a root directory:

  1. for obj in oss2.ObjectIterator(bucket, delimiter='/'):
  2. if obj.is_prefix(): # Folder
  3. print('directory: ' + obj.key)
  4. else: # Object
  5. print('file: ' + obj.key)

Note: Folder listing stimulation is less efficient and is not recommended.

Identify whether an object exists

You can use object_exists to determine whether the object exists. If the returned value is true, it indicates that the object exists. If the returned value is false, it indicates that the object does not exist.

  1. exist = bucket.object_exists('remote.txt')
  2. if exist:
  3. print('object exist')
  4. else:
  5. print('object not eixst')

Delete an object

The following code deletes a single object:

  1. bucket.delete_object('remote.txt')

You can delete multiple objects (up to 1,000 objects). The following code deletes three objects and prints the names of successfully-deleted objects:

  1. result = bucket.batch_delete_objects(['a.txt', 'b.txt', 'c.txt'])
  2. print('\n'.join(result.deleted_keys))

Copy an object

The following code copies the content of source.txt in a bucket named src-bucket to the target.txt object in the current bucket.

  1. bucket.copy_object('src-bucket', 'source.txt', 'target.txt')

Copy a large object

When an object is large, multipart copy is recommended to avoid time-out due to a large object size. Similar to multipart upload, multipart copy is completed in three steps:

  1. Initialization (Bucket.init_multipart_upload): Get an Upload ID.

  2. Copy parts (Bucket.upload_part_copy): Each part of the source object is copied as a part of the target object.

  3. Complete multipart copy (Bucket.complete_multipart_copy): Multipart copy is completed to generate the target object.

For example,

  1. from oss2.models import PartInfo
  2. from oss2 import determine_part_size
  3. src_key = 'remote.txt'
  4. dst_key = 'remote-dst.txt'
  5. total_size = bucket.head_object(src_key).content_length
  6. part_size = determine_part_size(total_size, preferred_size=100 * 1024)
  7. # Part initialization
  8. upload_id = bucket.init_multipart_upload(dst_key).upload_id
  9. parts = []
  10. # Copy parts one by one
  11. part_number = 1
  12. offset = 0
  13. while offset < total_size:
  14. num_to_upload = min(part_size, total_size - offset)
  15. byte_range = (offset, offset + num_to_upload - 1)
  16. result = bucket.upload_part_copy(bucket.bucket_name, src_key, byte_range,
  17. dst_key, upload_id, part_number)
  18. parts.append(PartInfo(part_number, result.etag))
  19. offset += num_to_upload
  20. part_number += 1
  21. # Complete multipart upload
  22. bucket.complete_multipart_upload(dst_key, upload_id, parts)

Change the object metadata

The following code changes the custom object metadata:

  1. bucket.update_object_meta('story.txt', {'x-oss-meta-author': 'O. Henry'})
  2. bucket.update_object_meta('story.txt', {'x-oss-meta-price': '100 dollar'})

The previous value of the custom object metadata (the HTTP header prefixed with x-oss-meta-) is overwritten each time the custom object metadata is called.

In the preceding example, the custom object metadata x-oss-meta-author is deleted during the second call.

Other information such as Content-Type can also be changed:

  1. bucket.update_object_meta('story.txt', {'Content-Type': 'text/plain'})

Note: This call changed the Content-Type and cleared the previous custom object metadata.

View the object access permission

  1. print(bucket.get_object_acl('story.txt').acl)

Note: The object has four access ACLs: default (default value), private (private-read-write), public-read (public-read and private-write), and public-read-write (public-read-write). For more information, see Object-level permissions.

Set object access permissions

Set the object access permission to public-read:

  1. bucket.put_object_acl('story.txt', oss2.OBJECT_ACL_PUBLIC_READ)

Note: The object has four access ACLs: default (default value), private (private-read-write), public-read (public-read and private-write), and public-read-write (public-read-write). They are mapped to oss2.OBJECT_ACL_DEFAULT, oss2.OBJECT_ACL_PRIVATE, oss2.OBJECT_ACL_PUBLIC_READ and oss2.OBJECT_ACL_PUBLIC_READ_WRITE respectively.

Thank you! We've received your feedback.