Document Center

Manage objects

Last Updated: Dec 22, 2017

View all objects

You can list all objects in a bucket using the oss_list_object interface.

  1. aos_pool_t *p;
  2. oss_request_options_t *options;
  3. aos_status_t *s;
  4. aos_table_t *resp_headers;
  5. char *bucket_name = "<Name of your bucket>";
  6. aos_string_t bucket;
  7. oss_list_object_params_t *params;
  8. oss_list_object_content_t *content;
  9. int max_ret = 1000;
  10. char *key;
  12. aos_pool_create(&p, NULL);
  14. options = oss_request_options_create(p);
  15. init_options(options);
  17. aos_str_set(&bucket, bucket_name);
  18. params = oss_create_list_object_params(p);
  19. params->max_ret = max_ret;
  20. aos_str_set(&params->prefix, "<View the prefix of the object>");
  21. aos_str_set(&params->delimiter, "<View the delimiter of the object>");
  22. aos_str_set(&params->marker, "<View the start point of the object>");
  24. s = oss_list_object(options, &bucket, params, &resp_headers);
  25. if (aos_status_is_ok(s)) {
  26.     printf("get object succeeded\n");
  28.     /* Download objects */
  29.     aos_list_for_each_entry(content, &params->object_list, node) {
  30.     key = apr_psprintf(p, "%.*s", content->key.len, content->key.data);
  31.     }
  32. } else {
  33.     printf("get object failed\n");
  34. }
  36. aos_pool_destroy(p);

Notice:

  • By default, if a bucket contains more than 1,000 objects, only the first 1,000 objects are returned and the IsTruncated parameter in the returned results is true. The NextMarker is returned to serve as the start point of next read. To increase the quantity of returned objects, you can modify the max_ret parameter or use the marker parameter for multiple reads.
  • Complete code can be found at GitHub.

Create a simulate directory

OSS is an object-based storage service. It has no directory. The creation of a simulate directory is essentially the creation of an object with the size of 0. This object can be uploaded and downloaded as a normal object, but the console displays the object whose name ends with a slash (/) as a folder. So you can use the preceding method to create a simulate directory. 

  1. aos_pool_t *p;
  2. oss_request_options_t *options;
  3. aos_status_t *s;
  4. aos_table_t *headers;
  5. aos_table_t *resp_headers;
  6. char *bucket_name = "<Name of your bucket>";
  7. char *object_name = "<Your folder name/>";
  8. aos_string_t bucket;
  9. aos_string_t object;
  10. char *data = "";
  11. aos_list_t buffer;
  12. aos_buf_t *content;
  14. aos_pool_create(&p, NULL);
  16. options = oss_request_options_create(p);
  17. init_options(options);
  19. aos_str_set(&bucket, bucket_name);
  20. aos_str_set(&object, object_name);
  21. headers = aos_table_make(p, 0);
  23. aos_list_init(&buffer);
  24. content = aos_buf_pack(options->pool, data, strlen(data));
  25. aos_list_add_tail(&content->node, &buffer);
  26. s = oss_put_object_from_buffer(options, &bucket, &object, &buffer, headers, &resp_headers);
  27. if (aos_status_is_ok(s)) {
  28.     printf("create dir succeeded\n");
  29. } else {
  30.     printf("create dir failed\n");
  31. }
  32. aos_pool_destroy(p);

Note: Complete code can be found at GitHub.

Set the HTTP Header of an object

When uploading an object to OSS, except for the object content, you can specify certain attribute information for the object. The attribute information is called meta information. The metadata is stored together with the object during uploading, and returned together with the object during downloading. The following code sets the expiration time for an object:

  1. aos_pool_t *p;
  2. oss_request_options_t *options;
  3. aos_status_t *s;
  4. aos_table_t *headers;
  5. aos_table_t *resp_headers;
  6. char *bucket_name = "<Name of your bucket>";
  7. char *object_name = "<Name of your object>";
  8. aos_string_t bucket;
  9. aos_string_t object;
  10. char *data = "<object content>";
  11. aos_list_t buffer;
  12. aos_buf_t *content;
  14. aos_pool_create(&p, NULL);
  16. options = oss_request_options_create(p);
  17. init_options(options);
  19. aos_str_set(&object, object_name);
  20. aos_str_set(&bucket, bucket_name);
  21. headers = aos_table_make(p, 0);
  23. /* Set the HTTP header */
  24. headers = aos_table_make(p, 1);
  25. apr_table_set(headers, "Expires", "Fri, 28 Feb 2012 05:38:42 GMT"); 
  27. /* Read data into the buffer */
  28. aos_list_init(&buffer);
  29. content = aos_buf_pack(options->pool, data, strlen(data));
  30. aos_list_add_tail(&content->node, &buffer);
  31. s = oss_put_object_from_buffer(options, &bucket, &object, &buffer, headers, &resp_headers);
  32. if (aos_status_is_ok(s)) {
  33.     printf("put object succeeded\n");
  34. } else {
  35.     printf("put object failed\n");
  36. }
  38. aos_pool_destroy(p);

