Object Storage Service:Run the ls command to list buckets, objects, and parts within an account

Usage notes

• To list buckets, you must have the oss:ListBuckets permission. To list objects, you must have the oss:ListObjects permission. To list all versions of objects, you must have the oss:ListObjectVersions permission. To list all parts, you must have the oss:ListParts and oss:ListMultipartUploads permissions. For more information, see Attach a custom policy to a RAM user.

• For ossutil 1.6.16 and later, you can directly use ossutil as the binary name in the command line. You do not need to update the binary name based on the operating system. For ossutil earlier than 1.6.16, you need to update the binary name based on the operating system. For more information, see ossutil command reference.

List buckets

• Command syntax

  ossutil ls [-s] [--limited-num] [--marker] 

  The following table describes the parameters in the syntax.

  Parameter	Description
  -s	Specifies that only bucket names are listed.
  --limited-num	The maximum number of results that you want to return. You can specify this parameter together with the marker parameter to display the returned results by page.
  --marker	The position from which the list operation starts. Buckets whose names are alphabetically after the marker are listed.

• Examples

  • List all buckets of the current Alibaba Cloud account:

    ossutil ls

    You can also run the following command to list all buckets of the current Alibaba Cloud account:

    ossutil ls oss://

    The following output indicates that all buckets of the current Alibaba Cloud account are listed. The listed information includes the bucket names, creation times, regions, storage classes, and number of buckets.

    2016-10-21 16:18:37 +0800 CST       oss-cn-hangzhou         Archive    oss://examplebucketA
    2016-12-01 15:06:21 +0800 CST       oss-cn-hangzhou        Standard    oss://examplebucketB
    2016-07-20 10:36:24 +0800 CST       oss-cn-hangzhou              IA    oss://examplebucketC
    2016-10-21 17:31:27 +0800 CST       oss-cn-hangzhou         Archive    oss://examplebucketD
    Bucket Number is:4
    0.252174(s) elapsed  

  • List all buckets of the current Alibaba Cloud account in simple mode:

    ossutil ls -s

    The following output indicates that all buckets of the current Alibaba Cloud account are listed. The listed information includes only the bucket names and number of buckets.

    oss://examplebucketA
    oss://examplebucketB
    oss://examplebucketC
    oss://examplebucketD
    Bucket Number is:4
    0.235104(s) elapsed  

  • List buckets whose names are alphabetically after the examplebucketA marker:

    ossutil ls oss:// --limited-num=2 -s --marker examplebucketA

    The following output indicates that two buckets whose names are alphabetically after examplebucketA are listed.

    2016-12-01 15:06:21 +0800 CST       oss-cn-hangzhou        Standard    oss://examplebucketB
    2016-07-20 10:36:24 +0800 CST       oss-cn-hangzhou              IA    oss://examplebucketC
    Bucket Number is:2
    0.132174(s) elapsed                        

List objects

• Command syntax

  ossutil ls oss://bucketname[/prefix] [-s] [-d] [--limited-num] [--marker] [--include] [--exclude]  [--version-id-marker] [--all-versions]

  The following table describes the parameters in the syntax.

  Parameter	Description
  bucketname	The name of the bucket.
  prefix	The prefix of the names of the objects that you want to list. Specify this parameter when you want to list objects whose names contain the specified prefix.
  -s	Specifies that only object names are listed.
  -d	Specifies that only objects and subdirectories in the root directory of the bucket are listed. Objects in subdirectories are not listed.
  --limited-num	The maximum number of results that you want to return. You can specify this parameter together with the marker parameter to display the returned results by page.
  --marker	The position from which the list operation starts. Objects whose names are alphabetically after the marker are listed.
  --include	Includes all objects that meet the specified conditions. For more information, see --include and --exclude.
  --exclude	Excludes all objects that meet the specified conditions. For more information, see --include and --exclude.
  --version-id-marker	Specifies the object version from which you want to start the list operation. You can specify this parameter only after versioning is enabled for the bucket.
  --all-versions	Specifies that all versions of objects in the bucket are listed. You can specify this parameter only after versioning is enabled for the bucket.

