How to delete files from a versioning-enabled bucket using the Python SDK - Object Storage Service

This topic describes how to delete one or more files (objects), or files with a specified prefix, from a versioning-enabled bucket.

Usage notes

In this topic, the public endpoint of the China (Hangzhou) region is used. If you want to access OSS from other Alibaba Cloud services in the same region as OSS, use an internal endpoint. For more information about OSS regions and endpoints, see Regions and endpoints.
In this topic, access credentials are obtained from environment variables. For more information about how to configure access credentials, see Configure access credentials using OSS SDK for Python 1.0.
In this topic, an OSSClient instance is created by using an OSS endpoint. If you want to create an OSSClient instance by using custom domain names or Security Token Service (STS), see Initialization.
To delete an object, you must have the oss:DeleteObject permission. For more information, see Attach a custom policy to a RAM user.

Delete behaviors in a versioning-enabled bucket

The delete behavior is as follows:

Without a specified versionId (soft delete):
If you perform a delete operation without specifying a versionId, OSS inserts a delete marker for the current version of the object instead of deleting the object. When you then perform a GetObject operation, OSS detects the delete marker and returns a 404 Not Found error. The response also returns the x-oss-delete-marker = true header and the version number of the new delete marker in the x-oss-version-id header.
A value of true for x-oss-delete-marker indicates that the version corresponding to the returned x-oss-version-id is a delete marker.
With a specified versionId (permanent delete):
If you perform a delete operation and specify a versionId, OSS permanently deletes that version of the object based on the params object's versionId parameter. To delete a version with the ID "null", use the params parameter and set params['versionId'] = "null". OSS treats the string "null" as the versionId "null" and deletes the object with this versionId.

Delete a single file

The following examples show how to permanently or soft delete a single object.

Permanent delete

The following code shows how to permanently delete an object by specifying its versionId:

# -*- coding: utf-8 -*-
import os
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider
# Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured.
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())

# Specify the endpoint of the region where the bucket is located. For example, if the bucket is in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com.
endpoint = "https://oss-cn-hangzhou.aliyuncs.com"
# Specify the region information that corresponds to the endpoint, for example, cn-hangzhou. Note that this parameter is required for V4 signatures.
region = "cn-hangzhou"

# Set yourBucketName to the name of the bucket.
bucket = oss2.Bucket(auth, endpoint, "yourBucketName", region=region)

# Set yourObjectName to the full path of the object. Do not include the bucket name. Example: example/test.txt.
object_name = 'yourObjectName'

# Specify the versionId of the object. This can also be the versionId of a delete marker.
params = dict()
params['versionId'] = 'yourObjectVersionIdOrDeleteMarkerVersionId'

# Delete the object or the object associated with the delete marker that has the specified versionId.
result = bucket.delete_object(object_name, params=params)
print("delete object name: ", object_name)
# If the versionId of an object is specified, the returned delete_marker is None and the returned versionId is the versionId of the specified object.
# If the versionId of a delete marker is specified, the returned delete_marker is True and the returned versionId is the versionId of the specified delete marker.
if result.delete_marker:
    print("delete del-marker versionid: ",result.versionid)
else:
    print("delete object versionid:", result.versionid)

Soft delete

The following code shows how to soft delete an object without specifying a versionId:

# -*- coding: utf-8 -*-
import os
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider
# Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured.
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())

# Specify the endpoint of the region where the bucket is located. For example, if the bucket is in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com.
endpoint = "https://oss-cn-hangzhou.aliyuncs.com"
# Specify the region information that corresponds to the endpoint, for example, cn-hangzhou. Note that this parameter is required for V4 signatures.
region = "cn-hangzhou"

# Set yourBucketName to the name of the bucket.
bucket = oss2.Bucket(auth, endpoint, "yourBucketName", region=region)

# Set yourObjectName to the full path of the object. Do not include the bucket name. Example: example/test.txt.
object_name = 'yourObjectName'

# Soft delete the object without specifying a versionId. This operation adds a delete marker to the object.
result = bucket.delete_object(object_name)
# View the delete marker.
print("delete marker: ", result.delete_marker)
# View the versionId of the returned delete marker.
print("delete marker versionid: ", result.versionid)

Delete multiple files

The following examples show how to permanently or soft delete multiple objects.

Permanent delete

The following code shows how to permanently delete multiple objects and delete markers by specifying their versionIds:

# -*- coding: utf-8 -*-
import os
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider
from oss2.models import BatchDeleteObjectVersion
from oss2.models import BatchDeleteObjectVersionList
# Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured.
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())

# Specify the endpoint of the region where the bucket is located. For example, if the bucket is in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com.
endpoint = "https://oss-cn-hangzhou.aliyuncs.com"
# Specify the region information that corresponds to the endpoint, for example, cn-hangzhou. Note that this parameter is required for V4 signatures.
region = "cn-hangzhou"

# Set yourBucketName to the name of the bucket.
bucket = oss2.Bucket(auth, endpoint, "yourBucketName", region=region)

version_list = BatchDeleteObjectVersionList()
# You can pass the versionId of an object or a delete marker.
obj1_versionid = 'yourObject1VersionId'
obj1_del_marker_versionid = 'yourObject1DelMarkerVersionId'
obj2_versionid = 'yourObject2VersionId'
obj2_del_marker_versionid = 'yourObject2DelMarkerVersionId'
version_list.append(BatchDeleteObjectVersion(key='yourObject1Name', versionid=obj1_versionid))
version_list.append(BatchDeleteObjectVersion(key='yourObject1Name', versionid=obj1_del_marker_versionid))
version_list.append(BatchDeleteObjectVersion(key='yourObject2Name', versionid=obj2_versionid))
version_list.append(BatchDeleteObjectVersion(key='yourObject2Name', versionid=obj2_del_marker_versionid))

# Batch delete objects or delete markers with specified versionIds.
result = bucket.delete_object_versions(version_list)
# View the versionIds of the deleted objects or delete markers.
for del_version in result.delete_versions:
    print('del object name:', del_version.key)
    # Check whether a delete marker was deleted.
    print('Is del marker:', del_version.delete_marker)
    # If a delete marker was deleted, print the versionId of the deleted delete marker. Otherwise, print the versionId of the deleted object.
    if del_version.delete_marker:
        print('del object del_marker.versionid', del_version.delete_marker_versionid)
    else:
        print('del object versionid:', del_version.versionid)

Soft delete

The following code shows how to soft delete multiple objects without specifying their versionIds:

# -*- coding: utf-8 -*-
import os
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider
from oss2.models import BatchDeleteObjectVersion
from oss2.models import BatchDeleteObjectVersionList
# Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured.
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())

# Specify the endpoint of the region where the bucket is located. For example, if the bucket is in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com.
endpoint = "https://oss-cn-hangzhou.aliyuncs.com"
# Specify the region information that corresponds to the endpoint, for example, cn-hangzhou. Note that this parameter is required for V4 signatures.
region = "cn-hangzhou"

# Set yourBucketName to the name of the bucket.
bucket = oss2.Bucket(auth, endpoint, "yourBucketName", region=region)


key_list = ['yourObject1Name', 'yourObject2Name']
# After you perform a delete operation without specifying a versionId, a delete marker is added to the object.
result = bucket.batch_delete_objects(key_list)
for del_version in result.delete_versions:
    print('key name:', del_version.key)
    # Print the returned delete marker.
    print('Is del marker:', del_version.delete_marker)
    print('key del_marker.versionid', del_version.delete_marker_versionid)

Delete files with a specified prefix

The following code shows how to delete files that have a specified prefix:

# -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider
# Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured.
auth = oss2.ProviderAuth(EnvironmentVariableCredentialsProvider())
# Specify the endpoint of the region where the bucket is located. For example, if the bucket is in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com.
# Set yourBucketName to the name of the bucket.
bucket = oss2.Bucket(auth, 'https://oss-cn-hangzhou.aliyuncs.com', 'yourBucketName')
prefix = "yourKeyPrefix"

# List the versionIds of all files with the specified prefix and delete these files.
next_key_marker = None
next_versionid_marker = None
while True:
    result = bucket.list_object_versions(prefix=prefix, key_marker=next_key_marker, versionid_marker=next_versionid_marker)

    for version_info in result.versions:
        bucket.delete_object(version_info.key, params={'versionId': version_info.versionid})

    for del_marker_info in result.delete_marker:
        bucket.delete_object(del_marker_info.key, params={'versionId': del_marker_info.versionid})

    is_truncated = result.is_truncated

    if is_truncated:
        next_key_marker = result.next_key_marker
        next_versionid_marker = result.next_versionid_marker
    else:
        break

References

For more information about the API operation to delete a single file, see DeleteObject.
For more information about the API operation to delete multiple files, see DeleteMultipleObjects.