Notice:

  • The following options are available for you to set the HTTP header: Cache-Control, Content-Disposition, Content-Encoding, and Expires. For their introductions, see RFC2616.
  • Complete code can be found at GitHub.

Set user meta information

The OSS supports user-defined meta information for object description. For example:

  1. aos_pool_t *p;
  2. oss_request_options_t *options;
  3. aos_status_t *s;
  4. aos_table_t *headers;
  5. aos_table_t *resp_headers;
  6. char *bucket_name = "<Name of your bucket>";
  7. char *object_name = "<Name of your object>";
  8. aos_string_t bucket;
  9. aos_string_t object;
  10. char *data = "<object content>";
  11. aos_list_t buffer;
  12. aos_buf_t *content;
  14. aos_pool_create(&p, NULL);
  16. options = oss_request_options_create(p);
  17. init_options(options);
  19. aos_str_set(&bucket, bucket_name);
  20. aos_str_set(&object, object_name);
  21. headers = aos_table_make(p, 1);
  23. /* Set user-defined meta */
  24. apr_table_set(headers, "x-oss-meta-author", "oss");
  26. /* Upload data to OSS */
  27. aos_list_init(&buffer);
  28. content = aos_buf_pack(options->pool, data, strlen(data));
  29. aos_list_add_tail(&content->node, &buffer);
  30. s = oss_put_object_from_buffer(options, &bucket, &object, &buffer, headers, &resp_headers);
  31. if (aos_status_is_ok(s)) {
  32.     printf("put object succeeded\n");
  33. } else {
  34.     printf("put object failed\n");
  35. }
  36. aos_pool_destroy(p);

Notice:

  • Because the object meta information is stored in HTTP headers during object uploading/downloading, the meta information cannot contain any complex character according to HTTP.
  • A single object may have multiple similar parameters, but the total size of UserMetadata cannot exceed 8KB.

Get the metadata of the object

Sometimes you must get metadata related with the object after you upload the object to the OSS or before you read the object, such as the length or the object type. In this case, you can get the metadata of the object through the oss_object_head interface. The following codes gets the object length and type information: 

  1. void head_object()
  2. {
  3.     aos_pool_t *p = NULL;
  4.     aos_string_t bucket;
  5.     aos_string_t object;
  6.     oss_request_options_t *options = NULL;
  7.     aos_table_t *headers = NULL;
  8.     aos_table_t *resp_headers = NULL;
  9.     aos_status_t *s = NULL;
  10.     char *content_length_str = NULL;
  11.     char *object_type = NULL;
  12.     int64_t content_length = 0;
  14.     aos_pool_create(&p, NULL);
  16.     /* Create and initialize options */
  17.     options = oss_request_options_create(p);
  18.     init_options(options);
  20.     /* Initialize parameters */
  21.     aos_str_set(&bucket, "<Name of your bucket>");
  22.     aos_str_set(&object, "<Name of your object>");
  23.     headers = aos_table_make(p, 0);
  25.     /* Get the object metadata */
  26.     s = oss_head_object(options, &bucket, &object, headers, &resp_headers);
  28.     if (aos_status_is_ok(s)) {
  29.         /* Get the object length */
  30.         content_length_str = (char*)apr_table_get(resp_headers, OSS_CONTENT_LENGTH);
  31.         if (content_length_str != NULL) {
  32.             content_length = atoll(content_length_str);
  33.         }
  35.         /* Get the object type */
  36.         object_type = (char*)apr_table_get(resp_headers, OSS_OBJECT_TYPE);
  38.         printf("head object succeeded, object type:%s, content_length:%ld\n", 
  39.                object_type, content_length);
  40.     } else {
  41.         printf("head object failed\n");
  42.     }
  44.     aos_pool_destroy(p);
  45. }

Notice:

  • The oss_head_object interface does not download the object content, but only read the object metadata, including the system-level and user-defined metadata.
  • Complete code can be found at GitHub.

Copy an object