• Examples

  • List all objects in a bucket named examplebucket:

    ossutil ls oss://examplebucket

    The following output indicates that all objects in the examplebucket bucket are listed. The listed information includes the last modified time, sizes, ETag values, and names of the objects.

    The ETag value of an object is used to identify the content of an object. If an object is created by calling the PutObject operation, the ETag of the object is the MD5 hash of the object content. If an object is created by using other methods, the ETag of the object is not the MD5 hash of the object content but a unique value calculated based on the built-in rules.

    LastModifiedTime                    Size(B)  StorageClass   ETag                                    ObjectName
    2020-12-01 15:06:37 +0800 CST           114      Standard   61DE142E5AFF9A6748707D4A77BFBCFB        oss://examplebucket/example.txt
    2020-12-01 15:06:42 +0800 CST        363812      Standard   E7581E5D2EBC56ECCB6FB6050B4C6545        oss://examplebucket/examplefolder/photo.jpg
    2020-12-01 15:06:45 +0800 CST      57374182      Standard   BE97B7AD7A2C1277B11221E5C9537544        oss://examplebucket/video.mp4
    Object Number is:3
    0.007379(s) elapsed                 

  • List objects whose names contain the example prefix in a bucket named examplebucket:

    ossutil ls oss://examplebucket/example

    The following output indicates that all objects whose names contain the example prefix in the examplebucket bucket are listed.

    LastModifiedTime                    Size(B)  StorageClass   ETag                                     ObjectName
    2020-12-01 15:06:37 +0800 CST           114      Standard   61DE142E5AFF9A6748707D4A77BFBCFB        oss://examplebucket/example.txt
    2020-12-01 15:06:42 +0800 CST        363812      Standard   E7581E5D2EBC56ECCB6FB6050B4C6545        oss://examplebucket/examplefolder/photo.jpg
    Object Number is:2
    0.007379(s) elapsed                 

  • List objects whose names contain the .mp4 extension in a bucket named examplebucket:

    ossutil ls oss://examplebucket --include *.mp4

    The following output indicates that objects whose names contain the .mp4 extension in the examplebucket bucket are listed.

    LastModifiedTime                    Size(B)  StorageClass   ETag                                     ObjectName
    2020-12-01 15:06:45 +0800 CST      57374182      Standard   BE97B7AD7A2C1277B11221E5C9537544        oss://examplebucket/video.mp4
    Object Number is:1
    0.007379(s) elapsed                 

  • List only objects and subdirectories in the root directory of a bucket named examplebucket:

    ossutil ls oss://examplebucket -d

    The following output indicates that objects and subdirectories in the root directory of the examplebucket bucket are listed.

    oss://examplebucket/example.txt
    oss://examplebucket/examplefolder/
    oss://examplebucket/video.mp4
    Object and Directory Number is: 3
    
    0.278489(s) elapsed

  • List all versions of all objects in a bucket named examplebucket:

    ossutil ls oss://examplebucket --all-versions

    The following output indicates that all versions of all objects in the examplebucket bucket are listed.

    LastModifiedTime                   Size(B)  StorageClass   ETag                                   VERSIONID                                                           IS-LATEST   DELETE-MARKER   ObjectName
    2020-12-01 15:06:37 +0800 CST         114      Standard   61DE142E5AFF9A6748707D4A77BFBCFB      CAEQARiBgICUsOuR2hYiIDI3NWVjNmEyYmM0NTRkZWNiMTkxY2VjMDMwZjFlMDA3    true        false           oss://examplebucket/example.txt
    2020-06-11 11:03:37 +0800 CST      363812      Standard   E7581E5D2EBC56ECCB6FB6050B4C6545      CAEQARiBgIDZtvuR2hYiIDNhYjRkN2M5NTA5OTRlN2Q4YTYzODQwMzQ4NDYwZDdm    true        false           oss://examplebucket/examplefolder/photo.jpg
    2021-01-26 13:27:08 +0800 CST           0                                                       CAEQLxiBgIDd7NH0uRciIDA3Yzg0MTZjOWNlYzQ4ODZhMzVkZWE0MmE2NzBlYTYx    true        true            oss://examplebucket/image.png
    2020-12-01 15:06:45 +0800 CST    57374182      Standard   BE97B7AD7A2C1277B11221E5C9537544      CAEQLBiBgMDZiprwthciIDY2NGM0NTNmZDE3ODRmZmVhZGM4YTUwZGQyNGU3ZjQ3    true        false           oss://examplebucket/video.mp4
    2016-06-11 10:53:46 +0800 CST      118076      Standard   FFDB300F053AAF06F4C4C58A4869C427      CAEQARiBgID8rumR2hYiIGUyOTAyZGY2MzU5MjQ5ZjlhYzQzZjNlYTAyZDE3MDRk    false       false           oss://examplebucket/example.txt
    2016-06-11 11:02:05 +0800 CST      345374      Standard   078A9852BCF81DC4811E6EDCBFD121BE      CAEQARiBgICNz_iR2hYiIGJjZTBjNDQxYWRhNTQ2ZTNiNmMzYzQ1YzMzMDA5ZjUw    false       false           oss://examplebucket/examplefolder/photo.jpg
    Object Number is: 6
    
    0.692000(s) elapsed

  • List all versions of an object named example.txt in the root directory of a bucket named examplebucket:

    ossutil ls oss://examplebucket/example.txt --all-versions

    The following output indicates that all versions of the example.txt object are listed.

    LastModifiedTime                   Size(B)  StorageClass  ETag                                   VERSIONID                                                           IS-LATEST   DELETE-MARKER  ObjectName
    2020-12-01 15:06:37 +0800 CST         114      Standard   61DE142E5AFF9A6748707D4A77BFBCFB      CAEQARiBgICUsOuR2hYiIDI3NWVjNmEyYmM0NTRkZWNiMTkxY2VjMDMwZjFlMDA3    true        false           oss://examplebucket/example.txt
    2016-06-11 10:53:46 +0800 CST         114      Standard   61DE142E5AFF9A6748707D4A77BFBCFB      CAEQARiBgID8rumR2hYiIGUyOTAyZGY2MzU5MjQ5ZjlhYzQzZjNlYTAyZDE3MDRk    false       false           oss://examplebucket/example.txt
    Object Number is: 2
    
    0.361000(s) elapsed

