• Object Storage Service

obs
  1. Help Center
  2. Object Storage Service
  3. Developer Guide (Python SDK)
  4. Versioning Management
  5. Listing Versioning Objects

Listing Versioning Objects

You can call ObsClient.listVersions to list versioning objects.

The following table describes the parameters involved in this API.

Parameter

Description

Versions.prefix

Name prefix that the objects to be listed must contain

Versions.key_marker

Object name to start with when listing versioning objects in a bucket. All versioning objects whose names follow this parameter are listed in the lexicographical order.

Versions.max_keys

Maximum number of listed versioning objects. The value ranges from 1 to 1000. If the value is not in this range, 1000 versioning objects are returned by default.

Versions.delimiter

Character used to group object names. If the object name contains the delimiter parameter, the character string from the first character to the first delimiter in the object name is grouped under a single result element, commonPrefix. (If a prefix is specified in the request, the prefix must be removed from the object name.)

Versions.version_id_marker

Object name to start with when listing versioning objects in a bucket. All versioning objects are listed in the lexicographical order by object name and version ID. This parameter must be used together with key_marker.

NOTE:
  • If the value of version_id_marker is not a version ID specified by key_marker, version_id_marker is ineffective.
  • The returned result of ObsClient.listVersions includes the versioning objects and delete markers.

Listing Versioning Objects in Simple Mode

The following sample code shows how to list versioning objects in simple mode. A maximum of 1000 versioning objects can be listed.

# Import the module.
from com.obs.client.obs_client import ObsClient
# Create an instance of ObsClient.
obsClient = ObsClient(
    access_key_id='*** Provide your Access Key ***',    
    secret_access_key='*** Provide your Secret Key ***',    
    server='yourdomainname'
)

resp = obsClient.listVersions('bucketname')
if resp.status < 300:
    print('requestId:', resp.requestId)
    # Obtain versioning objects.
    index = 1    
    for version in resp.body.versions:        
        print('version [' + str(index) + ']')        
        print('key:', version.key)        
        print('versionId:', version.versionId)        
        print('owner_id:', version.owner.owner_id)        
        print('owner_name:', version.owner.owner_name)        
        index += 1        
    # Obtain delete markers.
    index = 1    
    for marker in resp.body.markers:        
        print('marker [' + str(index) + ']')        
        print('key:', marker.key)        
        print('versionId:', marker.versionId)        
        print('owner_id:', marker.owner.owner_id)        
        print('owner_name:', marker.owner.owner_name)        
        index += 1
else:
    print('errorCode:', resp.errorCode)
    print('errorMessage:', resp.errorMessage)
NOTE:
  • A maximum of 1000 versioning objects can be listed each time. If a bucket contains more than 1000 objects and body.head.isTruncated is True in the returned result, not all versioning objects are listed. In such cases, you can use body.head.nextKeyMarker and body.head.nextVersionIdMarker to obtain the start position for next listing.
  • If you want to obtain all versioning objects in a specified bucket, you can use the paging mode for listing objects.

Listing Versioning Objects by Specifying the Number

Sample code:

# Import the module.
from com.obs.client.obs_client import ObsClient
# Create an instance of ObsClient.
obsClient = ObsClient(
    access_key_id='*** Provide your Access Key ***',    
    secret_access_key='*** Provide your Secret Key ***',    
    server='yourdomainname'
)

from com.obs.models.versions import Versions
versions = Versions()
# List 100 versioning objects.
versions.max_keys = 100

resp = obsClient.listVersions('bucketname', version=versions)

if resp.status < 300:
    print('requestId:', resp.requestId)
    # Obtain versioning objects.
    index = 1    
    for version in resp.body.versions:        
        print('version [' + str(index) + ']')        
        print('key:', version.key)        
        print('versionId:', version.versionId)        
        print('owner_id:', version.owner.owner_id)        
        print('owner_name:', version.owner.owner_name)        
        index += 1        
    # Obtain delete markers.
    index = 1    
    for marker in resp.body.markers:        
        print('marker [' + str(index) + ']')        
        print('key:', marker.key)        
        print('versionId:', marker.versionId)        
        print('owner_id:', marker.owner.owner_id)        
        print('owner_name:', marker.owner.owner_name)        
        index += 1
else:
    print('errorCode:', resp.errorCode)
    print('errorMessage:', resp.errorMessage)

Listing Versioning Objects by Specifying a Prefix

Sample code:

