Updated on 2024-06-21 GMT+08:00

Listing Multipart Uploads (SDK for Go)

Function

This API lists ongoing multipart uploads.

Ongoing multipart uploads are the multipart uploads that have been initiated but have not been completed or aborted. A maximum of 1,000 multipart uploads can be returned in a response. If there are over 1,000 ongoing tasks satisfying the list criteria, you need to send more requests to query additional multipart uploads.

Restrictions

  • To list multipart uploads, you must be the bucket owner or have the required permission (obs:bucket:ListBucketMultipartUploads in IAM or ListBucketMultipartUploads in a bucket policy). For details, see Introduction to OBS Access Control, IAM Custom Policies, and Configuring an Object Policy.
  • The mapping between OBS regions and endpoints must comply with what is listed in Regions and Endpoints.
  • To list ongoing multipart uploads in a bucket, you must have the ListBucketMultipartUploads permission.
  • The bucket owner can grant others the ListBucketMultipartUploads permission.

Method

func (obsClient ObsClient) ListMultipartUploads(input *ListMultipartUploadsInput) (output *ListMultipartUploadsOutput, err error)

Request Parameters

Table 1 List of request parameters

Parameter

Type

Mandatory (Yes/No)

Description

input

*ListMultipartUploadsInput

Yes

Explanation:

Input parameters for listing multipart uploads. For details, see Table 2.

Table 2 ListMultipartUploadsInput

Parameter

Type

Mandatory (Yes/No)

Description

Bucket

string

Yes

Explanation:

Bucket name

Restrictions:

  • A bucket name must be unique across all accounts and regions.
  • A bucket name:
    • Must be 3 to 63 characters long and start with a digit or letter. Lowercase letters, digits, hyphens (-), and periods (.) are allowed.
    • Cannot be formatted as an IP address.
    • Cannot start or end with a hyphen (-) or period (.).
    • Cannot contain two consecutive periods (..), for example, my..bucket.
    • Cannot contain a period (.) and a hyphen (-) adjacent to each other, for example, my-.bucket or my.-bucket.
  • If you repeatedly create buckets of the same name in the same region, no error will be reported and the bucket attributes comply with those set in the first creation request.

Default value:

None

Prefix

string

No

Explanation:

Name prefix that the objects in the multipart uploads to be listed must contain

Assume that you have the following objects: logs/day1, logs/day2, logs/day3, and ExampleObject.jpg. If you specify logs/ as the prefix, the multipart uploads of logs/day1, logs/day2, and logs/day3 will be returned. If you leave this parameter blank, all multipart uploads in the bucket will be returned.

Restrictions:

The value must contain 1 to 1,024 characters.

Default value:

None

MaxUploads

int

No

Explanation:

Maximum number of listed multipart uploads

Restrictions:

If the specified value is greater than 1000, only 1,000 multipart uploads are returned.

Value range:

An integer from 1 to 1000

Default value:

1000

Delimiter

string

No

Explanation:

Object names are grouped by this parameter, which is often used with Prefix. If a prefix is specified, objects with the same string from the prefix to the first delimiter are grouped into one CommonPrefixes. If no prefix is specified, objects with the same string from the first character to the first delimiter are grouped into one CommonPrefixes.

Assume that a bucket has objects abcd, abcde, and bbcde in it. If delimiter is set to d and prefix is set to a, objects abcd and abcde are grouped into a CommonPrefixes with abcd as the prefix. If only delimiter is set to d, objects abcd and abcde are grouped into a CommonPrefixes with abcd as the prefix, and bbcde is grouped separately into another CommonPrefixes with bbcd as the prefix.

Value range:

The value must contain 1 to 1,024 characters.

Default value:

None

KeyMarker

string

No

Explanation:

Object name after which multipart upload listing begins

Value range:

Value of NextKeyMarker in the response body of the last request

Default value:

None

UploadIdMarker

string

No

Explanation:

Upload ID after which the multipart upload listing begins

Restrictions:

This parameter is valid only when used with KeyMarker. If both parameters are specified, multipart uploads with IDs greater than the specified UploadIdMarker for the specified KeyMarker are listed.

Value range:

The value of NextUploadIdMarker in the response body of the last request

Default value:

None

EncodingType

string

No

Explanation:

Encoding type for Key in the response. If Key in the response contains control characters that are not supported by the XML 1.0 standard, you can specify this parameter to encode Key.

Value range:

url

Default value:

None. If you leave this parameter blank, encoding is not applied to Key.

Responses

Table 3 List of returned results

Parameter

Type

Description

output

*ListMultipartUploadsOutput

Explanation:

Returned results. For details, see Table 4.

err

error

Explanation:

Error messages returned by the API

Table 4 ListMultipartUploadsOutput

Parameter

Type

Description

StatusCode

int

Explanation:

HTTP status code

Value range:

