edit-icon download-icon

Manage objects

Last Updated: Oct 26, 2017

In OSS, you can manage the objects in a bucket using a series of interfaces, such as ListObjects, DeleteObject, CopyObject, and DoesObjectExist.

List objects in a bucket

List objects in a simple mode

  1. using Aliyun.OSS;
  2. // Initialize an OSSClient
  3. var client = new OssClient(endpoint, accessKeyId, accessKeySecret);
  4. /// <summary>
  5. /// List summary of objects in the specified bucket (OssObjectSummary)
  6. /// </summary>
  7. /// <param name="bucketName">Name of the bucket</param>
  8. public void ListObjects(string bucketName)
  9. {
  10. try
  11. {
  12. var listObjectsRequest = new ListObjectsRequest(bucketName);
  13. var result = client.ListObjects(listObjectsRequest);
  14. Console.WriteLine("List objects succeeded");
  15. foreach (var summary in result.ObjectSummaries)
  16. {
  17. Console.WriteLine("File name:{0}", summary.Key);
  18. }
  19. }
  20. catch (Exception ex)
  21. {
  22. Console.WriteLine("List objects failed. {0}", ex.Message);
  23. }
  24. }

Note:

  • For complete code, see GitHub.

  • By default, if a bucket contains more than 100 objects, only the first 100 objects are returned and the IsTruncated parameter in the returned results is to be 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 MaxKeys parameter or use the Marker parameter for multiple reads.

Names of the List objects containing a specified prefix

  1. using Aliyun.OSS;
  2. // Initialize an OSSClient
  3. var client = new OssClient(endpoint, accessKeyId, accessKeySecret);
  4. /// <summary>
  5. /// List summary of objects whose keys match the prefix parameter in a specified bucket (OssObjectSummary)
  6. /// </summary>
  7. /// <param name="bucketName">Name of the bucket</param>
  8. /// <param name="prefix">Limit that the prefix must be contained in the names of objects to be returned</param>
  9. public void ListObjects(string bucketName, string prefix)
  10. {
  11. try
  12. {
  13. var listObjectsRequest = new ListObjectsRequest(bucketName)
  14. {
  15. Prefix = prefix
  16. };
  17. var result = client.ListObjects(listObjectsRequest);
  18. Console.WriteLine("List objects succeeded");
  19. foreach (var summary in result.ObjectSummaries)
  20. {
  21. Console.WriteLine("File Name:{0}", summary.Key);
  22. }
  23. }
  24. catch (Exception ex)
  25. {
  26. Console.WriteLine("List objects failed. {0}", ex.Message);
  27. }
  28. }

List objects in an asynchronous mode

  1. using Aliyun.OSS;
  2. // Initialize an OSSClient
  3. static OssClient ossClient = new OssClient(endpoint, accessKeyId, accessKeySecret);
  4. static AutoResetEvent _event = new AutoResetEvent(false);
  5. public static void AsyncListObjects()
  6. {
  7. try
  8. {
  9. var listObjectsRequest = new ListObjectsRequest(bucketName);
  10. ossClient.BeginListObjects(listObjectsRequest, ListObjectCallback, null);
  11. _event.WaitOne();
  12. }
  13. catch (Exception ex)
  14. {
  15. Console.WriteLine("List objects failed. {0}", ex.Message);
  16. }
  17. }
  18. private static void ListObjectCallback(IAsyncResult ar)
  19. {
  20. try
  21. {
  22. var result = ossClient.EndListObjects(ar);
  23. foreach (var summary in result.ObjectSummaries)
  24. {
  25. Console.WriteLine ("Object name: 0", summary.Key);
  26. }
  27. _event.Set();
  28. Console.WriteLine("List objects succeeded");
  29. }
  30. catch (Exception ex)
  31. {
  32. Console.WriteLine("List objects failed. {0}", ex.Message);
  33. }
  34. }

Note:

  • For complete code, see GitHub.

  • The ListObjectCallback method is implemented after an asynchronous call. Similar interfaces must be used when an asynchronous interface is called to list objects.

List objects through ListObjectsRequest