# Import the module.
from com.obs.client.obs_client import ObsClient
# Create an instance of ObsClient.
obsClient = ObsClient(
    access_key_id='*** Provide your Access Key ***',    
    secret_access_key='*** Provide your Secret Key ***',    
    server='yourdomainname'
)

from com.obs.models.versions import Versions
versions = Versions()
# Set the prefix to prefix and the number to 100.
versions.max_keys = 100
versions.prefix = 'prefix'

resp = obsClient.listVersions('bucketname', version=versions)

if resp.status < 300:
    print('requestId:', resp.requestId)
    # Obtain versioning objects.
    index = 1    
    for version in resp.body.versions:        
        print('version [' + str(index) + ']')        
        print('key:', version.key)        
        print('versionId:', version.versionId)        
        print('owner_id:', version.owner.owner_id)        
        print('owner_name:', version.owner.owner_name)        
        index += 1        
    # Obtain delete markers.
    index = 1    
    for marker in resp.body.markers:        
        print('marker [' + str(index) + ']')        
        print('key:', marker.key)        
        print('versionId:', marker.versionId)        
        print('owner_id:', marker.owner.owner_id)        
        print('owner_name:', marker.owner.owner_name)        
        index += 1
else:
    print('errorCode:', resp.errorCode)
    print('errorMessage:', resp.errorMessage) 

Listing Versioning Objects by Specifying the Start Position

Sample code:

# Import the module.
from com.obs.client.obs_client import ObsClient
# Create an instance of ObsClient.
obsClient = ObsClient(
    access_key_id='*** Provide your Access Key ***',    
    secret_access_key='*** Provide your Secret Key ***',    
    server='yourdomainname'
)

from com.obs.models.versions import Versions
versions = Versions()
# List 100 versioning objects whose names are following test in lexicographical order.
versions.max_keys = 100
versions.key_marker = 'test'

resp = obsClient.listVersions('bucketname', version=versions)

if resp.status < 300:
    print('requestId:', resp.requestId)
    # Obtain versioning objects.
    index = 1    
    for version in resp.body.versions:        
        print('version [' + str(index) + ']')        
        print('key:', version.key)        
        print('versionId:', version.versionId)        
        print('owner_id:', version.owner.owner_id)        
        print('owner_name:', version.owner.owner_name)        
        index += 1        
    # Obtain delete markers.
    index = 1    
    for marker in resp.body.markers:        
        print('marker [' + str(index) + ']')        
        print('key:', marker.key)        
        print('versionId:', marker.versionId)        
        print('owner_id:', marker.owner.owner_id)        
        print('owner_name:', marker.owner.owner_name)        
        index += 1
else:
    print('errorCode:', resp.errorCode)
    print('errorMessage:', resp.errorMessage) 

Listing All Versioning Objects in Paging Mode

Sample code:

# Import the module.
from com.obs.client.obs_client import ObsClient
# Create an instance of ObsClient.
obsClient = ObsClient(
    access_key_id='*** Provide your Access Key ***',    
    secret_access_key='*** Provide your Secret Key ***',    
    server='yourdomainname'
)

from com.obs.models.versions import Versions
versions = Versions()
versions.max_keys = 100

while True:
    resp = obsClient.listVersions('bucketname', version=versions)
    if resp.status < 300:
        print('requestId:', resp.requestId)
        # Obtain versioning objects.
        index = 1    
        for version in resp.body.versions:        
            print('version [' + str(index) + ']')        
            print('key:', version.key)        
            print('versionId:', version.versionId)        
            print('owner_id:', version.owner.owner_id)        
            print('owner_name:', version.owner.owner_name)        
            index += 1        
        # Obtain delete markers.
        index = 1    
        for marker in resp.body.markers:        
            print('marker [' + str(index) + ']')        
            print('key:', marker.key)        
            print('versionId:', marker.versionId)        
            print('owner_id:', marker.owner.owner_id)        
            print('owner_name:', marker.owner.owner_name)        
            index += 1
        if not resp.body.head.isTruncated:
            break
        versions.key_marker = resp.body.head.nextKeyMarker
        versions.version_id_marker = resp.body.head.nextVersionIdMarker
    else:
        print('errorCode:', resp.errorCode)
        print('errorMessage:', resp.errorMessage)
        break 

Listing All Versioning Objects in a Folder

There is no folder concept in OBS. All elements in buckets are objects. Folders are actually objects whose sizes are 0 and whose names end with a slash (/). When you set a folder name as the prefix, objects in this folder will be listed. Sample code is as follows:

# Import the module.
from com.obs.client.obs_client import ObsClient
# Create an instance of ObsClient.
obsClient = ObsClient(
    access_key_id='*** Provide your Access Key ***',    
    secret_access_key='*** Provide your Secret Key ***',    
    server='yourdomainname'
)

from com.obs.models.versions import Versions
versions = Versions()
versions.max_keys = 100
versions.prefix = 'dir/'

while True:
    resp = obsClient.listVersions('bucketname', version=versions)
    if resp.status < 300:
        print('requestId:', resp.requestId)
        # Obtain versioning objects.
        index = 1    
        for version in resp.body.versions:        
            print('version [' + str(index) + ']')        
            print('key:', version.key)        
            print('versionId:', version.versionId)        
            print('owner_id:', version.owner.owner_id)        
            print('owner_name:', version.owner.owner_name)        
            index += 1        
        # Obtain delete markers.
        index = 1    
        for marker in resp.body.markers:        
            print('marker [' + str(index) + ']')        
            print('key:', marker.key)        
            print('versionId:', marker.versionId)        
            print('owner_id:', marker.owner.owner_id)        
            print('owner_name:', marker.owner.owner_name)        
            index += 1
        if not resp.body.head.isTruncated:
            break
        versions.key_marker = resp.body.head.nextKeyMarker
        versions.version_id_marker = resp.body.head.nextVersionIdMarker
    else:
        print('errorCode:', resp.errorCode)
        print('errorMessage:', resp.errorMessage)
        break 

Listing All Versioning Objects According to Folders in a Bucket

Sample code:

# Import the module.
from com.obs.client.obs_client import ObsClient
# Create an instance of ObsClient.
obsClient = ObsClient(
    access_key_id='*** Provide your Access Key ***',    
    secret_access_key='*** Provide your Secret Key ***',    
    server='yourdomainname'
)

def listVersionsByPrefix(resp, versions):
    for prefix in resp.body.commonPrefixs:
        versions.prefix = prefix.prefix
        subresp = obsClient.listVersions('bucketname', version=versions)
        if subresp.status < 300:
            print('Objects in folder [' + prefix.prefix + '] :')
            # Obtain versioning objects.
            index = 1    
            for version in subresp.body.versions:        
                print('version [' + str(index) + ']')        
                print('key:', version.key)        
                print('versionId:', version.versionId)        
                print('owner_id:', version.owner.owner_id)        
                print('owner_name:', version.owner.owner_name)        
                index += 1        
        # Obtain delete markers.
            index = 1    
            for marker in subresp.body.markers:        
                print('marker [' + str(index) + ']')        
                print('key:', marker.key)        
                print('versionId:', marker.versionId)        
                print('owner_id:', marker.owner.owner_id)        
                print('owner_name:', marker.owner.owner_name)        
                index += 1
        else:
            print('errorCode:', resp.errorCode)
            print('errorMessage:', resp.errorMessage)

from com.obs.models.versions import Versions
versions = Versions()
versions.delimiter = '/'

resp = obsClient.listVersions('bucketname', version=versions)

if resp.status < 300:
    print('Objects in the root directory:')
    # Obtain versioning objects.
    index = 1    
    for version in resp.body.versions:        
        print('version [' + str(index) + ']')        
        print('key:', version.key)        
        print('versionId:', version.versionId)        
        print('owner_id:', version.owner.owner_id)        
        print('owner_name:', version.owner.owner_name)        
        index += 1        
        # Obtain delete markers.
    index = 1    
    for marker in resp.body.markers:        
        print('marker [' + str(index) + ']')        
        print('key:', marker.key)        
        print('versionId:', marker.versionId)        
        print('owner_id:', marker.owner.owner_id)        
        print('owner_name:', marker.owner.owner_name)        
        index += 1
    listVersionsByPrefix(resp)
else:
    print('errorCode:', resp.errorCode)
    print('errorMessage:', resp.errorMessage)
NOTE:
  • The previous sample code does not include scenarios where the number of objects in a folder exceeds 1000.
  • Because objects and sub-folders in a folder are to be listed and all the objects end with a slash (/), delimiter is always a slash (/).
  • In the returned result of each recursion, body.versions includes the versioning objects in the folder, body.markers includes the delete markers in the folder, and body.commonPrefixs includes the sub-folders in the folder.