All Products
Search

This Product

    ENS:ListObjects

    Document Center

    ENS:ListObjects

    Last Updated:Dec 25, 2024

    Queries the information about all objects in a bucket.

    Debugging

    You can run this interface directly in OpenAPI Explorer, saving you the trouble of calculating signatures. After running successfully, OpenAPI Explorer can automatically generate SDK code samples.

    Authorization information

    The following table shows the authorization information corresponding to the API. The authorization information can be used in the Action policy element to grant a RAM user or RAM role the permissions to call this API operation. Description:

    • Operation: the value that you can use in the Action element to specify the operation on a resource.
    • Access level: the access level of each operation. The levels are read, write, and list.
    • Resource type: the type of the resource on which you can authorize the RAM user or the RAM role to perform the operation. Take note of the following items:
      • The required resource types are displayed in bold characters.
      • If the permissions cannot be granted at the resource level, All Resources is used in the Resource type column of the operation.
    • Condition Key: the condition key that is defined by the cloud service.
    • Associated operation: other operations that the RAM user or the RAM role must have permissions to perform to complete the operation. To complete the operation, the RAM user or the RAM role must have the permissions to perform the associated operations.
    OperationAccess levelResource typeCondition keyAssociated operation
    ens:ListObjectslist
    *All Resources
    *
      none
    		none

    Request parameters

    ParameterTypeRequiredDescriptionExample
    BucketNamestringYes

    The name of the bucket.

    		test
    EncodingTypestringNo

    The encoding type of the object names in the response. Only URL encoding is supported.

    		url
    MarkerstringNo

    The position from which the list operation starts. If this parameter is specified, objects whose names are alphabetically greater than value of Marker are returned. The Marker parameter is used to list the returned objects by page, and its value must be smaller than 1,024 bytes in length.

    Even if the value specified for Marker does not exist in the list during a conditional query, the list starts from the object whose name is alphabetically greater than the value of Marker.

    		a
    MaxKeyslongNo

    The maximum number of objects to return. Valid values: 0 to 1000. Default value: 100.

    		100
    PrefixstringNo

    The prefix that must be included in the names of objects you want to list. If you specify a prefix to query objects, the returned object names contain the prefix.

    The value of the parameter must be less than 1,000 bytes in length.

    		b
    ContinuationTokenstringNo

    The token used in this list operation. If the number of objects exceeds the value of MaxKeys, the NextContinuationToken is included in the response as the token for the next list operation.

    		test1.txt
    StartAfterstringNo

    The position from which the list operation starts. If this parameter is specified, objects whose names are alphabetically greater than the value of StartAfter are returned. The StartAfter parameter is used to list the returned objects by page, and its value must be less than 1,000 bytes in length. Even if the value specified for StartAfter does not exist in the list during a conditional query, the list starts from the object whose name is alphabetically greater than the value of StartAfter.

    		b

    Response parameters

    ParameterTypeDescriptionExample
    object
    CommonPrefixesarray

    If the delimiter parameter is specified in the request, the response contains CommonPrefixes. Objects whose names contain the same string from the prefix to the next occurrence of the delimiter are grouped as a single result element in CommonPrefixes.

    Prefixstring

    If the delimiter parameter is specified in the request, the response contains CommonPrefixes. Objects whose names contain the same string from the prefix to the next occurrence of the delimiter are grouped as a single result element in CommonPrefixes.

    		N/A
    NextContinuationTokenstring

    The token used in the next list operation.

    		CgJiYw--
    ContinuationTokenstring

    The token used in this list operation.

    		test1.txt
    Delimiterstring

    The character used to group objects by name.

    		/
    EncodingTypestring

    The encoding type of the object names in the response.

    		N/A
    Prefixstring

    The prefix contained in the names of returned objects.

    		b
    Markerstring

    The position from which the list operation starts.

    		ceshi.txt1617853707991
    BucketNamestring

    The name of the bucket.

    		test
    Contentsarray<object>

    The list of object metadata.

    Contentobject
    Keystring

    The name of the object.

    		ceshi.txt1617853706546
    LastModifiedstring

    The time when the object was last modified.

    		2021-04-08T03:48:47.488Z
    ETagstring

    The entity tag (ETag). When an object is created, an ETag is created to identify the content of the object.

    • For an object that is created by calling the PutObject operation, the ETag value of the object is the MD5 hash of the object content.
    • For an object that is not created by calling the PutObject operation, the ETag value of the object is the UUID of the object content.
    • The ETag of an object can be used to check whether the object content is modified. However, we recommend that you use the MD5 hash of an object rather than the ETag value of the object to verify data integrity.
    		5B3C1A2E053D763E1B002CC607C5****
    Sizelong

    The size of the returned object. Unit: bytes.

    		15
    IsTruncatedboolean

    Indicates whether the listed objects are truncated. Valid values:

    • false
    • true
    		true
    KeyCountlong

    The number of keys returned for this request.

    		10
    NextMarkerstring

    The position from which the next list operation starts.

    		ceshi.txt1617853707991
    MaxKeyslong

    The maximum number of objects returned.

    		10
    RequestIdstring

    The ID of the request.

    		4833C4AC-9396-458C-8F25-1D701334E560

    Examples

    Sample success responses

    JSONformat

    {
  "CommonPrefixes": [
    "N/A"
  ],
  "NextContinuationToken": "CgJiYw--",
  "ContinuationToken": "test1.txt",
  "Delimiter": "/",
  "EncodingType": "N/A",
  "Prefix": "b",
  "Marker": "ceshi.txt1617853707991",
  "BucketName": "test",
  "Contents": [
    {
      "Key": "ceshi.txt1617853706546",
      "LastModified": "2021-04-08T03:48:47.488Z",
      "ETag": "5B3C1A2E053D763E1B002CC607C5****",
      "Size": 15
    }
  ],
  "IsTruncated": true,
  "KeyCount": 10,
  "NextMarker": "ceshi.txt1617853707991",
  "MaxKeys": 10,
  "RequestId": "4833C4AC-9396-458C-8F25-1D701334E560"
}

    Error codes

    HTTP status codeError codeError messageDescription
    400Invalid%sSpecified parameter %s is not valid-
    400InvalidBucketNameSpecified parameter BucketName is not valid.-
    400InvalidPrefixSpecified parameter Prefix is not valid.-
    400InvalidStartAfterSpecified parameter StartAfter is not valid.-
    400InvalidMarkerSpecified parameter Marker is not valid.-
    400InvalidDelimiterSpecified parameter Delimiter is not valid.-
    400NoPermissionPermission denied.-
    400InvalidParameter.%sThe specified field %s invalid. Please check it again.-
    403AccessDeniedauth is not valid-
    404NoSuchBucketThe specified bucket does not exist.The requested bucket does not exist.
    500InternalErrorThe request processing has failed due to some unknown error.-

    For a list of error codes, visit the Service error codes.

    Change history

    Change timeSummary of changesOperation
    No change history