Introduction
The IBM Cloud® Object Storage API is a REST-based API for reading and writing objects. It uses IBM Cloud® Identity and Access Management for authentication/authorization, and supports a subset of the S3 API for easy migration of applications to IBM Cloud.
For details about using Object Storage, see the IBM Cloud docs.
Object Storage is a global service. The location of data is determined by the region where a bucket is created, and subsequent requests to that bucket must be sent to the same corresponding endpoint. The examples shown here assume that requests are sent to the US South region. For more details about selecting endpoints Object Storage, see the IBM Cloud docs.
Java developers can use this SDK to interact with Object Storage. The SDK is a fork of the official AWS SDK for Java. For more information, see the COS SDK for Java API Reference.
JavaScript developers can use this SDK to interact with Object Storage. The SDK is a fork of the official AWS SDK for JavaScript. For more information, see the COS SDK for JavaScript API Reference.
The SDK is supported on Node versions 4.x and later.
Python developers can use this SDK to interact with Object Storage. The SDK is a fork of the boto3 library. For more information, see the COS SDK for Python API Reference.
Go developers can use this SDK to interact with Object Storage. The SDK is a fork of the official AWS SDK for Go. For more information, see the COS SDK for Go API Reference.
The SDK supports Go versions 1.10 - 1.12.
The code examples on this tab use the client library that is provided for Java.
Maven
<dependency>
<groupId>com.ibm.cos</groupId>
<artifactId>ibm-cos-java-sdk</artifactId>
</dependency>
GitHub
The code examples on this tab use the client library that is provided for Node.js.
Installation
npm install ibm-cos-sdk
GitHub
The code examples on this tab use the client library that is provided for Python.
Installation
pip install --upgrade ibm-cos-sdk
GitHub
The code examples on this tab use the client library that is provided for Go.
go get -u github.com/IBM/ibm-cos-sdk-go
GitHub
Error handling
The Object Storage service uses standard HTTP response codes to indicate if a method completes successfully. A 200
response always indicates success. A 400
type response is some sort of failure, and a 500
type response usually indicates an internal system error.
For more details about response codes Object Storage, see the IBM Cloud docs.
Methods
List buckets in a service instance
This operation lists all buckets within the specified service instance, regardless of location. Note that while any endpoint may be used to list all buckets, any operations that target a specific bucket must use the appropriate endpoint for that bucket's location.
GET /
Request
Custom Headers
This header references the service instance that contains buckets to list. This value can be either the full Cloud Resource Name (CRN) or just the GUID segment that identifies the service instance.
Example:
d6f76k03-6k4f-4a82-n165-697654o63903
Query Parameters
If supplied, the returned listing will also include the provisioning code (
LocationConstraint
) for each bucket. This allows for inferring a bucket's location and associated endpoint.Possible values: allows empty value
curl -X "GET" "https://s3.$REGION.cloud-object-storage.appdomain.cloud/" -H "Authorization: Bearer $IAM_TOKEN" -H "ibm-service-instance-id: $SERVICE_INSTANCE_ID"
curl -X "GET" "https://s3.$REGION.cloud-object-storage.appdomain.cloud?extended" -H "Authorization: Bearer $IAM_TOKEN" -H "ibm-service-instance-id: $SERVICE_INSTANCE_ID"
public static void getBuckets() { System.out.println("Retrieving list of buckets"); final List<Bucket> bucketList = _cos.listBuckets(); for (final Bucket bucket : bucketList) { System.out.printf("Bucket Name: %s\n", bucket.getName()); } }
def get_buckets(): print("Retrieving list of buckets") try: buckets = cos.buckets.all() for bucket in buckets: print("Bucket Name: {0}".format(bucket.name)) except ClientError as be: print("CLIENT ERROR: {0}\n".format(be)) except Exception as e: print("Unable to retrieve list buckets: {0}".format(e))
function getBuckets() { console.log('Retrieving list of buckets'); return cos.listBuckets() .promise() .then((data) => { if (data.Buckets != null) { for (var i = 0; i < data.Buckets.length; i++) { console.log(`Bucket Name: ${data.Buckets[i].Name}`); } } }) .catch((e) => { console.error(`ERROR: ${e.code} - ${e.message}\n`); }); }
func main() { // Create client sess := session.Must(session.NewSession()) client := s3.New(sess, conf) // Call Function d, _ := client.ListBuckets(&s3.ListBucketsInput{}) fmt.Println(d) }
Response
This operation returns a list of all buckets within a service instance.
Service instance ID.
Example:
d6f76k03-6k4f-4a82-n165-697654o63903
Service instance ID.
Example:
d6f76k03-6k4f-4a82-n165-697654o63903
owner
Bucket name.
Example:
myBucket
Timestamp of bucket creation.
Example:
2019-04-29T20:49:22.374Z
buckets
Status Code
Success
Success
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <ListAllMyBucketsResult> <Owner> <ID>{account-id}</ID> <DisplayName>{account-id}</DisplayName> </Owner> <Buckets> <Bucket> <Name>bucket-27200-lwx4cfvcue</Name> <CreationDate>2016-08-18T14:21:36.593Z</CreationDate> </Bucket> <Bucket> <Name>bucket-27590-drqmydpfdv</Name> <CreationDate>2016-08-18T14:22:32.366Z</CreationDate> </Bucket> <Bucket> <Name>bucket-27852-290jtb0n2y</Name> <CreationDate>2016-08-18T14:23:03.141Z</CreationDate> </Bucket> <Bucket> <Name>bucket-28731-k0o1gde2rm</Name> <CreationDate>2016-08-18T14:25:09.599Z</CreationDate> </Bucket> </Buckets> </ListAllMyBucketsResult>
Success
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <ListAllMyBucketsResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/"> <Owner> <ID>{account-id}</ID> <DisplayName>{account-id}</DisplayName> </Owner> <IsTruncated>false</IsTruncated> <MaxKeys>1000</MaxKeys> <Prefix/> <Marker/> <Buckets> <Bucket> <Name>bucket-27200-lwx4cfvcue</Name> <CreationDate>2016-08-18T14:21:36.593Z</CreationDate> <LocationConstraint>us-south-standard</LocationConstraint> <CreationTemplateId>dca204eb-72b5-4e2a-a142-808d2a5c2a87</CreationTemplateId> </Bucket> <Bucket> <Name>bucket-27590-drqmydpfdv</Name> <CreationDate>2016-08-18T14:22:32.366Z</CreationDate> <LocationConstraint>seo01-standard</LocationConstraint> <CreationTemplateId>dca204eb-72b5-4e2a-a142-808d2a5c2a87</CreationTemplateId> </Bucket> <Bucket> <Name>bucket-27852-290jtb0n2y</Name> <CreationDate>2016-08-18T14:23:03.141Z</CreationDate> <LocationConstraint>eu-standard</LocationConstraint> <CreationTemplateId>dca204eb-72b5-4e2a-a142-808d2a5c2a87</CreationTemplateId> </Bucket> <Bucket> <Name>bucket-28731-k0o1gde2rm</Name> <CreationDate>2016-08-18T14:25:09.599Z</CreationDate> <LocationConstraint>us-cold</LocationConstraint> <CreationTemplateId>dca204eb-72b5-4e2a-a142-808d2a5c2a87</CreationTemplateId> </Bucket> </Buckets> </ListAllMyBucketsResult>
Create a new bucket
To create a bucket, you must create a COS service instance, and create an API key or HMAC credentials to authenticate requests.
Bucket names must be globally unique and DNS-compliant; names between 3 and 63 characters long must be made of lowercase letters, numbers, and dashes. Bucket names must begin and end with a lowercase letter or number. Bucket names resembling IP addresses are not allowed. Bucket names must be unique because all buckets in the public cloud share a global namespace, allowing access to buckets without the need to provide any service instance or account information. It is not possible to create a bucket with a name beginning with cosv1-
or account-
as these prefixes are reserved by the system.
Buckets are created in the location specified in the endpoint used to make the request. Once a bucket is created, it can be accessed at that location using any of the three networks: public, private, or direct. Any requests targeting an existing bucket using an endpoint with an incorrect location will result in a 404 NoSuchKey
error.
All data in IBM Cloud Object Storage is encrypted at rest. This technology individually encrypts each object by using per-object generated keys. These keys are secured and reliably stored by using the same Information Dispersal Algorithms that protect object data by using an All-or-Nothing Transform (AONT). Key data is impossible to recover, even if individual nodes or hard disks are compromised. If it is necessary to control the encryption keys used, an IBM Key Protect or Hyper Protect Crypto Services root key CRN can be provided during bucket creation.
It is possible to create a bucket with a "storage class" that alters the way storage charges are incurred based on frequency of access. This can be helpful when dealing with "cool" data that might need to be accessed without the delay of restoring from an archive, but is unlikely to be accessed frequently. A provisioning code can be passed in the S3 API LocationConstraint
parameter to specify the storage class of a new bucket. A storage class can not be altered after a bucket is created.
The S3 API concept of a "bucket owner" is not an individual user, but instead is considered to be the Service Instance associated with the bucket.
PUT /{Bucket}
Request
Custom Headers
This header references the service instance where the bucket will be created and to which data usage will be billed. It is required when using IAM tokens, but it should not be used when using hmac credentials. This value can be either the full Cloud Resource Name (CRN) or just the GUID segment that identifies the service instance.
Example:
d6f76k03-6k4f-4a82-n165-697654o63903
The algorithm and key size used to for the managed encryption root key. Required if
ibm-sse-kp-customer-root-key-crn
is also present.Allowable values: [
AES256
]Example:
AES256
The CRN of the root key used to encrypt the bucket. Required if
ibm-sse-kp-encryption-algorithm
is also present.Example:
crn:v1:bluemix:public:kms:us-south:a/f047b55a3362ac06afad8a3f2f5586ea:12e8c9c2-a162-472d-b7d6-8b9a86b815a6:key:02fd6835-6001-4482-a892-13bd2085f75d
The canned ACL to apply to the bucket. This header should not be used - instead create an IAM policy to grant public access to a bucket.
Allowable values: [
private
,public-read
]
Path Parameters
The name of the bucket to create.
Example:
my-new-bucket
Allowable values: [
us-standard
,us-cold
]
curl -X "PUT" "https://s3.us-south.cloud-object-storage.appdomain.cloud/$NEW_BUCKET" -H "Authorization: Bearer $IAM_TOKEN" -H "ibm-service-instance-id: $SERVICE_INSTANCE_ID"
curl -X "PUT" "https://s3.us-south.cloud-object-storage.appdomain.cloud/$NEW_BUCKET" -H "Authorization: Bearer $IAM_TOKEN" -H "ibm-service-instance-id: $SERVICE_INSTANCE_ID" -H "ibm-sse-kp-encryption-algorithm: AES256" -H "ibm-sse-kp-customer-root-key-crn: $KP_ROOT_KEY_CRN" -d "<CreateBucketConfiguration> <LocationConstraint>us-south-smart</LocationConstraint> </CreateBucketConfiguration>"
public static void createBucket(String bucketName) { System.out.printf("Creating new bucket: %s\n", bucketName); _cos.createBucket(bucketName); System.out.printf("Bucket: %s created!\n", bucketName); }
def create_bucket(bucket_name): print("Creating new bucket: {0}".format(bucket_name)) try: cos.Bucket(bucket_name).create( CreateBucketConfiguration={ "LocationConstraint":COS_BUCKET_LOCATION } ) print("Bucket: {0} created!".format(bucket_name)) except ClientError as be: print("CLIENT ERROR: {0}\n".format(be)) except Exception as e: print("Unable to create bucket: {0}".format(e))
function createBucket(bucketName) { console.log(`Creating new bucket: ${bucketName}`); return cos.createBucket({ Bucket: bucketName, CreateBucketConfiguration: { LocationConstraint: 'us-standard' }, }).promise() .then((() => { console.log(`Bucket: ${bucketName} created!`); })) .catch((e) => { console.error(`ERROR: ${e.code} - ${e.message}\n`); }); }
func main() { // Create client sess := session.Must(session.NewSession()) client := s3.New(sess, conf) // Bucket Names newBucket := "<NEW_BUCKET_NAME>" newColdBucket := "<NEW_COLD_BUCKET_NAME>" input := &s3.CreateBucketInput{ Bucket: aws.String(newBucket), } client.CreateBucket(input) input2 := &s3.CreateBucketInput{ Bucket: aws.String(newColdBucket), CreateBucketConfiguration: &s3.CreateBucketConfiguration{ LocationConstraint: aws.String("us-cold"), }, } client.CreateBucket(input2) d, _ := client.ListBuckets(&s3.ListBucketsInput{}) fmt.Println(d) }
Delete a bucket
Only empty buckets may be deleted. A bucket name is returned to the available namespace approximately 10 minutes after deletion.
DELETE /{Bucket}
Request
Path Parameters
The name of the bucket to delete.
curl -X "DELETE" "https://s3.us-south.cloud-object-storage.appdomain.cloud/$BUCKET" -H "Authorization: Bearer $IAM_TOKEN" \
public static void deleteBucket(String bucketName) { System.out.printf("Deleting bucket: %s\n", bucketName); _cos.deleteBucket(bucketName); System.out.printf("Bucket: %s deleted!\n", bucketName); }
def delete_bucket(bucket_name): print("Deleting bucket: {0}".format(bucket_name)) try: cos.Bucket(bucket_name).delete() print("Bucket: {0} deleted!".format(bucket_name)) except ClientError as be: print("CLIENT ERROR: {0}\n".format(be)) except Exception as e: print("Unable to delete bucket: {0}".format(e))
function deleteBucket(bucketName) { console.log(`Deleting bucket: ${bucketName}`); return cos.deleteBucket({ Bucket: bucketName }).promise() .then(() => { console.log(`Bucket: ${bucketName} deleted!`); }) .catch((e) => { console.error(`ERROR: ${e.code} - ${e.message}\n`); }); }
func main() { // Bucket Name bucket := "<BUCKET_NAME>" // Create client sess := session.Must(session.NewSession()) client := s3.New(sess, conf) input := &s3.DeleteBucketInput{ Bucket: aws.String(bucket), } d, _ := client.DeleteBucket(input) fmt.Println(d) }
Read a bucket's headers
This request is useful for checking whether a bucket has Key Protect enabled.
HEAD /{Bucket}
Request
Path Parameters
The name of the bucket being checked. The bucket must exist in the location specified by the endpoint for the request to succeed.
curl -X "GET" "https://s3.$REGION.cloud-object-storage.appdomain.cloud/$NEW_BUCKET" -H "Authorization: Bearer $IAM_TOKEN" -H "ibm-service-instance-id: $SERVICE_INSTANCE_ID"
public HeadBucketRequest(String bucketName)
response = client.head_bucket( Bucket='string', ExpectedBucketOwner='string' )
var params = { Bucket: 'STRING_VALUE' /* required */ }; s3.headBucket(params, function(err, data) { if (err) console.log(err, err.stack); // an error occurred else console.log(data); // successful response });
func main() { // Bucket Name bucket := "<BUCKET_NAME>" sess := session.Must(session.NewSession()) client := s3.New(sess, conf) d, _ := client.HeadBucket(bucket) fmt.Println(d) }
List objects in a bucket (v1)
Returns some or all (up to 1,000) of the objects in a bucket. You can use the request parameters as selection criteria to return a subset of the objects in a bucket. A 200 OK
response can contain valid or invalid XML. Make sure to design your application to parse the contents of the response and handle it appropriately. This version (v1) uses a marker
parameter to list objects starting with a given object. Version 2 of this API provides a continuation token instead, making it a bit more straightforward to chain listing requests for buckets with large numbers of objects.
GET /{Bucket}
Request
Path Parameters
The name of the bucket to be listed.
Query Parameters
A delimiter is a character you use to group keys.
Requests COS to url-encode the object keys in the response. Object keys may contain any Unicode character; however, XML 1.0 parser cannot parse some characters, such as characters with an ASCII value from 0 to 10. For characters that are not supported in XML 1.0, you can add this parameter to request that COS encodes the keys in the response.
Allowable values: [
url
]Specifies the key to start with when listing objects in a bucket.
Sets the maximum number of keys returned in the response. By default the API returns up to 1,000 key names. The response might contain fewer keys but will never contain more.
Limits the response to keys that begin with the specified prefix.
curl -X "GET" "https://s3.$REGION.cloud-object-storage.appdomain.cloud/$BUCKET" -H "Authorization: Bearer $IAM_TOKEN"
public static void getBucketContents(String bucketName) { System.out.printf("Retrieving bucket contents from: %s\n", bucketName); ObjectListing objectListing = _cos.listObjects(new ListObjectsRequest().withBucketName(bucketName)); for (S3ObjectSummary objectSummary : objectListing.getObjectSummaries()) { System.out.printf("Item: %s (%s bytes)\n", objectSummary.getKey(), objectSummary.getSize()); } }
def get_bucket_contents(bucket_name): print("Retrieving bucket contents from: {0}".format(bucket_name)) try: files = cos.Bucket(bucket_name).objects.all() for file in files: print("Item: {0} ({1} bytes).".format(file.key, file.size)) except ClientError as be: print("CLIENT ERROR: {0}\n".format(be)) except Exception as e: print("Unable to retrieve bucket contents: {0}".format(e))
function getBucketContents(bucketName) { console.log(`Retrieving bucket contents from: ${bucketName}`); return cos.listObjects( {Bucket: bucketName}, ).promise() .then((data) => { if (data != null && data.Contents != null) { for (var i = 0; i < data.Contents.length; i++) { var itemKey = data.Contents[i].Key; var itemSize = data.Contents[i].Size; console.log(`Item: ${itemKey} (${itemSize} bytes).`) } } }) .catch((e) => { console.error(`ERROR: ${e.code} - ${e.message}\n`); }); }
func main() { // Create client sess := session.Must(session.NewSession()) client := s3.New(sess, conf) // Bucket Name Bucket := "<BUCKET_NAME>" // Call Function Input := &s3.ListObjectsInput{ Bucket: aws.String(Bucket), } l, e := client.ListObjects(Input) fmt.Println(l) fmt.Println(e) // prints "<nil>" }
Response
A flag that indicates whether IBM COS returned all of the results that satisfied the search criteria.
Indicates where in the bucket listing begins. Marker is included in the response if it was sent with the request.
When response is truncated (the
IsTruncated
element value in the response is true), you can use the key name in this field as marker in the subsequent request to get next set of objects. IBM COS lists objects in alphabetical order.Note: This element is returned only if you have delimiter request parameter specified. If response does not include the
NextMarker
and it is truncated, you can use the value of the last key in the response as the marker in the subsequent request to get the next set of object keys.Metadata about each object returned.
The bucket name.
Keys that begin with the indicated prefix.
Causes keys that contain the same string between the prefix and the first occurrence of the delimiter to be rolled up into a single result element in the
CommonPrefixes
collection. These rolled-up keys are not returned elsewhere in the response. Each rolled-up result counts as only one return against theMaxKeys
value.The maximum number of keys returned in the response body.
All of the keys rolled up in a common prefix count as a single return when calculating the number of returns.
A response can contain CommonPrefixes only if you specify a delimiter.
CommonPrefixes contains all (if there are any) keys between Prefix and the next occurrence of the string specified by the delimiter.
CommonPrefixes lists keys that act like subdirectories in the directory specified by Prefix.
For example, if the prefix is notes/ and the delimiter is a slash (/) as in notes/summer/july, the common prefix is notes/summer/. All of the keys that roll up into a common prefix count as a single return when calculating the number of returns.
Encoding type used by IBM COS to encode object keys in the response.
Possible values: [
url
]
Status Code
Success
NoSuchBucket
Success
<ListBucketResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/"> <Name>apiary</Name> <Prefix/> <Marker/> <MaxKeys>1000</MaxKeys> <Delimiter/> <IsTruncated>false</IsTruncated> <Contents> <Key>drone-bee</Key> <LastModified>2016-08-25T17:38:38.549Z</LastModified> <ETag>"0cbc6611f5540bd0809a388dc95a615b"</ETag> <Size>4</Size> <Owner> <ID>{account-id}</ID> <DisplayName>{account-id}</DisplayName> </Owner> <StorageClass>STANDARD</StorageClass> </Contents> <Contents> <Key>soldier-bee</Key> <LastModified>2016-08-25T17:49:06.006Z</LastModified> <ETag>"37d4c94839ee181a2224d6242176c4b5"</ETag> <Size>11</Size> <Owner> <ID>{account-id}</ID> <DisplayName>{account-id}</DisplayName> </Owner> <StorageClass>STANDARD</StorageClass> </Contents> <Contents> <Key>worker-bee</Key> <LastModified>2016-08-25T17:46:53.288Z</LastModified> <ETag>"d34d8aada2996fc42e6948b926513907"</ETag> <Size>467</Size> <Owner> <ID>{account-id}</ID> <DisplayName>{account-id}</DisplayName> </Owner> <StorageClass>STANDARD</StorageClass> </Contents> </ListBucketResult>
List objects in a bucket (v2)
Returns some or all (up to 1,000) of the objects in a bucket. You can use the request parameters as selection criteria to return a subset of the objects in a bucket. A 200 OK
response can contain valid or invalid XML. Make sure to design your application to parse the contents of the response and handle it appropriately.
GET /{Bucket}?list-type=2
Request
Path Parameters
Bucket name to list.
Query Parameters
Allowable values: [
2
]A delimiter is a character you use to group keys.
Encoding type used by IBM COS to encode object keys in the response.
Allowable values: [
url
]Sets the maximum number of keys returned in the response. By default the API returns up to 1,000 key names. The response might contain fewer keys but will never contain more.
Limits the response to keys that begin with the specified prefix.
ContinuationToken
indicates IBM COS that the list is being continued on this bucket with a token. ContinuationToken is obfuscated and is not a real key.The owner field (Service Instance ID) is not present in listV2 by default, if you want to return the Service Instance ID with each key in the result, then set the fetch owner field to true.
StartAfter
is where you want IBM COS to start listing from. IBM COS starts listing after this specified key.StartAfter
can be any key in the bucket.
curl -X "GET" "https://s3.$REGION.cloud-object-storage.appdomain.cloud/$BUCKET?list-type=2" -H "Authorization: Bearer $IAM_TOKEN"
def get_bucket_contents_v2(bucket_name, max_keys): print("Retrieving bucket contents from: {0}".format(bucket_name)) try: # create client object cos_cli = ibm_boto3.client("s3", ibm_api_key_id=COS_API_KEY_ID, ibm_service_instance_id=COS_SERVICE_CRN, config=Config(signature_version="oauth"), endpoint_url=COS_ENDPOINT) more_results = True next_token = "" while (more_results): response = cos_cli.list_objects_v2(Bucket=bucket_name, MaxKeys=max_keys, ContinuationToken=next_token) files = response["Contents"] for file in files: print("Item: {0} ({1} bytes).".format(file["Key"], file["Size"])) if (response["IsTruncated"]): next_token = response["NextContinuationToken"] print("...More results in next batch!\n") else: more_results = False next_token = "" except ClientError as be: print("CLIENT ERROR: {0}\n".format(be)) except Exception as e: print("Unable to retrieve bucket contents: {0}".format(e))
var params = { Bucket: 'STRING_VALUE', /* required */ ContinuationToken: 'STRING_VALUE', Delimiter: 'STRING_VALUE', EncodingType: url, FetchOwner: true || false, MaxKeys: 'NUMBER_VALUE', Prefix: 'STRING_VALUE', StartAfter: 'STRING_VALUE' }; s3.listObjectsV2(params, function(err, data) { if (err) console.log(err, err.stack); // an error occurred else console.log(data); // successful response });
func main() { // Create client sess := session.Must(session.NewSession()) client := s3.New(sess, conf) // Bucket Name Bucket := "<BUCKET_NAME>" // Call Function Input := &s3.ListObjectsV2Input{ Bucket: aws.String(Bucket), } l, e := client.ListObjectsV2(Input) fmt.Println(l) fmt.Println(e) // prints "<nil>" }
Response
Set to false if all of the results were returned. Set to true if more keys are available to return. If the number of results exceeds that specified by MaxKeys, all of the results might not be returned.
Metadata about each object returned.
The bucket name.
When using this API with an access point, you must direct requests to the access point hostname. The access point hostname takes the form AccessPointName-AccountId.s3-accesspoint.Region.amazonaws.com. When using this operation with an access point through the AWS SDKs, you provide the access point ARN in place of the bucket name. For more information about access point ARNs, see Using Access Points in the Amazon Simple Storage Service Developer Guide.
When using this API with IBM COS on Outposts, you must direct requests to the S3 on Outposts hostname. The S3 on Outposts hostname takes the form AccessPointName-AccountId.outpostID.s3-outposts.Region.amazonaws.com. When using this operation using S3 on Outposts through the AWS SDKs, you provide the Outposts bucket ARN in place of the bucket name. For more information about S3 on Outposts ARNs, see Using S3 on Outposts in the Amazon Simple Storage Service Developer Guide.
Keys that begin with the indicated prefix.
Causes keys that contain the same string between the prefix and the first occurrence of the delimiter to be rolled up into a single result element in the CommonPrefixes collection. These rolled-up keys are not returned elsewhere in the response. Each rolled-up result counts as only one return against the
MaxKeys
value.Sets the maximum number of keys returned in the response. By default the API returns up to 1,000 key names. The response might contain fewer keys but will never contain more.
All of the keys rolled up into a common prefix count as a single return when calculating the number of returns.
A response can contain `CommonPrefixes` only if you specify a delimiter.
`CommonPrefixes` contains all (if there are any) keys between `Prefix` and the next occurrence of the string specified by a delimiter.
`CommonPrefixes` lists keys that act like subdirectories in the directory specified by `Prefix`.
For example, if the prefix is `notes/` and the delimiter is a slash (`/`) as in `notes/summer/july`, the common prefix is `notes/summer/`. All of the keys that roll up into a common prefix count as a single return when calculating the number of returns.
Encoding type used by IBM COS to encode object keys in the response. If you specify
encoding-type
request parameter, IBM COS includes this element in the response, and returns encoded key name values in the following response elements:Delimiter
,KeyMarker
,Prefix
,NextKeyMarker
,Key
.Possible values: [
url
]KeyCount is the number of keys returned with this request. KeyCount will always be less than equals to MaxKeys field. Say you ask for 50 keys, your result will include less than equals 50 keys
If ContinuationToken was sent with the request, it is included in the response.
NextContinuationToken
is sent whenisTruncated
is true, which means there are more keys in the bucket that can be listed. The next list requests to IBM COS can be continued with thisNextContinuationToken
.NextContinuationToken
is obfuscated and is not a real keyIf StartAfter was sent with the request, it is included in the response.
Status Code
Success
NoSuchBucket
Success
<ListBucketResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/"> <Name>apiary</Name> <Prefix/> <ContinuationToken>1dPe45g5uuxjyASPegLq80sQsZKL5OB2by4Iz_7YGR5NjiOENBPZXqvKJN6_PgKGVzZYTlws7qqdWaMklzb8HX2iDxxl72ane3rUFQrvNMeIih49MZ4APUjrAuYI83KxSMmfKHGZyKallFkD5N6PwKg</ContinuationToken> <NextContinuationToken>1a8j20CqowRrM4epIQ7fTBuyPZWZUeA8Epog16wYu9KhAPNoYkWQYhGURsIQbll1lP7c-OO-V5Vyzu6mogiakC4NSwlK4LyRDdHQgY-yPH4wMB76MfQR61VyxI4TJLxIWTPSZA0nmQQWcuV2mE4jiDA</NextContinuationToken> <KeyCount>1</KeyCount> <MaxKeys>1</MaxKeys> <Delimiter/> <IsTruncated>true</IsTruncated> <Contents> <Key>soldier-bee</Key> <LastModified>2016-08-25T17:49:06.006Z</LastModified> <ETag>"37d4c94839ee181a2224d6242176c4b5"</ETag> <Size>11</Size> <StorageClass>STANDARD</StorageClass> </Contents> </ListBucketResult>
Create (upload) an object
Adds an object to a bucket using a single request. IBM COS never adds partial objects; if you receive a success response, IBM COS added the entire object to the bucket. IBM COS is a distributed system. If it receives multiple write requests for the same object simultaneously, it overwrites all but the last object written. IBM COS does not provide object locking; if you need this, make sure to build it into your application layer.
All objects written to IBM COS are encrypted by default using SecureSlice. If you require possession of encryption keys, you can use Key Protect or SSE-C.
To ensure that data is not corrupted traversing the network, use the Content-MD5
header. When you use this header, IBM COS checks the object against the provided MD5 value and, if they do not match, returns an error. Additionally, you can calculate the MD5 while putting an object to IBM COS and compare the returned ETag to the calculated MD5 value. The Content-MD5
header is required for any request to upload an object with a retention period configured using Immutable Object Storage.
Larger objects (greater than 100 MiB) may benefit from breaking the object into multiple parts and uploading the parts in parallel. For more information, see the Multipart uploads methods.
PUT /{Bucket}/{Key}
Request
Custom Headers
The canned ACL to apply to the object.
Allowable values: [
private
,public-read
]Upload the object only if its entity tag (ETag) is the same as the one specified, otherwise return a 412 (precondition failed).
Upload the object only if its entity tag (ETag) is different from the one specified, otherwise return a 412 (precondition failed).
Upload the object only if it has not been modified since the specified time, otherwise return a 412 (precondition failed).
Can be used to specify caching behavior along the request/reply chain. For more information, see RFC 2616.
Specifies presentational information for the object. For more information, see RFC 2616.
Specifies what content encodings have been applied to the object and thus what decoding mechanisms must be applied to obtain the media-type referenced by the Content-Type header field. For more information, see RFC 2616.
The language the content is in.
Size of the body in bytes. This parameter is useful when the size of the body cannot be determined automatically. For more information, see RFC 2616.
The base64-encoded 128-bit MD5 digest of the payload (just the request body without the headers) according to RFC 1864. This header can be used as a message integrity check to verify that the data is the same data that was originally sent. Although it is optional, it is recommended to use the Content-MD5 mechanism as an end-to-end integrity check.
A standard MIME type describing the format of the contents. For more information, see RFC 2616.
The date and time at which the object is no longer cacheable. For more information, RFC 2616.
The server-side encryption algorithm used when storing this object in IBM COS (
AES256
).Allowable values: [
AES256
]If the bucket is configured as a website, redirects requests for this object to another object in the same bucket or to an external URL.
Specifies the algorithm to use to when encrypting the object (for example,
AES256
).Specifies the customer-provided encryption key for IBM COS to use in encrypting data. This value is used to store the object and then it is discarded; IBM COS does not store the encryption key. The key must be appropriate for use with the algorithm specified in the
x-amz-server-side-encryption-customer-algorithm
header.Specifies the 128-bit MD5 digest of the encryption key according to RFC 1321. IBM COS uses this header for a message integrity check to ensure that the encryption key was transmitted without error.
A set of tags for the object. The tags must be encoded as URL duery parameters (For example,
SomeKey=SomeValue
).
Path Parameters
The bucket that will hold the object.
Object key for which the PUT operation was initiated.
Possible values: length ≥ 1
Object data.
curl -X "PUT" "https://(endpoint)/(bucket-name)/(object-key)" -H "Authorization: bearer (token)" -H "Content-Type: (content-type)" -d "(object-contents)"
cos.putObject( "sample", // the name of the destination bucket "myfile", // the object key new File("/home/user/test.txt") // the file name and path of the object to be uploaded );
cos.Object(bucket_name, item_name).put(Body=filelike_object)
function createTextFile(bucketName, itemName, fileText) { console.log(`Creating new item: ${itemName}`); return cos.putObject({ Bucket: bucketName, Key: itemName, Body: fileText }).promise() .then(() => { console.log(`Item: ${itemName} created!`); }) .catch((e) => { console.error(`ERROR: ${e.code} - ${e.message}\n`); }); }
func main() { // Create client sess := session.Must(session.NewSession()) client := s3.New(sess, conf) // Variables and random content to sample, replace when appropriate bucketName := "<BUCKET_NAME>" key := "<OBJECT_KEY>" content := bytes.NewReader([]byte("<CONTENT>")) input := s3.PutObjectInput{ Bucket: aws.String(bucketName), Key: aws.String(key), Body: content, } // Call Function to upload (Put) an object result, _ := client.PutObject(&input) fmt.Println(result) }
Read (download) an object
Retrieves objects from IBM COS. If the object you are retrieving has been archived, before you can retrieve the object you must first restore a copy. Otherwise, this operation returns an InvalidObjectStateError
error. If you encrypt an object by using server-side encryption with customer-provided encryption keys (SSE-C) when you store the object in IBM COS, then when you GET the object, you must use the following headers:
x-amz-server-side-encryption-customer-algorithm
x-amz-server-side-encryption-customer-key
x-amz-server-side-encryption-customer-key-MD5
GET /{Bucket}/{Key}
Request
Custom Headers
Returns the object only if its entity tag (ETag) is the same as the one specified, otherwise returns a 412 (precondition failed).
Returns the object only if it has been modified since the specified time, otherwise returns a 304 (not modified).
Returns the object only if its entity tag (ETag) is different from the one specified, otherwise returns a 304 (not modified).
Returns the object only if it has not been modified since the specified time, otherwise return a 412 (precondition failed).'
Downloads the specified range bytes of an object. For more information about the HTTP Range header, see RFC 2516.
Specifies the algorithm to use to when encrypting the object (for example, AES256).
Specifies the customer-provided encryption key for IBM COS to use in encrypting data. This value is used to store the object and then it is discarded; IBM COS does not store the encryption key. The key must be appropriate for use with the algorithm specified in the
x-amz-server-side-encryption-customer-algorithm
header.Specifies the 128-bit MD5 digest of the encryption key according to RFC 1321. IBM COS uses this header for a message integrity check to ensure that the encryption key was transmitted without error.
Path Parameters
The bucket containing the object.
Key of the object to get.
Possible values: length ≥ 1
Query Parameters
Sets the
Cache-Control
header of the response.Sets the
Content-Disposition
header of the responseSets the
Content-Encoding
header of the response.Sets the
Content-Language
header of the response.Sets the
Content-Type
header of the response.Sets the
Expires
header of the response.Part number of the object being read. This is a positive integer between 1 and 10,000. Effectively performs a "ranged" GET request for the part specified. Useful for downloading just a part of an object.
Response
Object data.
A map of metadata to store with the object in S3.
Metadata
Status Code
Success
NoSuchKey
{ "AcceptRanges": "bytes", "ContentLength": "10", "ContentRange": "bytes 0-9/43", "ContentType": "text/plain", "ETag": "\"0d94420ffd0bc68cd3d152506b97a9cc\"", "LastModified": "Thu, 09 Oct 2014 22:57:28 GMT", "Metadata": {}, "VersionId": "null" }
Read object metadata
The HEAD operation retrieves metadata from an object without returning the object itself. This operation is useful if you're only interested in an object's metadata or it's existence.
HEAD /{Bucket}/{Key}
Request
Custom Headers
Return the object only if its entity tag (ETag) is the same as the one specified, otherwise return a 412 (precondition failed).
Return the object only if it has been modified since the specified time, otherwise return a 304 (not modified).
Return the object only if its entity tag (ETag) is different from the one specified, otherwise return a 304 (not modified).
Return the object only if it has not been modified since the specified time, otherwise return a 412 (precondition failed).
Downloads the specified range bytes of an object. For more information about the HTTP Range header, see RFC 2516.
Specifies the algorithm to use to when encrypting the object (for example, AES256).
Specifies the customer-provided encryption key for IBM COS to use in encrypting data. This value is used to store the object and then it is discarded; IBM COS does not store the encryption key. The key must be appropriate for use with the algorithm specified in the
x-amz-server-side-encryption-customer-algorithm
header.Specifies the 128-bit MD5 digest of the encryption key according to RFC 1321. IBM COS uses this header for a message integrity check to ensure that the encryption key was transmitted without error.
Path Parameters
The bucket containing the object.
The object key.
Possible values: length ≥ 1
Query Parameters
Part number of the object being read. This is a positive integer between 1 and 10,000. Effectively performs a "ranged" HEAD request for the part specified. Useful querying about the size of the part and the number of parts in this object.
Delete an object
Permantently deletes an object. This operation is final - there is no way to recover a deleted object. Data stored in IBM COS is erasure coded and distributed to multiple individual storage devices in multiple data centers. When data is deleted, various mechanisms exist which prevent recovery or reconstruction of the deleted objects.
Deletion of an object undergoes various stages. First, the metadata is marked to indicate the object is deleted, then, the data is removed. Eventually, deleted metadata is overwritten by a process of compaction and the deleted data blocks are overwritten with new data in the course of normal operations. As soon as the metadata is marked deleted, it is not possible to read an object remotely. IBM's provider-managed encryption and erasure coding prevents data (both before and after deletion) from being accessible from within individual data centers.
DELETE /{Bucket}/{Key}
Request
Custom Headers
Specifies the source object for the copy operation.
Possible values: Value must match regular expression
\/.+\/.+
The canned ACL to apply to the object.
Allowable values: [
private
,public-read
]Specifies caching behavior along the request/reply chain.
Specifies presentational information for the object.
Specifies what content encodings have been applied to the object and thus what decoding mechanisms must be applied to obtain the media-type referenced by the Content-Type header field. For more information, see RFC 2616.
The language the content is in.
A standard MIME type describing the format of the contents. For more information, see RFC 2616.
Copies the object if its entity tag (ETag) matches the specified tag.
Copies the object if it has been modified since the specified time.
Copies the object if its entity tag (ETag) is different than the specified ETag.
Copies the object if it hasn't been modified since the specified time.
The date and time at which the object is no longer cacheable. For more information, RFC 2616.
Specifies whether the metadata is copied from the source object or replaced with metadata provided in the request.
Allowable values: [
COPY
,REPLACE
]Specifies whether the object tag-set are copied from the source object or replaced with tag-set provided in the request.
Allowable values: [
COPY
,REPLACE
]The server-side encryption algorithm used when storing this object.
Allowable values: [
AES256
]If the bucket is configured as a website, redirects requests for this object to another object in the same bucket or to an external URL.
Specifies the algorithm to use to when encrypting the object (for example, AES256).
Specifies the customer-provided encryption key for use in encrypting data.
Specifies the 128-bit MD5 digest of the encryption key according to RFC 1321. Used as a message integrity check to ensure that the encryption key was transmitted without error.
Specifies the algorithm to use when decrypting the source object (for example, AES256).
Specifies the customer-provided encryption key for IBM COS to use to decrypt the source object. The encryption key provided in this header must be one that was used when the source object was created.
Specifies the 128-bit MD5 digest of the encryption key according to RFC 1321. Used as a message integrity check to ensure that the encryption key was transmitted without error.
The tag-set for the object destination object this value must be used in conjunction with the
TaggingDirective
. The tag-set must be encoded as URL Query parameters.
Path Parameters
The name of the destination bucket.
The key of the destination object.
Possible values: length ≥ 1
A map of metadata to store with the object.
x-amz-meta-
Response
Container for all response elements.
Returns the ETag of the new object. The ETag reflects only changes to the contents of an object, not its metadata. The source and destination ETag is identical for a successfully copied object.
Returns the date that the object was last modified.
CopyObjectResult
Status Code
Success
ObjectNotInActiveTierError
{ "CopyObjectResult": { "ETag": "\"6805f2cfc46c0f04559748bb039d69ae\"", "LastModified": "2016-12-15T17:38:53.000Z" } }
Delete multiple objects
This operation enables you to delete multiple objects from a bucket using a single HTTP request. If you know the object keys that you want to delete, then this operation provides a suitable alternative to sending individual delete requests, reducing per-request overhead. The request contains a list of up to 1000 keys that you want to delete. In the XML, you provide the object key names. For each key, IBM COS performs a delete operation and returns the result of that delete, success, or failure, in the response. Note that if the object specified in the request is not found, IBM COS returns the result as deleted. The operation supports two modes for the response: verbose and quiet. By default, the operation uses verbose mode in which the response includes the result of deletion of each key in your request. In quiet mode the response includes only keys where the delete operation encountered an error. For a successful deletion, the operation does not return any information about the delete in the response body.
POST /{Bucket}?delete
Request
Path Parameters
The bucket name containing the objects to delete.
Query Parameters
Allowable values: [
true
]Possible values: allows empty value
Container for the objects to delete.
The objects to delete.
Key name of the object to delete.
Possible values: length ≥ 1
Objects
Element to enable quiet mode for the request. When you add this element, you must set its value to true.
Delete
Response
Container for a failed delete operation that describes the object that IBM COS attempted to delete and the error it encountered.
Status Code
Success
{ "Deleted": [ { "Key": "HappyFace.jpg", "VersionId": "yoz3HB.ZhCS_tKVEmIOr7qYyyAaZSKVd" }, { "Key": "HappyFace.jpg", "VersionId": "2LWg7lQLnY41.maGB5Z6SWW.dcq0vx7b" } ] }
Initiate a multipart upload
This operation initiates a multipart upload and returns an upload ID. This upload ID is used to associate all of the parts in the specific multipart upload. You specify this upload ID in each of your subsequent upload part requests. You also include this upload ID in the final request to either complete or abort the multipart upload request.
POST /{Bucket}/{Key}?uploads
Request
Custom Headers
Upload the object only if its entity tag (ETag) is the same as the one specified, otherwise return a 412 (precondition failed).
Upload the object only if its entity tag (ETag) is different from the one specified, otherwise return a 412 (precondition failed).
Upload the object only if it has not been modified since the specified time, otherwise return a 412 (precondition failed).
Specifies caching behavior along the request/reply chain.
Specifies presentational information for the object.
Specifies what content encodings have been applied to the object and thus what decoding mechanisms must be applied to obtain the media-type referenced by the Content-Type header field. For more information, see RFC 2616.
The language the content is in.
A standard MIME type describing the format of the contents. For more information, see RFC 2616.
The date and time at which the object is no longer cacheable. For more information, RFC 2616.
The server-side encryption algorithm used when storing this object (for example, AES256).
Allowable values: [
AES256
]If the bucket is configured as a website, redirects requests for this object to another object in the same bucket or to an external URL.
Specifies the algorithm to use to when encrypting the object (for example, AES256).
Specifies the customer-provided encryption key for encrypting data. IBM COS does not store the encryption key - it is discarded use. The key must be appropriate for use with the algorithm specified in the
x-amz-server-side-encryption-customer-algorithm
header.Specifies the 128-bit MD5 digest of the encryption key according to RFC 1321, ensuring the encryption key is transmitted without error.
A set of key-value pairs, encoded as URL query parameters.
The canned ACL to apply to the object.
Allowable values: [
private
,public-read
]
Path Parameters
The name of the bucket to which to initiate the upload.
Object key for which the multipart upload is to be initiated.
Possible values: length ≥ 1
Query Parameters
Allowable values: [
true
]Possible values: allows empty value
A map of metadata to store with the object in S3.
x-amz-meta-
Response
The name of the bucket to which the multipart upload was initiated.
When using this API with an access point, you must direct requests to the access point hostname. The access point hostname takes the form AccessPointName-AccountId.s3-accesspoint.Region.amazonaws.com. When using this operation with an access point through the AWS SDKs, you provide the access point ARN in place of the bucket name. For more information about access point ARNs, see Using Access Points in the Amazon Simple Storage Service Developer Guide.
When using this API with IBM COS on Outposts, you must direct requests to the S3 on Outposts hostname. The S3 on Outposts hostname takes the form AccessPointName-AccountId.outpostID.s3-outposts.Region.amazonaws.com. When using this operation using S3 on Outposts through the AWS SDKs, you provide the Outposts bucket ARN in place of the bucket name. For more information about S3 on Outposts ARNs, see Using S3 on Outposts in the Amazon Simple Storage Service Developer Guide.
Object key for which the multipart upload was initiated.
Possible values: length ≥ 1
ID for the initiated multipart upload.
Status Code
Success
{ "Bucket": "examplebucket", "Key": "largeobject", "UploadId": "ibZBv_75gd9r8lH_gqXatLdxMVpAlj6ZQjEs.OwyF3953YdwbcQnMA2BLGn8Lx12fQNICtMw5KyteFeHw.Sjng--" }
Complete a multipart upload
Completes a multipart upload by assembling previously uploaded parts.
After successfully uploading all parts of an upload, you call this operation to complete the upload. Upon receiving this request, IBM COS concatenates all the parts in ascending order by part number to create a new object. In the Complete Multipart Upload request, you must provide the parts list. You must ensure that the parts list is complete. This operation concatenates the parts that you provide in the list. For each part in the list, you must provide the part number and the ETag
value, returned after that part was uploaded.
POST /{Bucket}/{Key}?uploadId={uploadId}
Request
Path Parameters
Name of the bucket to which the multipart upload was initiated.
Object key for which the multipart upload was initiated.
Possible values: length ≥ 1
Query Parameters
ID for the initiated multipart upload.
The container for the completed multipart upload details.
Array of CompletedPart data types.
Entity tag returned when the part was uploaded.
Part number that identifies the part. This is a positive integer between 1 and 10,000.
Parts
CompleteMultipartUpload
Response
The URI that identifies the newly created object.
The name of the bucket that contains the newly created object.
The object key of the newly created object.
Possible values: length ≥ 1
Entity tag that identifies the newly created object data. Objects with different object data will have different entity tags. The entity tag is an opaque string. The entity tag is an MD5 digest of the object data, unless it was uploaded using SSE-C (and is randomly generated).
Status Code
Success
{ "Bucket": "acexamplebucket", "ETag": "\"4d9031c7644d8081c2829f4ea23c55f7-2\"", "Key": "bigobject", "Location": "https://examplebucket.s3.us-south.cloud-object-storage.appdomain.com/bigobject" }
List parts of a multipart upload
Lists the parts that have been uploaded for a specific multipart upload. This operation must include the upload ID, which you obtain by sending the initiate multipart upload request. This request by default returns a maximum of 1,000 uploaded parts. You can restrict the number of parts returned by specifying the max-parts
request parameter. If your multipart upload consists of more than 1,000 parts, the response returns an IsTruncated
field with the value of true, and a NextPartNumberMarker
element. In subsequent ListParts
requests you can include the part-number-marker
query string parameter and set its value to the NextPartNumberMarker
field value from the previous response.
GET /{Bucket}/{Key}?uploadId={uploadId}
Request
Path Parameters
The bucket where the parts have been uploaded.
Object key for which the multipart upload was initiated.
Possible values: length ≥ 1
Query Parameters
Upload ID identifying the multipart upload whose parts are being listed.
Sets the maximum number of parts to return.
Specifies the part after which listing should begin. Only parts with higher part numbers will be listed.
Response
The name of the bucket to which the multipart upload was initiated.
Object key for which the multipart upload was initiated.
Possible values: length ≥ 1
Upload ID identifying the multipart upload whose parts are being listed.
When a list is truncated, this element specifies the last part in the list, as well as the value to use for the part-number-marker request parameter in a subsequent request.
When a list is truncated, this element specifies the last part in the list, as well as the value to use for the part-number-marker request parameter in a subsequent request.
Maximum number of parts that were allowed in the response.
Indicates whether the returned list of parts is truncated. A true value indicates that the list was truncated. A list can be truncated if the number of parts exceeds the limit returned in the MaxParts element.
Container for elements related to a particular part. A response can contain zero or more
Part
elements.Container element that identifies who initiated the multipart upload. If the initiator is an AWS account, this element provides the same information as the
Owner
element. If the initiator is an IAM User, this element provides the user ARN and display name.If the principal is an AWS account, it provides the Canonical User ID. If the principal is an IAM User, it provides a user ARN value.
Name of the Principal.
Initiator
Container element that identifies the object owner, after the object is created. If multipart upload is initiated by an IAM user, this element provides the parent account ID and display name.
Container for the display name of the owner.
Container for the ID of the owner.
Owner
Class of storage (STANDARD or REDUCED_REDUNDANCY) used to store the uploaded object.
Possible values: [
STANDARD
,ACCELERATED
,GLACIER
]
Status Code
Success
{ "Initiator": { "DisplayName": "owner-display-name", "ID": "examplee7a2f25102679df27bb0ae12b3f85be6f290b936c4393484be31bebcc" }, "Owner": { "DisplayName": "owner-display-name", "ID": "examplee7a2f25102679df27bb0ae12b3f85be6f290b936c4393484be31bebcc" }, "Parts": [ { "ETag": "\"d8c2eafd90c266e19ab9dcacc479f8af\"", "LastModified": "2016-12-16T00:11:42.000Z", "PartNumber": "1", "Size": 26246026 }, { "ETag": "\"d8c2eafd90c266e19ab9dcacc479f8af\"", "LastModified": "2016-12-16T00:15:01.000Z", "PartNumber": "2", "Size": 26246026 } ], "StorageClass": "STANDARD" }
Abort a multipart upload
Stops a current multipart upload and removes any parts of an incomplete upload, which would otherwise incur storage costs.
DELETE /{Bucket}/{Key}?uploadId={uploadId}
List active multipart uploads
This operation lists in-progress multipart uploads. An in-progress multipart upload is a multipart upload that has been initiated using the Initiate Multipart Upload request, but has not yet been completed or aborted. This operation returns at most 1,000 multipart uploads in the response. 1,000 multipart uploads is the maximum number of uploads a response can include, which is also the default value. You can further limit the number of uploads in a response by specifying the max-uploads
parameter in the response. If additional multipart uploads satisfy the list criteria, the response will contain an IsTruncated
element with the value true. To list the additional multipart uploads, use the key-marker
and upload-id-marker
request parameters. In the response, the uploads are sorted by key. If your application has initiated more than one multipart upload using the same object key, then uploads in the response are first sorted by key. Additionally, uploads are sorted in ascending order within each key by the upload initiation time.
GET /{Bucket}?uploads
Request
Path Parameters
The name of the bucket to which the multipart upload was initiated.
Query Parameters
Allowable values: [
true
]Possible values: allows empty value
Character you use to group keys. All keys that contain the same string between the prefix, if specified, and the first occurrence of the delimiter after the prefix are grouped under a single result element,
CommonPrefixes
. If you don''t specify the prefix parameter, then the substring starts at the beginning of the key. The keys that are grouped underCommonPrefixes
result element are not returned elsewhere in the response.Requests IBM COS to encode the object keys in the response and specifies the encoding method to use. An object key may contain any Unicode character; however, XML 1.0 parser cannot parse some characters, such as characters with an ASCII value from 0 to 10. For characters that are not supported in XML 1.0, you can add this parameter to request that IBM COS encode the keys in the response.
Allowable values: [
url
]Together with upload-id-marker, this parameter specifies the multipart upload after which listing should begin. If
upload-id-marker
is not specified, only the keys lexicographically greater than the specifiedkey-marker
will be included in the list. Ifupload-id-marker
is specified, any multipart uploads for a key equal to thekey-marker
might also be included, provided those multipart uploads have upload IDs lexicographically greater than the specifiedupload-id-marker
.Sets the maximum number of multipart uploads, from 1 to 1,000, to return in the response body. 1,000 is the maximum number of uploads that can be returned in a response.
Lists in-progress uploads only for those keys that begin with the specified prefix. You can use prefixes to separate a bucket into different grouping of keys. (You can think of using prefix to make groups in the same way you'd use a folder in a file system.)
Together with key-marker, specifies the multipart upload after which listing should begin. If key-marker is not specified, the upload-id-marker parameter is ignored. Otherwise, any multipart uploads for a key equal to the key-marker might be included in the list only if they have an upload ID lexicographically greater than the specified
upload-id-marker
.Pagination limit
Pagination token
Pagination token
Response
The name of the bucket to which the multipart upload was initiated.
The key at or after which the listing began.
Upload ID after which listing began.
When a list is truncated, this element specifies the value that should be used for the key-marker request parameter in a subsequent request.
When a prefix is provided in the request, this field contains the specified prefix. The result contains only keys starting with the specified prefix.
Contains the delimiter you specified in the request. If you don't specify a delimiter in your request, this element is absent from the response.
When a list is truncated, this element specifies the value that should be used for the
upload-id-marker
request parameter in a subsequent request.Maximum number of multipart uploads that could have been included in the response.
Indicates whether the returned list of multipart uploads is truncated. A value of true indicates that the list was truncated. The list can be truncated if the number of multipart uploads exceeds the limit allowed or specified by max uploads.
Container for elements related to a particular multipart upload. A response can contain zero or more
Upload
elements.If you specify a delimiter in the request, then the result returns each distinct key prefix containing the delimiter in a
CommonPrefixes
element. The distinct key prefixes are returned in thePrefix
child element.Encoding type used by IBM COS to encode object keys in the response. If you specify
encoding-type
request parameter, IBM COS includes this element in the response, and returns encoded key name values in the following response elements:Delimiter
,KeyMarker
,Prefix
,NextKeyMarker
,Key
.Possible values: [
url
]
Status Code
Success
{ "Uploads": [ { "Initiated": "2014-05-01T05:40:58.000Z", "Initiator": { "DisplayName": "display-name", "ID": "examplee7a2f25102679df27bb0ae12b3f85be6f290b936c4393484be31bebcc" }, "Key": "JavaFile", "Owner": { "DisplayName": "display-name", "ID": "examplee7a2f25102679df27bb0ae12b3f85be6f290b936c4393484be31bebcc" }, "StorageClass": "STANDARD", "UploadId": "examplelUa.CInXklLQtSMJITdUnoZ1Y5GACB5UckOtspm5zbDMCkPF_qkfZzMiFZ6dksmcnqxJyIBvQMG9X9Q--" }, { "Initiated": "2014-05-01T05:41:27.000Z", "Initiator": { "DisplayName": "display-name", "ID": "examplee7a2f25102679df27bb0ae12b3f85be6f290b936c4393484be31bebcc" }, "Key": "JavaFile", "Owner": { "DisplayName": "display-name", "ID": "examplee7a2f25102679df27bb0ae12b3f85be6f290b936c4393484be31bebcc" }, "StorageClass": "STANDARD", "UploadId": "examplelo91lv1iwvWpvCiJWugw2xXLPAD7Z8cJyX9.WiIRgNrdG6Ldsn.9FtS63TCl1Uf5faTB.1U5Ckcbmdw--" } ] }
Upload a part of an object
Uploads a part in a multipart upload. In this operation, you provide part data in your request. However, you have an option to specify your existing IBM COS object as a data source for the part you are uploading. To upload a part from an existing object, you use the UploadPartCopy
operation. You must initiate a multipart upload (see CreateMultipartUpload
) before you can upload any part. In response to your initiate request, IBM COS returns an upload ID (a unique identifier) that you must include in your upload part requests.Part numbers can be any number from 1 to 10,000, inclusive. A part number uniquely identifies a part and also defines its position within the object being created. If you upload a new part using the same part number that was used with a previous part, the previously uploaded part is overwritten. Each part must be at least 5 MB in size, except the last part. There is no size limit on the last part of your multipart upload.
To ensure that data is not corrupted when traversing the network, specify the Content-MD5
header in the upload part request. IBM COS checks the part data against the provided MD5 value. If they do not match, IBM COS returns an error. If the upload request uses HMAC authentication (AWS Signature Version 4), then IBM COS uses the x-amz-content-sha256
header as a checksum instead of Content-MD5
.
After you initiate multipart upload and upload one or more parts, you must either complete or abort multipart upload in order to stop getting charged for storage of the uploaded parts. Only after you either complete or abort multipart upload, IBM COS frees up the parts storage and stops charging you for the parts storage.
PUT /{Bucket}/{Key}?partNumber={partNumber}&uploadId={uploadId}
Request
Custom Headers
Size of the body in bytes. This parameter is useful when the size of the body cannot be determined automatically. For more information, see RFC 2616.
The base64-encoded 128-bit MD5 digest of the payload (just the request body without the headers) according to RFC 1864. This header can be used as a message integrity check to verify that the data is the same data that was originally sent. Although it is optional, it is recommended to use the Content-MD5 mechanism as an end-to-end integrity check.
Specifies the algorithm to use to when encrypting the object (for example, AES256).
Specifies the customer-provided encryption key for IBM COS to use in encrypting data. This value is used to store the object and then it is discarded; IBM COS does not store the encryption key. The key must be appropriate for use with the algorithm specified in the
x-amz-server-side-encryption-customer-algorithm header
. This must be the same encryption key specified in the initiate multipart upload request.Specifies the 128-bit MD5 digest of the encryption key according to RFC 1321. IBM COS uses this header for a message integrity check to ensure that the encryption key was transmitted without error.
Confirms that the requester knows that they will be charged for the request. Bucket owners need not specify this parameter in their requests. For information about downloading objects from requester pays buckets, see Downloading Objects in Requestor Pays Buckets in the IBM COS Developer Guide.
Allowable values: [
requester
]The account id of the expected bucket owner. If the bucket is owned by a different account, the request will fail with an HTTP
403 (Access Denied)
error.
Path Parameters
The name of the bucket to which the multipart upload was initiated.
Object key for which the multipart upload was initiated.
Possible values: length ≥ 1
Query Parameters
Part number of part being uploaded. This is a positive integer between 1 and 10,000.
Upload ID identifying the multipart upload whose part is being uploaded.
Object data.
Use an existing object as a part of a new object
Uploads a part by copying data from an existing object as data source. You specify the data source by adding the request header x-amz-copy-source
in your request and a byte range by adding the request header x-amz-copy-source-range
in your request. The minimum allowable part size for a multipart upload is 5 MB. Instead of using an existing object as part data, you might use the UploadPart
operation and provide data in your request.
You must initiate a multipart upload before you can upload any part. In response to your initiate request. IBM COS returns a unique identifier, the upload ID, that you must include in your upload part request.
Note the following additional considerations about the request headers x-amz-copy-source-if-match
, x-amz-copy-source-if-none-match
, x-amz-copy-source-if-unmodified-since
, and x-amz-copy-source-if-modified-since
:
- If both of the
x-amz-copy-source-if-match
andx-amz-copy-source-if-unmodified-since
headers are present in the request as follows:x-amz-copy-source-if-match
condition evaluates totrue
, andx-amz-copy-source-if-unmodified-since
condition evaluates tofalse
, then IBM COS returns200 OK
and copies the data. - If both of the
x-amz-copy-source-if-none-match
andx-amz-copy-source-if-modified-since
headers are present in the request as follows:x-amz-copy-source-if-none-match
condition evaluates tofalse
, andx-amz-copy-source-if-modified-since
condition evaluates totrue
IBM COS returns412 Precondition Failed
response code.
PUT /{Bucket}/{TargetKey}?partNumber={partNumber}&uploadId={uploadId}
Request
Custom Headers
Specifies the source object to use as a part in the multipart upload.
Possible values: Value must match regular expression
\/.+\/.+
Copies the object if its entity tag (ETag) matches the specified tag.
Copies the object if it has been modified since the specified time.
Copies the object if its entity tag (ETag) is different than the specified ETag.
Copies the object if it hasn't been modified since the specified time.
The range of bytes to copy from the source object. The range value must use the form bytes=first-last, where the first and last are the zero-based byte offsets to copy. For example, bytes=0-9 indicates that you want to copy the first 10 bytes of the source. You can copy a range only if the source object is greater than 5 MB.
Specifies the algorithm to use to when encrypting the object (
AES256
).Specifies the customer-provided encryption key for IBM COS to use in encrypting data. This value is used to store the object and then it is discarded; IBM COS does not store the encryption key. The key mu