List parts

• Command syntax

  ossutil ls oss://bucketname[/prefix] [-s] [-d] [-m] [-a] [--limited-num] [--upload-id-marker] 

  The following table describes the parameters in the syntax.

  Parameter	Description
  bucketname	The name of the bucket. If you want to list resources in a specific bucket, specify this parameter.
  prefix	Specifies that the parts whose names contain a specific prefix are listed.
  -s	Specifies that the command returns only upload IDs and object names.
  -d	Specifies that only objects and subdirectories in the root directory of the bucket are listed. Objects in subdirectories are not listed.
  -m	Specifies that the command lists parts.
  -a	Specifies that the command lists objects and parts.
  --limited-num	The maximum number of results that you want to return. You can specify this parameter together with the --upload-id-marker parameter to display returned results by page.
  --upload-id-marker	The position from which the list operation starts. Parts whose upload IDs are alphabetically after the marker are listed.

• Examples

  • List all parts in a bucket named examplebucket:

    ossutil ls oss://examplebucket -m

    The following output indicates that all parts in the examplebucket bucket are listed.

    InitiatedTime                     UploadID                           ObjectName
    2017-01-13 03:45:26 +0000 CST     15754AF7980C4DFB8193F190837520BB    oss://examplebucket/test.mp4
    2017-01-13 03:45:13 +0000 CST     2A1F9B4A95E341BD9285CC42BB950EE0    oss://examplebucket/test.mp4
    2017-01-13 03:45:01 +0000 CST     3998971ACAF94AD9AC48EAC1988BE863    oss://examplebucket/test.mp4
    2017-01-20 11:16:21 +0800 CST     A20157A7B2FEC4670626DAE0F4C0073C    oss://examplebucket/object.exe
    UploadId Number is:4
    0.191289(s) elapsed  

  • List all objects and parts in a bucket named examplebucket:

    ossutil ls oss://examplebucket -a

    The following output indicates that all objects and parts in the examplebucket bucket are listed.

    LastModifiedTime                    Size(B)  StorageClass   ETag                                     ObjectName
    2020-12-01 15:06:37 +0800 CST           114      Standard   61DE142E5AFF9A6748707D4A77BFBCFB        oss://examplebucket/example.txt
    2020-12-01 15:06:42 +0800 CST        363812      Standard   E7581E5D2EBC56ECCB6FB6050B4C6545        oss://examplebucket/examplefolder/photo.jpg
    2020-12-01 15:06:45 +0800 CST      57374182      Standard   BE97B7AD7A2C1277B11221E5C9537544        oss://examplebucket/video.mp4
    Object Number is:3
    InitiatedTime                     UploadID                           ObjectName
    2017-01-13 03:45:26 +0000 CST     15754AF7980C4DFB8193F190837520BB    oss://examplebucket/test.mp4
    2017-01-13 03:45:13 +0000 CST     2A1F9B4A95E341BD9285CC42BB950EE0    oss://examplebucket/test.mp4
    2017-01-13 03:45:01 +0000 CST     3998971ACAF94AD9AC48EAC1988BE863    oss://examplebucket/test.mp4
    2017-01-20 11:16:21 +0800 CST     A20157A7B2FEC4670626DAE0F4C0073C    oss://examplebucket/object.exe
    UploadId Number is:4
    0.791289(s) elapsed  

Common options

If you use ossutil to switch to a bucket that is located in another region, add the -e option to specify the endpoint of the region in which the bucket is located. If you use ossutil to switch to a bucket that belongs to another Alibaba Cloud account, add the -i option to specify the AccessKey ID of the specified account, and add the -k option to specify the AccessKey secret of the specified account.

ossutil ls oss://test -e oss-cn-hangzhou.aliyuncs.com -i yourAccessKeyID  -k yourAccessKeySecret

For more information about common options, see Common options.