You can copy objects that you have permissions on within the same region. The following code copies an object using the oss_copy_object interface:

  1. aos_pool_t *p;
  2. oss_request_options_t *options;
  3. aos_status_t *s;
  4. aos_table_t * headers;
  5. aos_table_t *resp_headers;
  6. char *source_bucket_name = "<Name of your source bucket>";
  7. char *source_object_name = "<Name of your source object>";
  8. char *dest_bucket_name = "<Name of your target bucket>";
  9. char *source_object_name = "<Name of your target object>";
  10. aos_string_t source_bucket;
  11. aos_string_t source_object;
  12. aos_string_t dest_bucket;
  13. aos_string_t dest_object;
  15. aos_pool_create(&p, NULL);
  17. options = oss_request_options_create(p);
  18. init_options(options);
  20. aos_str_set(&source_bucket, source_bucket_name);
  21. aos_str_set(&source_object, source_object_name);
  22. aos_str_set(&dest_bucket, dest_bucket_name);
  23. aos_str_set(&dest_object, dest_object_name);
  24. headers = aos_table_make(p, 0);
  26. /* Copy the object */
  27. s = oss_copy_object(options, &source_bucket, &source_object, &dest_bucket, &dest_object, headers, &resp_headers);
  28. if (aos_status_is_ok(s)) {
  29.     printf("copy object succeeded\n");
  30. } else {
  31.     printf("copy object failed\n");
  32. }
  34. aos_pool_destroy(p);

Notice:

  • The source bucket and the target bucket must belong to the same region.
  • When copying an object larger than 1 GB, we suggest the multipart copying mode.

Multipart object copying

When copying an object larger than 500 MB, we suggest using the oss_upload_part_copy interface. The following code copies an object in the multipart copying mode:

  1. aos_pool_t *p;
  2. oss_request_options_t *options;
  3. char *source_bucket_name = "<Name of your source bucket>";
  4. char *source_object_name = "<Name of your source object>";
  5. char *dest_bucket_name = "<Name of your target bucket>";
  6. char *source_object_name = "<Name of your target object>";
  7. aos_string_t dest_bucket;
  8. aos_string_t dest_object;
  9. aos_string_t upload_id;
  10. aos_table_t *init_headers;
  11. aos_table_t *copy_headers;
  12. aos_table_t *list_part_resp_headers;
  13. aos_table_t *complete_resp_headers
  14. aos_table_t *resp_headers;
  15. aos_status_t *s;
  16. oss_list_upload_part_params_t *list_upload_part_params;
  17. oss_upload_part_copy_params_t *upload_part_copy_params1;
  18. aos_list_t complete_part_list;
  19. oss_list_part_content_t *part_content;
  20. oss_complete_part_content_t *complete_content;
  21. int part1 = 1;
  22. int64_t range_start1 = 0;
  23. int64_t range_end1 = 6000000;//not less than 5 MB
  24. int max_ret = 1000;
  26. aos_pool_create(&p, NULL);
  28. options = oss_request_options_create(p);
  29. init_options(options);
  31. aos_str_set(&dest_bucket, dest_bucket_name);
  32. aos_str_set(&dest_object, dest_object_name);
  33. init_headers = aos_table_make(p, 0);
  34. s = oss_init_multipart_upload(options, &dest_bucket, &dest_object, init_headers, &upload_id, &resp_headers);
  36. /* Copy the first data part  */
  37. upload_part_copy_params1 = oss_create_upload_part_copy_params(p);
  38. aos_str_set(&upload_part_copy_params1->source_bucket, source_bucket_name);
  39. aos_str_set(&upload_part_copy_params1->source_object, source_object_name);
  40. aos_str_set(&upload_part_copy_params1->dest_bucket, dest_bucket_name);
  41. aos_str_set(&upload_part_copy_params1->dest_object, dest_object_name);
  42. aos_str_set(&upload_part_copy_params1->upload_id, upload_id->data);
  43. upload_part_copy_params1->part_num = part1;
  44. upload_part_copy_params1->range_start = range_start1;
  45. upload_part_copy_params1->range_end = range_end1;
  46. copy_headers = aos_table_make(p, 0);
  47. s = oss_upload_part_copy(options, upload_part_copy_params1, copy_headers, &resp_headers);
  48. if (aos_status_is_ok(s)) {
  49.     printf("upload part copy succeeded\n");
  50. } else {
  51.     printf("upload part copy failed\n");
  52. }
  54. /* Continue copying the rest parts. Skipped*/
  55. ...
  57. /* List the parts */
  58. list_upload_part_params = oss_create_list_upload_part_params(p);
  59. list_upload_part_params->max_ret = max_ret;
  60. aos_list_init(&complete_part_list);
  61. s = oss_list_upload_part(options, &dest_bucket, &dest_object, &upload_id,
  62. list_upload_part_params, &list_part_resp_headers);
  63. aos_list_for_each_entry(part_content, &list_upload_part_params->part_list, node) {
  64.    complete_content = oss_create_complete_part_content(p);
  65.    aos_str_set(&complete_content->part_number, part_content->part_number.data);
  66.    aos_str_set(&complete_content->etag, part_content->etag.data);
  67.    aos_list_add_tail(&complete_content->node, &complete_part_list);
  68. }
  70. /* Complete the multipart copying */
  71. s = oss_complete_multipart_upload(options, &dest_bucket, &dest_object, &upload_id, &complete_part_list, &complete_resp_headers);
  72. if (aos_status_is_ok(s)) {
  73.     printf("complete multipart upload succeeded\n");
  74. } else {
  75.     printf("complete multipart upload failed\n");
  76. }
  78. aos_pool_destroy(p);