A status code is a group of digits that can be 2xx (indicating successes) or 4xx or 5xx (indicating errors). It indicates the status of a response. For more information, see Status Code.

Default value:

None

RequestId

string

Explanation:

Request ID returned by the OBS server

Default value:

None

ResponseHeaders

map[string][]string

Explanation:

HTTP response headers

Default value:

None

Bucket

string

Explanation:

Bucket name

Restrictions:

  • A bucket name must be unique across all accounts and regions.
  • A bucket name:
    • Must be 3 to 63 characters long and start with a digit or letter. Lowercase letters, digits, hyphens (-), and periods (.) are allowed.
    • Cannot be formatted as an IP address.
    • Cannot start or end with a hyphen (-) or period (.).
    • Cannot contain two consecutive periods (..), for example, my..bucket.
    • Cannot contain a period (.) and a hyphen (-) adjacent to each other, for example, my-.bucket or my.-bucket.
  • If you repeatedly create buckets of the same name in the same region, no error will be reported and the bucket attributes comply with those set in the first creation request.

Value range:

The value must contain 3 to 63 characters.

KeyMarker

string

Explanation:

Object name after which multipart upload listing begins. This parameter is consistent with that set in the request.

Value range:

The value must contain 1 to 1,024 characters.

Default value:

None

UploadIdMarker

string

Explanation:

Upload ID after which the multipart upload listing begins, which is consistent with that set in the request

Value range:

The value must contain 1 to 32 characters.

Default value:

None

NextKeyMarker

string

Explanation:

Object name to start with for the next multipart upload listing request. NextKeyMarker is returned when not all the objects are listed. You can set KeyMarker to this value in the next request to list the remaining multipart uploads.

Value range:

The value must contain 1 to 1,024 characters.

Default value:

None

NextUploadIdMarker

string

Explanation:

Upload ID to start with for the next multipart upload listing request. This parameter is used together with NextKeyMarker. NextVersionIdMarker is returned when not all the objects are listed. You can set NextKeyMarker to this value in the next request to list the remaining multipart uploads.

Value range:

The value must contain 1 to 32 characters.

Default value:

None

MaxUploads

int

Explanation:

Maximum number of listed multipart uploads, which is consistent with the same parameter in the request

Restrictions:

If the specified value is greater than 1000, only 1,000 multipart uploads are returned.

Value range:

An integer from 1 to 1000

Default value:

1000

IsTruncated

bool

Explanation:

Whether all results are returned in the response

Value range:

  • true: Not all results are returned.
  • false: All results are returned.

Default value:

None

Prefix

string

Explanation:

Prefix that the object names in the multipart uploads to be listed must contain. This parameter is consistent with that set in the request.

Assume that you have the following objects: logs/day1, logs/day2, logs/day3, and ExampleObject.jpg. If you specify logs/ as the prefix, the multipart uploads of logs/day1, logs/day2, and logs/day3 will be returned. If you leave this parameter blank, all multipart uploads in the bucket will be returned.

Restrictions:

The value must contain 1 to 1,024 characters.

Default value:

None

Delimiter

string

Explanation:

A character used to group object names in multipart uploads, which is consistent with that set in the request. This parameter is often used with Prefix. If a prefix is specified, objects with the same string from the prefix to the first delimiter are grouped into one CommonPrefixes. If no prefix is specified, objects with the same string from the first character to the first delimiter are grouped into one CommonPrefixes.

Assume that a bucket has objects abcd, abcde, and bbcde in it. If delimiter is set to d and prefix is set to a, objects abcd and abcde are grouped into a CommonPrefixes with abcd as the prefix. If only delimiter is set to d, objects abcd and abcde are grouped into a CommonPrefixes with abcd as the prefix, and bbcde is grouped separately into another CommonPrefixes with bbcd as the prefix.

Value range:

The value must contain 1 to 1,024 characters.

Default value:

None

Uploads

[]Upload

Explanation:

List of multipart uploads. For details, see Table 5.

CommonPrefixes

[]string

Explanation:

List of object name prefixes grouped according to the Delimiter parameter (if specified)

Value range:

The value must contain 1 to 1,024 characters.

Default value:

None

EncodingType

string

Explanation:

Encoding type for Key in the response. If Key in the response contains control characters that are not supported by the XML 1.0 standard, you can specify this parameter to encode Key.

Value range:

url

Default value:

None. If you leave this parameter blank, encoding is not applied to Key.

Table 5 Upload

Parameter

Type

Description

Key

string

Explanation:

Object name. An object is uniquely identified by an object name in a bucket. An object name is a complete path that does not contain the bucket name.

For example, if the address for accessing the object is examplebucket.obs.ap-southeast-1.myhuaweicloud.com/folder/test.txt, the object name is folder/test.txt.

Value range:

The value must contain 1 to 1,024 characters.