You can set parameters of ListObjectsRequest to achieve advanced features. For example,

  1. using Aliyun.OSS;
  2. // Initialize an OSSClient
  3. var client = new OssClient(endpoint, accessKeyId, accessKeySecret);
  4. /// <summary>
  5. /// List summary of objects in the specified bucket (OssObjectSummary)
  6. /// </summary>
  7. /// <param name="bucketName">Name of the bucket</param>
  8. public void ListObjects(string bucketName)
  9. {
  10. try
  11. {
  12. var listObjectsRequest = new ListObjectsRequest(bucketName)
  13. {
  14. Delimiter = "/",
  15. Marker = "abc"
  16. };
  17. result = client.ListObjects(listObjectsRequest);
  18. Console.WriteLine("List objects succeeded");
  19. foreach (var summary in result.ObjectSummaries)
  20. {
  21. Console.WriteLine ("Object name: 0", summary.Key);
  22. }
  23. }
  24. catch (Exception ex)
  25. {
  26. Console.WriteLine("List objects failed. {0}", ex.Message);
  27. }
  28. }

Note: The following table lists the configurable parameters and their functions:

Name Function
Delimiter A character used to group object names. All objects whose names contain the specified prefix and occur before the delimiter for the first time form a group of elements called CommonPrefixes.
Marker Set the returned results to begin from the first entry after the marker in alphabetical order.
MaxKeys Limits the maximum number of objects returned for one request. If this parameter is not set, the default value 100 is to be used. The maximum value cannot exceed 1,000.
Prefix Specifies the prefix that the names of returned objects must contain. Note that the object names returned for a query using the prefix parameter still contain the specified prefix.

Note:

  • For complete code, see GitHub.

  • Multiple iterations must be performed to traverse a whole batch of more than 100 objects. During each iteration, the key of the final object for the previous iteration can be used as the marker in the current iteration.

Simulate folder feature

The Delimiter and Prefix parameters can be used together to simulate the folder feature. Combinations of Delimiter and Prefix serve the following purposes:

  • Setting Prefix as the name of a folder enumerates the objects starting with this prefix, recursively returning all objects and subfolders in this folder.

  • When the slash (/) is used as the delimiter, the returned values enumerates only the objects in the folder and the subfolders to be returned in CommonPrefixes.

  • Recursive objects and folders in the subfolders not be displayed.

  • If the bucket contains four objects: oss.jpg, fun/test.jpg, fun/movie/001.avi, and fun/movie/007.avi. We use the “/“ symbol as the separator for folders.

List all objects in a bucket

The following code retrieves all objects from a bucket:

  1. using Aliyun.OSS;
  2. // Initialize an OSSClient
  3. var client = new OssClient(endpoint, accessKeyId, accessKeySecret);
  4. public void ListObject(string bucketName)
  5. {
  6. try
  7. {
  8. ObjectListing result = null;
  9. string nextMarker = string.Empty;
  10. do
  11. {
  12. var listObjectsRequest = new ListObjectsRequest(bucketName)
  13. {
  14. Marker = nextMarker,
  15. MaxKeys = 100
  16. };
  17. result = client.ListObjects(listObjectsRequest);
  18. Console.WriteLine("File:");
  19. foreach (var summary in result.ObjectSummaries)
  20. {
  21. Console.WriteLine("Name:{0}", summary.Key);
  22. }
  23. nextMarker = result.NextMarker;
  24. } while (result.IsTruncated);
  25. }
  26. catch (Exception ex)
  27. {
  28. Console.WriteLine("List object failed. {0}", ex.Message);
  29. }
  30. }

Output:

  1. File:
  2. Name:fun/movie/001.avi
  3. Name:fun/movie/007.avi
  4. Name:fun/test.jpg
  5. Name:oss.jpg

Recursively list all objects in a directory

We can set the Prefix parameter to retrieve all the objects under a directory:

  1. using Aliyun.OSS;
  2. // Initialize an OSSClient
  3. var client = new OssClient(endpoint, accessKeyId, accessKeySecret);
  4. public void ListObject(string bucketName)
  5. {
  6. try
  7. {
  8. var listObjectsRequest = new ListObjectsRequest(bucketName)
  9. {
  10. Prefix = "fun/"
  11. };
  12. result = client.ListObjects(listObjectsRequest);
  13. Console.WriteLine("List object succeeded");
  14. Console.WriteLine("File:");
  15. foreach (var summary in result.ObjectSummaries)
  16. {
  17. Console.WriteLine("Name:{0}", summary.Key);
  18. }
  19. Console.WriteLine("Dir:");
  20. foreach (var prefix in result.CommonPrefixes)
  21. {
  22. Console.WriteLine("Name:{0}", prefix);
  23. }
  24. }
  25. catch (Exception ex)
  26. {
  27. Console.WriteLine("List object failed. {0}", ex.Message);
  28. }
  29. }

Output:

  1. List object succeeded
  2. File:
  3. Name:fun/movie/001.avi
  4. Name:fun/movie/007.avi
  5. Name:fun/test.jpg
  6. Directory:

List objects and subdirectories in a directory

By using both Prefix and Delimiter, we can list the objects and subdirectories under a directory:

  1. using Aliyun.OSS;
  2. // Initialize an OSSClient
  3. var client = new OssClient(endpoint, accessKeyId, accessKeySecret);
  4. public void ListObjects(string bucketName)
  5. {
  6. try
  7. {
  8. var listObjectsRequest = new ListObjectsRequest(bucketName)
  9. {
  10. Prefix = "fun/",
  11. Delimiter = "/"
  12. };
  13. result = client.ListObjects(listObjectsRequest);
  14. Console.WriteLine("List object succeeded");
  15. Console.WriteLine("File:");
  16. foreach (var summary in result.ObjectSummaries)
  17. {
  18. Console.WriteLine("Name:{0}", summary.Key);
  19. }
  20. Console.WriteLine("Dir:");
  21. foreach (var prefix in result.CommonPrefixes)
  22. {
  23. Console.WriteLine("Name:{0}", prefix);
  24. }
  25. }
  26. catch (Exception ex)
  27. {
  28. Console.WriteLine("List object failed. {0}", ex.Message);
  29. }
  30. }

Output:

  1. List object success
  2. File:
  3. Name:fun/test.jpg
  4. Dir:
  5. Name:fun/movie/

Note:

  • In the returned results, the ObjectSummaries list contains the objects in the “fun” directory.

  • The CommonPrefixs list contains all subfolders in the “fun” directory. The “fun/movie/001.avi” and “fun/movie/007.avi” objects are not listed. This is because, they are in the “movie” directory under the “fun” folder.

Delete objects

Delete an object:

  1. using Aliyun.OSS;
  2. // Initialize an OSSClient
  3. var client = new OssClient(endpoint, accessKeyId, accessKeySecret);
  4. /// <summary>
  5. /// List a specific object in the specified bucket
  6. /// </summary>
  7. /// <param name="bucketName">Name of the bucket</param>
  8. /// <param name="key">Name of the object</param>
  9. public void DeleteObject(string bucketName, string key)
  10. {
  11. try
  12. {
  13. client.DeleteObject(bucketName, key);
  14. Console.WriteLine("Delete object succeeded");
  15. }
  16. catch (Exception ex)
  17. {
  18. Console.WriteLine("Delete object failed. {0}", ex.Message);
  19. }
  20. }

Note: For complete code, see GitHub.

Delete multiple objects:

  1. using Aliyun.OSS;
  2. // Initialize an OSSClient
  3. var client = new OssClient(endpoint, accessKeyId, accessKeySecret);
  4. /// <summary>
  5. /// Delete all objects in the specified bucket
  6. /// </summary>
  7. /// <param name="bucketName">Name of the bucket</param>
  8. public void DeleteObjects(string bucketName)
  9. {
  10. try
  11. {
  12. var keys = new List<string>();
  13. var listResult = client.ListObjects(bucketName);
  14. foreach (var summary in listResult.ObjectSummaries)
  15. {
  16. keys.Add(summary.Key);
  17. }
  18. var request = new DeleteObjectsRequest(bucketName, keys, false);
  19. client.DeleteObjects(request);
  20. Console.WriteLine("Delete objects succeeded");
  21. }
  22. catch (Exception ex)
  23. {
  24. Console.WriteLine("Delete objects failed. {0}", ex.Message);
  25. }
  26. }

Note: For complete code, see GitHub.

Copy objects

You can copy objects with the proper permission in the same region (Hangzhou, Shenzhen, or Qingdao).

Copy an object

The following code copies an object using the CopyObject method:

  1. using Aliyun.OSS;
  2. // Initialize an OSSClient
  3. var client = new OssClient(endpoint, accessKeyId, accessKeySecret);
  4. /// <summary>
  5. /// Copy the object
  6. /// </summary>
  7. /// <param name="sourceBucket">Name of the bucket containing the source object</param>
  8. /// <param name="sourceKey">Name of the source object</param>
  9. /// <param name="targetBucket">Name of the bucket where the target object is stored</param>
  10. /// <param name="targetKey">Name of the target object</param>
  11. public void CopyObect(string sourceBucket, string sourceKey, string targetBucket, string targetKey)
  12. {
  13. try
  14. {
  15. var metadata = new ObjectMetadata();
  16. metadata.AddHeader(Util.HttpHeaders.ContentType, "text/html");
  17. var req = new CopyObjectRequest(sourceBucket, sourceKey, targetBucket, targetKey)
  18. {
  19. NewObjectMetadata = metadata
  20. };
  21. var ret = client.CopyObject(req);
  22. Console.WriteLine("Copy object succeeded");
  23. Console.WriteLine ("The object's ETag: 0", ret.ETag);
  24. }
  25. catch (Exception ex)
  26. {
  27. Console.WriteLine("Copy object failed. {0}", ex.Message);
  28. }
  29. }