Delete an object

You can delete an object using the oss_delete_object interface:

  1. void delete_object()
  2. {
  3.     aos_pool_t *p = NULL;
  4.     aos_string_t bucket;
  5.     aos_string_t object;
  6.     oss_request_options_t *options = NULL;
  7.     aos_table_t *resp_headers = NULL;
  8.     aos_status_t *s = NULL;
  10.     aos_pool_create(&p, NULL);
  12.     /* Create and initialize options */
  13.     options = oss_request_options_create(p);
  14.     init_options(options);
  15.     aos_str_set(&bucket, "<Name of your bucket>");
  16.     aos_str_set(&object, "<Name of your object>");
  18.     /* Delete an object */
  19.     s = oss_delete_object(options, &bucket, &object, &resp_headers);
  21.     /* Determine whether the deletion was successful */
  22.     if (aos_status_is_ok(s)) {
  23.         printf("delete object succeed\n");
  24.     } else {
  25.         printf("delete object failed\n");
  26.     }
  28.     /* Release the resources*/
  29.     aos_pool_destroy(p);
  30. }

Note: Complete code can be found at GitHub.

Delete objects in batches

You can delete objects in batches using the oss_delete_objects interface. You can use the is_quiet parameter to determine whether to return the deletion results: 

  1. aos_pool_t *p;
  2. aos_status_t *s;
  3. aos_table_t *resp_headers;
  4. oss_request_options_t *options;
  5. char *bucket_name = "<Name of your bucket>";
  6. char *object_name1 = "<Name 1 of your object>";
  7. char *object_name2 = "<Name 2 of your object>";
  8. aos_string_t bucket;
  9. aos_string_t object1;
  10. aos_string_t object2;
  11. oss_object_key_t *content1;
  12. oss_object_key_t *content2;
  13. aos_list_t object_list;
  14. aos_list_t deleted_object_list;
  15. int is_quiet = 1;
  17. options = oss_request_options_create(p);
  18. init_options(options);
  20. aos_str_set(&bucket, bucket_name);
  21. aos_str_set(&object1, object_name1);
  22. aos_str_set(&object2, object_name2);
  24. /* Construct the list of objects to be deleted */
  25. aos_list_init(&object_list);
  26. aos_list_init(&deleted_object_list);
  27. content1 = oss_create_oss_object_key(p);
  28. aos_str_set(&content1->key, object_name1);
  29. aos_list_add_tail(&content1->node, &object_list);
  30. content2 = oss_create_oss_object_key(p);
  31. aos_str_set(&content2->key, object_name2);
  32. aos_list_add_tail(&content2->node, &object_list);
  34. /* Delete multiple objects */
  35. s = oss_delete_objects(options, &bucket, &object_list, is_quiet, &resp_headers, &deleted_object_list);
  36. if (aos_status_is_ok(s)) {
  37.     printf("delete objects succeeded\n");
  38. } else {
  39.     printf("delete objects failed\n");
  40. }
  42. aos_pool_destroy(p);

Delete objects with a specified prefix in batches

You can delete objects with a specified prefix in batches using the oss_delete_objects_by_prefix interface: 

  1. aos_pool_t *p;
  2. oss_request_options_t *options;
  3. aos_status_t *s;
  4. aos_table_t *resp_headers;
  5. char *bucket_name = "<Name of your bucket>";
  6. char *prefix_str = "<The prefix of the objects to be deleted>";
  7. aos_string_t bucket;
  8. aos_string_t prefix;
  10. aos_pool_create(&p, NULL);
  12. options = oss_request_options_create(p);
  13. init_options(options);
  15. aos_str_set(&bucket, bucket_name);
  16. aos_str_set(&prefix, prefix_str);
  18. /* Delete objects with the specified prefix*/
  19. s = oss_delete_objects_by_prefix(options, &bucket, &prefix);
  20. if (aos_status_is_ok(s)) {
  21.     printf("delete objects by prefix succeeded\n");
  22. } else {
  23.     printf("delete objects by prefix failed\n");
  24. }
  26. aos_pool_destroy(p);

Notice:

  • You can delete a directory through this batch deletion of objects with a specified prefix. For example, to delete the dir directory, you can set the prefix to dir/.
  • If the prefix is a null string (“”) or NULL, the whole bucket is deleted. Therefore, exercise caution when using this function.
Thank you! We've received your feedback.
Free Trial Free Trial