Default value:

None

UploadId

string

Explanation:

Multipart upload ID, for example, 000001648453845DBB78F2340DD460D8

Value range:

The value must contain 1 to 32 characters.

Default value:

None

Initiator

Initiator

Explanation:

Initiator of the multipart upload. For details, see Table 6.

Owner

Owner

Explanation:

Account ID of the object owner. For details, see Table 7.

StorageClass

StorageClassType

Explanation:

Storage class of the object to be uploaded

Value range:

See Table 8.

Default value:

None

Initiated

time.Time

Explanation:

Time when the multipart upload is initiated

Restrictions:

The time must be in the ISO8601 format, for example, 2018-01-01T00:00:00.000Z.

Sample code: time.Now().Add(time.Duration(24) * time.Hour)

Default value:

None

Table 6 Initiator

Parameter

Type

Mandatory (Yes/No)

Description

ID

string

Yes if used as a request parameter

Explanation:

Account (domain) ID of the initiator

Value range:

To obtain the account ID, see How Do I Get My Account ID and User ID?

Default value:

None

DisplayName

string

No

Explanation:

Account name of the initiator

Restrictions:

The account name can contain 6 to 32 characters and must start with a letter. Only letters, digits, hyphens (-), and underscores (_) are allowed.

Default value:

None

Table 7 Owner

Parameter

Type

Mandatory (Yes/No)

Description

ID

string

Yes if used as a request parameter

Explanation:

Account (domain) ID of the owner

Value range:

To obtain the account ID, see How Do I Get My Account ID and User ID?

Default value:

None

Table 8 StorageClassType

Constant

Default Value

Description

StorageClassStandard

STANDARD

OBS Standard

Features low access latency and high throughput and is used for storing massive, frequently accessed (multiple times a month) or small objects (< 1 MB) requiring quick response.

StorageClassWarm

WARM

OBS Infrequent Access

Used for storing data that is semi-frequently accessed (fewer than 12 times a year) but is instantly available when needed.

StorageClassCold

COLD

OBS Archive

Used for storing rarely accessed (once a year) data.

Code Examples

This example lists all initiated multipart uploads (that have not yet been completed or aborted) in bucket examplebucket.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
package main
import (
    "fmt"
    "os"
    obs "github.com/huaweicloud/huaweicloud-sdk-go-obs/obs"
)
func main() {
    //Obtain an AK/SK pair using environment variables or import an AK/SK pair in other ways. Using hard coding may result in leakage.
    //Obtain an AK/SK pair on the management console. For details, see https://support.huaweicloud.com/intl/en-us/usermanual-ca/ca_01_0003.html.
    ak := os.Getenv("AccessKeyID")
    sk := os.Getenv("SecretAccessKey")
    // (Optional) If you use a temporary AK/SK pair and a security token to access OBS, you are advised not to use hard coding to reduce leakage risks. You can obtain an AK/SK pair using environment variables or import an AK/SK pair in other ways.
    // securityToken := os.Getenv("SecurityToken")
    // Enter the endpoint corresponding to the bucket. CN-Hong Kong is used here as an example. Replace it with the one currently in use.
    endPoint := "https://obs.ap-southeast-1.myhuaweicloud.com"
    // Create an obsClient instance.
    // If you use a temporary AK/SK pair and a security token to access OBS, use the obs.WithSecurityToken method to specify a security token when creating an instance.
    obsClient, err := obs.New(ak, sk, endPoint/*, obs.WithSecurityToken(securityToken)*/)
    if err != nil {
        fmt.Printf("Create obsClient error, errMsg: %s", err.Error())
    }
    input := &obs.ListMultipartUploadsInput{}
    // Specify a bucket name.
    input.Bucket = "examplebucket"
    // Specify the maximum number of multipart uploads that can be listed. 10 is used as an example.
    input.MaxUploads = 10
    // List initiated multipart uploads in the bucket.
    output, err := obsClient.ListMultipartUploads(input)
    if err == nil {
        fmt.Printf("List mulitpart uploads successful with bucket(%s) !\n", input.Bucket)
        for index, upload := range output.Uploads {
            fmt.Printf("Upload[%d]-OwnerId:%s, UploadId:%s, Key:%s, Initiated:%s\n",
                index, upload.Owner.ID, upload.UploadId, upload.Key, upload.Initiated)
        }
        return
    }
    fmt.Printf("List mulitpart uploads fail with bucket(%s) !\n", input.Bucket)
    if obsError, ok := err.(obs.ObsError); ok {
        fmt.Println("An ObsError was found, which means your request sent to OBS was rejected with an error response.")
        fmt.Println(obsError.Error())
    } else {
        fmt.Println("An Exception was found, which means the client encountered an internal problem when attempting to communicate with OBS, for example, the client was unable to access the network.")
        fmt.Println(err)
    }
}