Description
The DELETE Multiple Object API is used to delete objects in a specified bucket in batches. Up to 1000 objects can be deleted at a time. COS offers two response modes: Verbose and Quiet. In Verbose mode, the deletion result of each object is returned. In Quiet mode, only information about objects that had errors is returned.
Note:
This request must carry Content-MD5 to verify the integrity of the Body.
Notes
- Each batch delete request can contain a maximum of 1,000 objects to be deleted.
- Batch deletion supports two modes of return: verbose and quiet. The default mode is verbose. The verbose mode returns the deletion status of each key, and the quiet mode only returns the status of the keys that failed to be deleted.
- Batch deletion requires the Content-MD5 header to verify that the request body has not been modified.
- Batch deletion requests allow a non-existent key to be deleted and still be considered successful.
Versioning
If versioning is enabled, you can specify a version ID for each object to delete, and the specified version or delete marker is permanently deleted. Otherwise, a new delete marker is created as the latest version of the specified object.
If a delete marker is created or deleted for an object deletion operation, both true and are included in the deletion result of the object, indicating that the delete marker of the specified object is created or deleted.
If a specific version ID (including the version ID of the delete marker) is permanently deleted in an object deletion operation, the deletion result includes the element, indicating the version ID that was deleted.
Request
Syntax example:
POST /?delete HTTP/1.1
Host: <BucketName-APPID>.<Endpoint>
Date: GMT Date
Content-Length: length
Content-Type: application/xml
Content-MD5: MD5
Authorization: Auth String
<Delete>
<Quiet></Quiet>
<Object>
<Key></Key>
</Object>
<Object>
<Key></Key>
</Object>
...
</Delete>
Note:
Authorization: Auth String (See Request Signature for details.)
Request Line
POST /?delete HTTP/1.1
This API accepts POST requests.
Request Header
Common Headers
This request operation is implemented by using the public request header. For details about the public request header, see Common Request Headers documentation.
Non-common Headers
Required headers:
This request is implemented by using the following required headers.
| Name | Description | Type | Required |
|---|---|---|---|
| Content-Length | HTTP request content length (bytes) defined in RFC 2616. | String | Yes |
| Content-MD5 | Base64-encoded 128-bit content MD5 checksum as defined in RFC 1864. This header is used to verify whether the file content has changed. | String | Yes |
Request Body
The specific node content of the request body of this request is as follows.
<Delete>
<Quiet></Quiet>
<Object>
<Key></Key>
</Object>
<Object>
<Key></Key>
</Object>
...
</Delete>
The specific contents are described as follows:
| Node Name (Keyword) | Parent Node | Description | Type | Required |
|---|---|---|---|---|
| DELETE | No | Describes the return result method and target object of this deletion. | Container | Yes |
| Quiet | DELETE | Boolean value, this value determines whether to enable the Quiet mode. A value of true starts Quiet mode, a value of false starts Verbose mode, and the default value is False. |
Boolean | No |
| Object | DELETE | Describes the information of each target object to be deleted. | Container | Yes |
| Key | DELETE.Object | Target Object File Name | String | Yes |
Response
Response Headers
Common Response Headers
This response utilizes common response headers. For details on common response headers, please refer to the Public Response Header document.
Special Response Headers
There are no special response headers for this request operation.
Response Body
The response body returns application/xml data. The following contains all the nodes:
<DeleteResult>
<Deleted>
<Key></Key>
</Deleted>
<Error>
<Key></Key>
<Code></Code>
<Message></Message>
</Error>
</DeleteResult>
The specific contents are as follows:
| Node Name (Keyword) | Parent Node | Description | Type |
|---|---|---|---|
| DeleteResult | No | Describes the return result method and target object of this deletion. | Container |
Contents of the Container node DeleteResult:
| Node Name (Keyword) | Parent Node | Description | Type |
|---|---|---|---|
| Deleted | DeleteResult | Information about objects that are successfully deleted. | Boolean |
| Error | DeleteResult | Information about objects that fail to be deleted. | Container |
Contents of the Container node Deleted:
| Node Name (Keyword) | Parent Node | Description | Type |
|---|---|---|---|
| Key | DeleteResult.Deleted | Name of an object. | String |
Contents of the Container node Error:
| Node Name (Keyword) | Parent Node | Description | Type |
|---|---|---|---|
| Key | DeleteResult.Error | The name of the object that failed to be deleted. | String |
| Code | DeleteResult.Error | Deletion failed error code | String |
| Message | DeleteResult.Error | Deletion failed error message | String |
Error Analysis
The following describes some special but common errors that may occur with this request:
| Error Code | HTTP Status Code | Description |
|---|---|---|
| InvalidRequest | 400 Bad Request | The required field Content-MD5 is not carried, and error message Missing required header for this request: Content-MD5 is returned. |
| MalformedXML | 400 Bad Request | If the number of requested keys exceeds 1000, a MalformedXML error will be returned, along with delete key size being greater than 1000. |
| InvalidDigest | 400 Bad Request | The Content-MD5 carried is inconsistent with the request body calculated by the server. |
For more information on COS error codes or the complete list of product errors, please refer to the Error Codes document.
Practical Case
Request
POST /?delete HTTP/1.1
Host: <BucketName-APPID>.<Endpoint>
Date: Wed, 23 Oct 2016 21:32:00 GMT
Connection: keep-alive
Accept-Encoding: gzip, deflate
Accept: */*
User-Agent: python-requests/2.12.4
Authorization: q-sign-algorithm=sha1&q-ak=AKIDxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&q-sign-time=1480932292;1981012292&q-key-time=1480932292;1981012292&q-url-param-list=delete&q-header-list=host&q-signature=c54f22fd92232a76972ba599cba25a8a733d2fef
Content-MD5: yoLiNjQuvB7lu8cEmPafrQ==
Content-Length: 125
<Delete>
<Quiet>true</Quiet>
<Object>
<Key>aa</Key>
</Object>
<Object>
<Key>aaa</Key>
</Object>
</Delete>
Response
HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 17
Connection: keep-alive
Date: Tue, 22 Aug 2017 12:00:48 GMT
x-cos-request-id: NTk5YzFjZjBfZWFhZDM1MGFfMjkwZV9lZGM3ZQ==
<DeleteResult/>
Request
POST /?delete HTTP/1.1
Host: <BucketName-APPID>.<Endpoint>
Date: Tue, 22 Aug 2017 12:16:35 GMT
Connection: keep-alive
Accept-Encoding: gzip, deflate
Accept: */*
User-Agent: python-requests/2.12.4
Authorization: q-sign-algorithm=sha1&q-ak=AKIDxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&q-sign-time=1480932292;1981012292&q-key-time=1480932292;1981012292&q-url-param-list=delete&q-header-list=host&q-signature=c54f22fd92232a76972ba599cba25a8a733d2fef
Content-MD5: V0XuU8V7aqMYeWyD3BC2nQ==
Content-Length: 126
<Delete>
<Quiet>false</Quiet>
<Object>
<Key>aa</Key>
</Object>
<Object>
<Key>aaa</Key>
</Object>
</Delete>
Response
HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 111
Connection: keep-alive
Date: Tue, 22 Aug 2017 12:16:35 GMT
x-cos-request-id: NTk5YzIwYTNfMzFhYzM1MGFfMmNmOWZfZWVhNjQ=
<DeleteResult>
<Deleted>
<Key>aa</Key>
</Deleted>
<Deleted>
<Key>aaa</Key>
</Deleted>
</DeleteResult>