IBM Cloud API Docs

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 /

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • cloud-object-storage.account.get_account_buckets

Auditing

Calling this method generates the following auditing event.

  • cloud-object-storage.instance.list

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.

Status Code

  • Success

Example responses
  • 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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • cloud-object-storage.bucket.put_bucket

Auditing

Calling this method generates the following auditing event.

  • cloud-object-storage.bucket.create

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

  • 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)
    }

Response

Status Code

  • Success

  • BucketAlreadyExists

No Sample Response

This method does not specify any sample responses.

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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • cloud-object-storage.bucket.delete_bucket

Auditing

Calling this method generates the following auditing event.

  • cloud-object-storage.bucket.delete

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)
    }

Response

Status Code

  • Success

No Sample Response

This method does not specify any sample responses.

Read a bucket's headers

This request is useful for checking whether a bucket has Key Protect enabled.

HEAD /{Bucket}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions. You can check your access by going to Users > User > Access.

  • cloud-object-storage.bucket.head

  • cloud-object-storage.bucket.list_crk_id

Auditing

Calling this method generates the following auditing event.

  • cloud-object-storage.bucket-metadata.read

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)
    }

Response

Status Code

  • Success

  • NoSuchBucket

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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • cloud-object-storage.bucket.get

Auditing

Calling this method generates the following auditing event.

  • cloud-object-storage.bucket.list

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

Status Code

  • Success

  • NoSuchBucket

Example responses
  • 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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • cloud-object-storage.bucket.get

Auditing

Calling this method generates the following auditing event.

  • cloud-object-storage.bucket.list

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

Status Code

  • Success

  • NoSuchBucket

Example responses
  • 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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • cloud-object-storage.object.put

Auditing

Calling this method generates the following auditing event.

  • cloud-object-storage.object.write

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

  • 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)
    }

Response

Status Code

  • OK

No Sample Response

This method does not specify any sample responses.

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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • cloud-object-storage.object.get

Auditing

Calling this method generates the following auditing event.

  • cloud-object-storage.object.read

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 response

  • Sets 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

Status Code

  • Success

  • NoSuchKey

Example responses
  • {
      "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions. You can check your access by going to Users > User > Access.

  • cloud-object-storage.bucket.head

  • cloud-object-storage.bucket.list_crk_id

Auditing

Calling this method generates the following auditing event.

  • cloud-object-storage.bucket-metadata.read

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.

Response

Status Code

  • Success

  • NoSuchKey

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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • cloud-object-storage.object.delete

Auditing

Calling this method generates the following auditing event.

  • cloud-object-storage.object.delete

Request

Path Parameters

  • The bucket containing the object.

  • Key name of the object to delete.

    Possible values: length ≥ 1

Response

Status Code

  • Success

Example responses
  • {}

Copy an object

Copies an object.

PUT /{Bucket}/{TargetKey}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions. You can check your access by going to Users > User > Access.

  • cloud-object-storage.object.copy

  • cloud-object-storage.object.copy_get

Auditing

Calling this method generates the following auditing events.

  • cloud-object-storage.object-copy.read

  • cloud-object-storage.object-copy.create

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

Response

Status Code

  • Success

  • ObjectNotInActiveTierError

Example responses
  • {
      "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • cloud-object-storage.object.post_multi_delete

Auditing

Calling this method generates the following auditing event.

  • cloud-object-storage.object-batch.delete

Request

Path Parameters

  • The bucket name containing the objects to delete.

Query Parameters

  • Allowable values: [true]

    Possible values: allows empty value

Response

Status Code

  • Success

Example responses
  • {
      "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • cloud-object-storage.object.post_initiate_upload

Auditing

Calling this method generates the following auditing event.

  • cloud-object-storage.object-multipart.start

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

Response

Status Code

  • Success

Example responses
  • {
      "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • cloud-object-storage.object.post_complete_upload

Auditing

Calling this method generates the following auditing event.

  • cloud-object-storage.object-multipart.complete

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.

Response

Status Code

  • Success

Example responses
  • {
      "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • cloud-object-storage.object.get_uploads

Auditing

Calling this method generates the following auditing event.

  • cloud-object-storage.object-multipart.list

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

Status Code

  • Success

Example responses
  • {
      "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • cloud-object-storage.object.delete_upload

Auditing

Calling this method generates the following auditing event.

  • cloud-object-storage.object-multipart.delete

Request

Path Parameters

  • The destination bucket for the upload.

  • Key of the object for which the multipart upload was initiated.

    Possible values: length ≥ 1

Query Parameters

  • Upload ID that identifies the multipart upload.

Response

Status Code

  • Success

  • NoSuchUpload

Example responses
  • {}

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • cloud-object-storage.bucket.get_uploads

Auditing

Calling this method generates the following auditing event.

  • cloud-object-storage.bucket-multipart.list

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 under CommonPrefixes 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 specified key-marker will be included in the list. If upload-id-marker is specified, any multipart uploads for a key equal to the key-marker might also be included, provided those multipart uploads have upload IDs lexicographically greater than the specified upload-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

Status Code

  • Success

Example responses
  • {
      "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • cloud-object-storage.object.put_part

Auditing

Calling this method generates the following auditing event.

  • cloud-object-storage.object-multipart.create

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.

Response

Status Code

  • Success

Example responses
  • {
      "ETag": "\"d8c2eafd90c266e19ab9dcacc479f8af\""
    }

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 UploadPartoperation 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 and x-amz-copy-source-if-unmodified-since headers are present in the request as follows: x-amz-copy-source-if-match condition evaluates to true, and x-amz-copy-source-if-unmodified-since condition evaluates to false, then IBM COS returns 200 OK and copies the data.
  • If both of the x-amz-copy-source-if-none-match and x-amz-copy-source-if-modified-since headers are present in the request as follows: x-amz-copy-source-if-none-match condition evaluates to false, and x-amz-copy-source-if-modified-since condition evaluates to true IBM COS returns 412 Precondition Failed response code.
PUT /{Bucket}/{TargetKey}?partNumber={partNumber}&uploadId={uploadId}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions. You can check your access by going to Users > User > Access.

  • cloud-object-storage.object.copy_part

  • cloud-object-storage.object.copy_part_get

Auditing

Calling this method generates the following auditing event.

  • cloud-object-storage.object-multipart.create

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