Note:

  • For complete code, see GitHub.
  • The object copied using the CopyObject method must be smaller than 1 GB; otherwise, an error is reported. If the object is larger than 1 GB, use the UploadPartCopy method described is as follows:

Copy a large object

Initialize Multipart Upload

The following code uses the InitiateMultipartUpload method to initialize a multipart upload task:

  1. using Aliyun.OSS;
  2. // Initialize an OSSClient
  3. var client = new OssClient(endpoint, accessKeyId, accessKeySecret);
  4. public void InitiateMultipartUpload(string bucketName, string key)
  5. {
  6. try
  7. {
  8. // Start Multipart Upload
  9. var request = new InitiateMultipartUploadRequest(bucketName, key);
  10. var result = client.InitiateMultipartUpload(request);
  11. // Print UploadId
  12. Console.WriteLine("Init multipart upload succeeded");
  13. Console.WriteLine("Upload Id:{0}", result.UploadId);
  14. }
  15. catch (Exception ex)
  16. {
  17. Console.WriteLine("Init multipart upload failed. {0}", ex.Message);
  18. }
  19. }

Note: For complete code, see GitHub.

Copy an object through UploadPartCopy

The UploadPartCopy method can be used to upload a new object by copying the data of an existing object. We recommend this method for copying an object larger than 500 MB.

  1. using Aliyun.OSS;
  2. // Initialize an OSSClient
  3. var client = new OssClient(endpoint, accessKeyId, accessKeySecret);
  4. public void UploadPartCopy(string sourceBucket, string sourceKey, string targetBucket, string targetKey, string uploadId)
  5. {
  6. try
  7. {
  8. // Calculate the total number of parts
  9. var metadata = client.GetObjectMetadata(sourceBucket, sourceKey);
  10. var fileSize = metadata.ContentLength;
  11. var partCount = (int)fileSize / partSize;
  12. if (fileSize % partSize != 0)
  13. {
  14. partCount++;
  15. }
  16. // Start to copy parts
  17. var partETags = new List<PartETag>();
  18. for (var i = 0; i < partCount; i++)
  19. {
  20. var skipBytes = (long)partSize * i;
  21. var size = (partSize < fileSize - skipBytes) ? partSize : (fileSize - skipBytes);
  22. var request = new UploadPartCopyRequest(targetBucket, targetKey, sourceBucket, sourceKey, uploadId)
  23. {
  24. PartSize = size,
  25. PartNumber = i + 1,
  26. BeginIndex = skipBytes
  27. };
  28. var result = client.UploadPartCopy(request);
  29. partETags.Add(result.PartETag);
  30. }
  31. Console.WriteLine("Upload part copy succeeded");
  32. }
  33. catch (Exception ex)
  34. {
  35. Console.WriteLine("Upload part copy failed. {0}", ex.Message);
  36. }

Note:

  • For complete code, see GitHub.

  • The preceding code calls the UploadPartCopy method to copy each part.

  • The UploadPartCopy usage requirements are basically the same as those for UploadPart. You must use BeginIndex to locate the start point of the part to be uploaded and use SourceKey to specify the object to be copied.

Complete multipart upload

The following code completes a multipart upload task:

  1. using Aliyun.OSS;
  2. // Initialize an OSSClient
  3. var client = new OssClient(endpoint, accessKeyId, accessKeySecret);
  4. public void CompleteMultipartUpload(string bucketName, string key, string uploadId)
  5. {
  6. try
  7. {
  8. var completeMultipartUploadRequest = new CompleteMultipartUploadRequest(bucketName, key, uploadId);
  9. foreach (var partETag in partETags)
  10. {
  11. completeMultipartUploadRequest.PartETags.Add(partETag);
  12. }
  13. var result = client.CompleteMultipartUpload(completeMultipartUploadRequest);
  14. Console.WriteLine("Complete multipart upload succeeded");
  15. }
  16. catch (Exception ex)
  17. {
  18. Console.WriteLine("Complete multipart upload failed. {0}", ex.Message);
  19. }
  20. }

For complete code, see GitHub.

Note:

  • In the preceding code, the PartETags are saved to the PartETags list during multipart upload. Once the OSS receives the PartETags list submitted by the user, it checks the validity of each data part.

  • Once all data parts are verified, the OSS combines these parts into a complete object.

Resumable copy

In addition to multipart copy, OSS provides the resumable copy feature for you to resume an interrupted copy task starting from the failed part. This speeds up the copy process.

  1. using Aliyun.OSS;
  2. // Initialize an OSSClient
  3. var client = new OssClient(endpoint, accessKeyId, accessKeySecret);
  4. public static void ResumableCopyObject(string sourceBucketName, string sourceKey,
  5. string destBucketName, string destKey)
  6. {
  7. string checkpointDir = @"<your checkpoint dir>";
  8. try
  9. {
  10. var request = new CopyObjectRequest(sourceBucketName, sourceKey, destBucketName, destKey);
  11. client.ResumableCopyObject(request, checkpointDir);
  12. Console.WriteLine("Resumable copy new object:{0} succeeded", request.DestinationKey);
  13. }
  14. catch (Exception ex)
  15. {
  16. Console.WriteLine("Resumable copy new object failed, {0}", ex.Message);
  17. }
  18. }

Note:

  • For complete code, see GitHub.

  • The checkpointDir directory stores records on the intermediate state of resumable copy. The records are used when a failed copy task is resumed.

  • If the checkpointDir directory is null, resumable copy does not take effect, and the object that previously failed to be copied, gets copied again.

Modify object metadata

The metadata of an existing object can be modified through ModifyObjectMeta.

  1. using Aliyun.OSS;
  2. // Initialize an OSSClient
  3. var client = new OssClient(endpoint, accessKeyId, accessKeySecret);
  4. /// <summary>
  5. /// Modify the metadata of the object
  6. /// </summary>
  7. /// <param name="bucketName">Name of the bucket where the object is stored</param>
  8. /// <param name="key">Name of the object</param>
  9. public void ModifyObjectMeta(string bucketName, string key)
  10. {
  11. try
  12. {
  13. var meta = new ObjectMetadata();
  14. meta.ContentType = "application/octet-stream";
  15. client.ModifyObjectMeta(bucketName, key, meta);
  16. Console.WriteLine("Modify object meta succeeded");
  17. }
  18. catch (Exception ex)
  19. {
  20. Console.WriteLine("Modify object meta failed. {0}", ex.Message);
  21. }
  22. }

Note: For complete code, see GitHub

Set object ACL

For more information on object ACL, see Access Control. You can set the object ACL through ‘SetBucketAcl’.

  1. using Aliyun.OSS;
  2. // Initialize an OSSClient
  3. var client = new OssClient(endpoint, accessKeyId, accessKeySecret);
  4. /// <summary>
  5. /// Set the object ACL
  6. /// </summary>
  7. /// <param name="bucketName">Name of the bucket where the object is stored</param>
  8. /// <param name="key">Name of the object</param>
  9. public void SetObjectAclSample(string bucketName, string key)
  10. {
  11. try
  12. {
  13. client.SetObjectAcl(bucketName, key, CannedAccessControlList.PublicRead);
  14. Console.WriteLine("Set Object:{0} Acl succeeded ", key);
  15. }
  16. catch (Exception ex)
  17. {
  18. Console.WriteLine("Failed with error info: {0}", ex.Message);
  19. }
  20. }

Note:

  • Four access permissions to objects: private, public-read, public-read-write, default. They correspond to CannedAccessControlList.Private, CannedAccessControlList.PublicRead, CannedAccessControlList.PublicReadWrite and CannedAccessControlList.Default respectively.

  • For complete code, see GitHub.

Get object ACL

You can get the object ACL through ‘GetBucketAcl’.

  1. using Aliyun.OSS;
  2. // Initialize an OSSClient
  3. var client = new OssClient(endpoint, accessKeyId, accessKeySecret);
  4. /// <summary>
  5. /// Get the object ACL
  6. /// </summary>
  7. /// <param name="bucketName">Name of the bucket where the object is stored</param>
  8. /// <param name="key">Name of the object</param>
  9. public void SetObjectAclSample(string bucketName, string key)
  10. {
  11. try
  12. {
  13. var result = client.GetObjectAcl(bucketName, key);
  14. Console.WriteLine("Get Object Acl succeeded,Id:{0} Acl:{1} succeeded",
  15. result.Owner.Id, result.ACL.ToString());
  16. }
  17. catch (Exception ex)
  18. {
  19. Console.WriteLine("Failed with error info: {0}", ex.Message);
  20. }
  21. }

Note: For complete code, see GitHub.

Thank you! We've received your feedback.