COS Resource Configuration API | IBM Cloud API Docs

Introduction

Last updated: 2024-01-26

This is a new API for configuring IBM Cloud Object Storage buckets.

This API will evolve to cover the full suite of bucket configuration options provided today by extensions made to the modified S3 API. The COS Resource Configuration API now supports:

Viewing non-mutable bucket metadata (CRNs, timestamps, and usage info)
Viewing and setting IP address access filters.
Viewing and setting Activity Tracker events for object operations.

The Configuration API supports two request methods. The Get bucket configuration method reads a bucket's metadata, and returns an entity tag (ETag) header that identifies the current configuration. The tag is updated when some piece of mutable configuration metadata changes. Use the ETag with an if-match header in the Update bucket configuration method to ensure that you are overwriting the correct configuration.

PATCH operations can update multiple fields in the same request.

What is mutable configuration metadata? There's a lot of useful but non-mutable metadata associated with a bucket: its name, location, class, the service instance it belongs to, the number of objects it holds, and so on. None of those values can be directly edited by a user but are important for intelligent data management and are necessary for integration with other IBM Cloud services. In contrast, mutable bucket metadata adds functionality or alters behavior. In this initial version of the Configuration API, the only such metadata is a bucket's firewall, Activity Tracker, and Metrics Monitoring configurations.

In direct contrast to an S3 API, the Configuration API doesn't rely on separate methods to access different bucket parameters. For example, in an S3 API you might use these methods:

Read the configuration of a bucket firewall by sending GET {endpoint}/{bucket}?firewall.
Read the configuration location with GET {endpoint}/{bucket}?location.
Check whether the configuration has Key Protect enabled by sending HEAD {endpoint}/{bucket} and reviewing the response headers.

Instead, the Configuration API uses a single JSON document to describe all aspects of a bucket's metadata and configuration with the Get the bucket configuration method. To update the configuration, the Configuration API uses JSON Merge Patch semantics to make updates directly to the bucket's metadata. Although you can only update a bucket's IP address access filter right now, the API might be updated to support making other updates. For example, you might be able to add a lifecycle rule, remove a firewall, and update a default retention period in a single request.

Some IDEs (such as PyCharm) may produce warnings about unused classes or methods. This is an artifact of the code generation tooling that allows for the passing of objects in named parameters, but generates a docstring that causes some linting tools to raise a warning.

JavaScript developers can use this SDK to interact with the Object Storage Resource Configuration API. For more information, see the COS Resource Configuration SDK for Java API Reference.

The SDK is supported on Java versions 1.6 and later.

JavaScript developers can use this SDK to interact with the Object Storage Resource Configuration API. For more information, see the COS Resource Configuration SDK for Java API Reference.

The SDK is supported on Node versions 8.x and later.

Python developers can use this SDK to interact with Object Storage Resource Configuration API. For more information, see the COS Resource Configuration SDK for Python API Reference.

Go developers can use this SDK to interact with Object Storage Resource Configuration API. For more information, see the COS Resource Configuration SDK for Go API Reference.

The SDK supports Go versions 1.12 and above.

The code examples on this tab use the Resource Configuration client library that is provided for Java.

Maven

<dependency>
  <groupId>com.ibm.cos.config</groupId>
  <artifactId>ibm-cos-java-config</artifactId>
</dependency>

GitHub

https://github.com/IBM/ibm-cos-sdk-java-config

The code examples on this tab use the client library that is provided for Node.js.

Installation

npm install ibm-cos-sdk-config

GitHub

https://github.com/IBM/ibm-cos-sdk-js-config

The code examples on this tab use the client library that is provided for Python.

Installation

pip install --upgrade ibm-cos-sdk-config

GitHub

https://github.com/IBM/ibm-cos-sdk-python-config

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-config

GitHub

https://github.com/IBM/ibm-cos-sdk-go-config

Endpoint URLs

Unlike the S3-compatible API for reading and writing data, the Configuration API uses a single, global service endpoint. Whether getting or updating metadata, for buckets located in the eu geo, us-south region, ams01 zone, or any other storage location, the request uses the same endpoint URL: https://config.cloud-object-storage.cloud.ibm.com/v1.

Note that the endpoint URL actually contains three parts: a protocol (https://), a host (config.cloud-object-storage.cloud.ibm.com), and a version (v1). The SDKs will construct this by default, but if sending requests using curl or any other REST API utility keep in mind that the endpoint requires both the protocol and version.

Error handling

This API uses standard HTTP response codes to indicate whether a method completed successfully. A 200 response indicates success. A 400 type response indicates a failure, and a 500 type response indicates an internal system error.

Element	Description
`http_status_code`	HTTP status code for the response. Integer. Example: `200`
`code`	Error code. String. Example: `AccessDenied`
`message`	Error message. String. Example: `Access Denied`
`resource`	Target of the failed request. String. Example: `Bucket123`
`ibm_cos_request_id`	Unique identifier for this request. String. Example: `5043294b-de39-4034-881a-92afbed1453d`

Example error object:

{
  "http_status_code": 403,
  "code": "AccessDenied",
  "message": "Access Denied",
  "resource": "my-new-bucket",
  "ibm_cos_request_id": "9f39ff2e-55d1-461b-a6f1-2d0b75138861"
}

Authentication

To work with the API, authenticate your app or service by including your IBM Cloud IAM access token.

To retrieve an access token:

curl -X POST https://iam.cloud.ibm.com/identity/token \
  -H "content-type: application/x-www-form-urlencoded" \
  -H "accept: application/json" \
  -d "grant_type=urn%3Aibm%3Aparams%3Aoauth%3Agrant-type%3Aapikey&apikey=<API_KEY>"

Replace <API_KEY> with your service credentials. Then use the full IAM token value, prefixed by the Bearer token type, to authenticate your API requests.

To retrieve an access token:

To be added

Replace <API_KEY> with your service credentials. Then use the full IAM token value, prefixed by the Bearer token type, to authenticate your API requests.

To create a client that will automatically handle token management:

const COS = require('ibm-cos-sdk-config/resource-configuration/v1')
const IAMAUTHENTICATOR = require('ibm-cos-sdk-config/auth');

clientInfo = new IamAuthenticator({
  apikey: 'apikey',
})

const client = new COS(clientInfo);

Replace apikey with an API key.

Now client is ready to make requests.

To create a client that will automatically handle token management:

from ibm_cos_sdk_config.resource_configuration_v1 import ResourceConfigurationV1
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

authenticator = IAMAuthenticator(
  apikey = 'apikey'
)

client = ResourceConfigurationV1(authenticator=api_key)

Replace api_key with a valid API key.

Now client is ready to make requests.

To retrieve an access token:

To be added

Replace <API_KEY> with your service credentials. Then use the full IAM token value, prefixed by the Bearer token type, to authenticate your API requests.

Additional headers

Request Parameter	Description
`authorization`	Required IBM Cloud IAM bearer token. String.
`content-type`	The content type of the request body. String. Example: `application/json`.

Response Parameter	Description
`Date`	Timestamp of the response. String. Example: `Sun, 13 Jan 2019 18:00:56 GMT`
`Content-Type`	All responses are of type `application/json`. Only returned if there is a response body (such as `GET`). String.
`Content-Length`	Length in bytes of the response body. Integer. Only returned if there is a response body (such as `GET`). Example: `255`
`ETag`	Entity tag (per RFC 7232) of the current state of configuration. String. Example: `"3ee236f6-0f8e-4171-8cec-050e4c87be48"`
`ibm-cos-config-api-ver`	The version of this API. String. Example: `1.0`
`ibm-cos-request-id`	Unique identifier for this request. String. Example: `5043294b-de39-4034-881a-92afbed1453d`

Returns metadata for the specified bucket.

GET /b/{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.

Allows reading of bucket metadata.

cloud-object-storage.bucket.list_bucket_crn
cloud-object-storage.bucket.get_firewall
cloud-object-storage.bucket.get_activity_tracking
cloud-object-storage.bucket.get_metrics_monitoring
cloud-object-storage.bucket.get_protection_management

Request

Path Parameters

bucket
Required*
string
Name of a bucket.

Fetch a bucket's metadata

curl https://config.cloud-object-storage.cloud.ibm.com/v1/b/my-bucket -H 'authorization: bearer $IAM_TOKEN'

Fetch a bucket's metadata

import com.ibm.cloud.objectstorage.config.resource_configuration.v1.ResourceConfiguration;
import com.ibm.cloud.objectstorage.config.resource_configuration.v1.model.BucketPatch;
import com.ibm.cloud.sdk.core.security.IamAuthenticator;

public class GetMetadata {

    private static final String BUCKET_NAME = <BUCKET_NAME>;
    private static final String API_KEY = <API_KEY>;

    public static void main(String[] args) {
    
        IamAuthenticator authenticator = new IamAuthenticator.Builder()
                .apiKey(API_KEY)
                .build();

        ResourceConfiguration RC_CLIENT = new ResourceConfiguration("resource-configuration", authenticator);

        GetBucketConfigOptions bucketOptions = new GetBucketConfigOptions.Builder(BUCKET_NAME).build();
        Bucket bucket = RC_CLIENT.getBucketConfig(bucketOptions).execute().getResult();

        ActivityTracking activityTrackingResponse = bucket.getActivityTracking();
        MetricsMonitoring metricsMonitoringResponse = bucket.getMetricsMonitoring();
        Firewall firewallResponse = bucket.getFirewall();
        ProtectionManagementResponse protectionManagementResponse = bucket.getProtectionManagement();
    }
}

Fetch a bucket's metadata

from ibm_cos_sdk_config.resource_configuration_v1 import ResourceConfigurationV1
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

api_key = '<API_KEY>'
bucket_name = '<BUCKET_NAME>'

authenticator = IAMAuthenticator(
  apikey=api_key
)

rc_client = ResourceConfigurationV1(authenticator=authenticator)

config = rc_client.get_bucket_config(bucket_name)

print(config)

Fetch a bucket's metadata

ResourceConfigurationV1 = require('ibm-cos-sdk-config/resource-configuration/v1');
IamAuthenticator = require('ibm-cos-sdk-config/auth');

var apiKey = '<API_KEY>'
var bucketName = '<BUCKET_NAME>'

authenticator = new IamAuthenticator({
  apikey: apiKey
});

const rcConfig = {authenticator: authenticator}

const client = new ResourceConfigurationV1(rcConfig);

function getBucketMetadata() {
    console.log('Getting bucket metadata...');

    var params = {bucket: bucketName};

    client.getBucketConfig(params, function (err, response) {
        if (err) {
            console.log("ERROR: " + err);
        } else {
            console.log(response.result);
        }
    });
}

getBucketMetadata()

Fetch a bucket's metadata

import (
  fmt
	"github.com/IBM/go-sdk-core/core"
  rc "github.com/IBM/ibm-cos-sdk-go-config/v2/resourceconfigurationv1"
)

const (
  apiKey = '<API_KEY>'
  bucketName = '<BUCKET_NAME>'
)

authenticator := &core.IamAuthenticator{
      ApiKey:  apiKey,
}

service, _ := rc.NewResourceConfigurationV1(&rc.ResourceConfigurationV1Options{
      Authenticator: authenticator,
})

getBucketConfigOptions := &rc.GetBucketConfigOptions{
  Bucket: core.StringPtr(bucketName),
}
result, response, _ := service.GetBucketConfig(getBucketConfigOptions)
fmt.Println(result)
fmt.Println(response)

Response

Response Body

Bucket

A bucket.

Status Code

200
Success
400
Bad Request
401
Unauthorized
403
Forbidden
404
Not Found
500
Internal Server Error

Example responses

Status 200

{
  "name": "my-new-bucket",
  "crn": "crn:v1:bluemix:public:cloud-object-storage:global:a/ 3bf0d9003abfb5d29761c3e97696b71c:xxxxxxx-6c4f-4a62-a165-696756d63903:bucket:my-new-bucket",
  "service_instance_id": "xxxxxxx-6c4f-4a62-a165-696756d63903",
  "service_instance_crn": "crn:v1:bluemix:public:cloud-object-storage:global:a/3bf0d9003abfb5d29761c3e97696b71c:xxxxxxx-6c4f-4a62-a165-696756d63903::",
  "time_created": "2018-03-26T16:23:36.980Z",
  "time_updated": "2018-10-17T19:29:10.117Z",
  "object_count": 764265234,
  "bytes_used": 28198745752445144
}

Status 400

{
  "http_status_code": 400,
  "code": "InvalidRequest",
  "message": "The request contains invalid elements.",
  "resource": "my-new-bucket",
  "ibm_cos_request_id": "9f39ff2e-55d1-461b-a6f1-2d0b75138861"
}

Status 401

{
  "code": "Unauthorized",
  "message": "The token provided is not valid.",
  "resource": "my-new-bucket",
  "ibm_cos_request_id": "9f39ff2e-55d1-461b-a6f1-2d0b75138861",
  "http_status_code": 401
}

Status 403

{
  "code": "AccessDenied",
  "message": "Access Denied",
  "resource": "my-new-bucket",
  "ibm_cos_request_id": "9f39ff2e-55d1-461b-a6f1-2d0b75138861",
  "http_status_code": 403
}

Status 404

{
  "code": "NoSuchBucket",
  "message": "The specified bucket does not exist.",
  "resource": "my-new-bucket",
  "ibm_cos_request_id": "9f39ff2e-55d1-461b-a6f1-2d0b75138861",
  "http_status_code": 404
}

Status 500

{
  "code": "InternalError",
  "message": "Internal server error.",
  "resource": "my-new-bucket",
  "ibm_cos_request_id": "9f39ff2e-55d1-461b-a6f1-2d0b75138861",
  "http_status_code": 500
}

Updates a bucket using JSON Merge Patch. This request is used to add functionality (like an IP access filter) or to update existing parameters. Primitives are overwritten and replaced in their entirety. It is not possible to append a new (or to delete a specific) value to an array. Arrays can be cleared by updating the parameter with an empty array []. A PATCH operation only updates specified mutable fields. Please don't use PATCH trying to update the number of objects in a bucket, any timestamps, or other non-mutable fields.

PATCH /b/{bucket}

Request

Custom Headers

If-Match
string
An Etag previously returned in a header when fetching or updating a bucket's metadata. If this value does not match the active Etag, the request will fail.

Path Parameters

bucket
Required*
string
Name of a bucket.

Request Body

application/merge-patch+jsonBucketPatch

An object containing new configuration metadata.

Examples:

firewall

activity_tracking

Enable a firewall

curl -X PATCH https://config.cloud-object-storage.cloud.ibm.com/v1/b/my-bucket   -H 'authorization: bearer $IAM_TOKEN'   -d '{"firewall": {"allowed_ip": ["10.142.175.0/22", "10.198.243.79"]}}'

Enable activity tracking

curl -X PATCH https://config.cloud-object-storage.cloud.ibm.com/v1/b/my-bucket   -H 'authorization: bearer $IAM_TOKEN'   -d '{"activity_tracking": {           "activity_tracker_crn": $AT_CRN,           "read_data_events": true,           "write_data_events": true}'

Enable metrics monitoring

curl -X PATCH https://config.cloud-object-storage.cloud.ibm.com/v1/b/my-bucket   -H 'authorization: bearer $IAM_TOKEN'   -d '{"metrics_monitoring": {           "metrics_monitoring_crn": $MM_CRN,           "usage_metrics_enabled": true}'

Activate protection management

curl -X PATCH https://config.cloud-object-storage.cloud.ibm.com/v1/b/my-bucket   -H 'authorization: bearer $IAM_TOKEN'   -d '{"protection_management": {           "requested_state": "activate",           "protection_management_token": $PM_TOKEN}}'

Enable firewall

import com.ibm.cloud.objectstorage.config.resource_configuration.v1.ResourceConfiguration;
import com.ibm.cloud.objectstorage.config.resource_configuration.v1.model.BucketPatch;
import com.ibm.cloud.sdk.core.security.IamAuthenticator;

import java.util.Arrays;

public class FirewallExample {

    private static final String BUCKET_NAME = <BUCKET_NAME>;
    private static final String API_KEY = <API_KEY>;
    private static List<String> IP_ARRAY = new ArrayList<String>();
    IP_ARRAY.add("x.x.x.x");
    IP_ARRAY.add("y.y.y.y");

    public static void main(String[] args) {
    
        IamAuthenticator authenticator = new IamAuthenticator.Builder()
                .apiKey(API_KEY)
                .build();

        ResourceConfiguration RC_CLIENT = new ResourceConfiguration("resource-configuration", authenticator);

        Firewall firewallConfig = new Firewall.Builder().allowedIp(IP_ARRAY).build();

        BucketPatch bucketPatch = new BucketPatch.Builder().firewall(firewallConfig).build();

        UpdateBucketConfigOptions update = new UpdateBucketConfigOptions
                .Builder(BUCKET_NAME)
                .bucketPatch(bucketPatch.asPatch())
                .build();

        RC_CLIENT.updateBucketConfig(update).execute();

        GetBucketConfigOptions bucketOptions = new GetBucketConfigOptions.Builder(BUCKET_NAME).build();
        Bucket bucket = RC_CLIENT.getBucketConfig(bucketOptions).execute().getResult();
        Firewall firewallResponse = bucket.getFirewall();
        for(String ip: firewallResponse.allowedIp()){
          System.out.println(ip)
        }
    }
}

Enable activity tracking

import com.ibm.cloud.objectstorage.config.resource_configuration.v1.ResourceConfiguration;
import com.ibm.cloud.objectstorage.config.resource_configuration.v1.model.BucketPatch;
import com.ibm.cloud.sdk.core.security.IamAuthenticator;

public class ActivityTrackerExample {

    private static final String BUCKET_NAME = <BUCKET_NAME>;
    private static final String API_KEY = <API_KEY>;
    private static final String AT_CRN = <AT_CRN>;

    public static void main(String[] args) {
    
        IamAuthenticator authenticator = new IamAuthenticator.Builder()
                .apiKey(API_KEY)
                .build();

        ResourceConfiguration RC_CLIENT = new ResourceConfiguration("resource-configuration", authenticator);

        ActivityTracking activityTrackingConfig = new ActivityTracking().Builder()
                .activityTrackerCrn(AT_CRN)
                .readDataEvents(true)
                .writeDataEvents(true)
                .build();

        BucketPatch bucketPatch = new BucketPatch.Builder().activityTracking(activityTrackingConfig).build();

        UpdateBucketConfigOptions update = new UpdateBucketConfigOptions
                .Builder(BUCKET_NAME)
                .bucketPatch(bucketPatch.asPatch())
                .build();

        RC_CLIENT.updateBucketConfig(update).execute();

        GetBucketConfigOptions bucketOptions = new GetBucketConfigOptions.Builder(BUCKET_NAME).build();
        Bucket bucket = RC_CLIENT.getBucketConfig(bucketOptions).execute().getResult();

        ActivityTracking activityTrackingResponse = bucket.getActivityTracking();
        System.out.println("Read Data Events : " + activityTrackingResponse.readDataEvents());
        System.out.println("Write Data Events : " + activityTrackingResponse.writeDataEvents());
        System.out.println("Activity Tracking CRN : " + activityTrackingResponse.activityTrackerCrn());
    }
}

Enable metrics monitoring

import com.ibm.cloud.objectstorage.config.resource_configuration.v1.ResourceConfiguration;
import com.ibm.cloud.objectstorage.config.resource_configuration.v1.model.BucketPatch;
import com.ibm.cloud.sdk.core.security.IamAuthenticator;

public class MetricsMonitoringExample {

    private static final String BUCKET_NAME = <BUCKET_NAME>;
    private static final String API_KEY = <API_KEY>;
    private static final String MM_CRN = <MM_CRN>;

    public static void main(String[] args) {
    
        IamAuthenticator authenticator = new IamAuthenticator.Builder()
                .apiKey(API_KEY)
                .build();

        ResourceConfiguration RC_CLIENT = new ResourceConfiguration("resource-configuration", authenticator);

        MetricsMonitoring metricsMonitoringConfig = new MetricsMonitoring().Builder()
              .metricsMonitoringCrn(MM_CRN)
              .requestMetricsEnabled(true)
              .usageMetricsEnabled(true)
              .build();

        BucketPatch bucketPatch = new BucketPatch.Builder().metricsMonitoring(metricsMonitoringConfig).build();

        UpdateBucketConfigOptions update = new UpdateBucketConfigOptions
                .Builder(BUCKET_NAME)
                .bucketPatch(bucketPatch.asPatch())
                .build();

        RC_CLIENT.updateBucketConfig(update).execute();

        GetBucketConfigOptions bucketOptions = new GetBucketConfigOptions.Builder(BUCKET_NAME).build();
        Bucket bucket = RC_CLIENT.getBucketConfig(bucketOptions).execute().getResult();

        MetricsMonitoring metricsMonitoringResponse = bucket.getMetricsMonitoring();
        System.out.println("Usage Metrics Enabled  : " + metricsMonitoringResponse.usageMetricsEnabled());
        System.out.println("Request Metrics Enabled : " + metricsMonitoringResponse.requestMetricsEnabled());
        System.out.println("Metrics Monitoring CRN : " + metricsMonitoringResponse.metricsMonitoringCrn());
    }
}

Enable protection management

import com.ibm.cloud.objectstorage.config.resource_configuration.v1.ResourceConfiguration;
import com.ibm.cloud.objectstorage.config.resource_configuration.v1.model.BucketPatch;
import com.ibm.cloud.sdk.core.security.IamAuthenticator;

public class ProtectionManagementExample {

    private static final String BUCKET_NAME = <BUCKET_NAME>;
    private static final String API_KEY = <API_KEY>;
    private static final String PM_TOKEN = <PM_TOKEN>;

    public static void main(String[] args) {

        IamAuthenticator authenticator = new IamAuthenticator.Builder()
                .apiKey(API_KEY)
                .build();

        ResourceConfiguration RC_CLIENT = new ResourceConfiguration("resource-configuration", authenticator);

        ProtectionManagement protectionManagementConfig = new ProtectionManagement.Builder()
              .requestedState("activate")
              .protectionManagementToken(PM_TOKEN)
              .build();

        BucketPatch bucketPatch = new BucketPatch.Builder().protectionManagement(protectionManagementConfig).build();

        UpdateBucketConfigOptions update = new UpdateBucketConfigOptions
                .Builder(BUCKET_NAME)
                .bucketPatch(bucketPatch.asPatch())
                .build();

        RC_CLIENT.updateBucketConfig(update).execute();

        GetBucketConfigOptions bucketOptions = new GetBucketConfigOptions.Builder(BUCKET_NAME).build();
        Bucket bucket = RC_CLIENT.getBucketConfig(bucketOptions).execute().getResult();

        ProtectionManagementResponse protectionManagementResponse = bucket.getProtectionManagement();
        List<ProtectionManagementResponseTokenEntry> ProtectionManagementResponseTokenEntries = protectionManagementResponse.tokenEntries();
        System.out.println("Token Applied Counter: " + protectionManagementResponse.tokenAppliedCounter());
        for(ProtectionManagementResponseTokenEntry tokenEntry: ProtectionManagementResponseTokenEntries) {
          System.out.println("Token Reference Id: " + tokenEntry.getTokenReferenceId());
        }
    }
}

Enable a firewall

from ibm_cos_sdk_config.resource_configuration_v1 import ResourceConfigurationV1
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

api_key = "<API_KEY>"
bucket_name = "<BUCKET_NAME>"
ip_array = ["x.x.x.x", "y.y.y.y"]

authenticator = IAMAuthenticator(apikey=api_key)
client = ResourceConfigurationV1(authenticator=authenticator)

firewall_config = {'firewall': {"allowed_ip": ip_array}}

client.update_bucket_config(bucket_name, bucket_patch=firewall_config)

Enable activity tracking

from ibm_cos_sdk_config.resource_configuration_v1 import ResourceConfigurationV1
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

api_key = "<API_KEY>"
bucket_name = "<BUCKET_NAME>"
at_crn = "<AT_CRN>"

authenticator = IAMAuthenticator(apikey=api_key)
client = ResourceConfigurationV1(authenticator=authenticator)

activity_tracking_config = {'activity_tracking':{'activity_tracker_crn': at_crn, 'read_data_events':True, 'write_data_events':True}}

client.update_bucket_config(bucket_name, bucket_patch=activity_tracking_config)

Enable metrics monitoring

from ibm_cos_sdk_config.resource_configuration_v1 import ResourceConfigurationV1
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

api_key = "<API_KEY>"
bucket_name = "<BUCKET_NAME>"
mm_crn = "<MM_CRN>"

authenticator = IAMAuthenticator(apikey=api_key)
client = ResourceConfigurationV1(authenticator=authenticator)

metrics_monitoring_config = {'metrics_monitoring': {'metrics_monitoring_crn': mm_crn, 'request_metrics_enabled':True, 'usage_metrics_enabled':True}}

client.update_bucket_config(bucket_name, bucket_patch=metrics_monitoring_config)

Enable protection management

from ibm_cos_sdk_config.resource_configuration_v1 import ResourceConfigurationV1
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

api_key = "<API_KEY>"
bucket_name = "<BUCKET_NAME>"
pm_token = "<PM_TOKEN>"

authenticator = IAMAuthenticator(apikey=api_key)
client = ResourceConfigurationV1(authenticator=authenticator)

protection_management_config = {'protection_management': {'requested_state': 'activate', 'protection_management_token': pm_token}}

client.update_bucket_config(bucket_name, bucket_patch=protection_management_config)

Enable a firewall

const ResourceConfigurationV1 = require('ibm-cos-sdk-config/resource-configuration/v1');
IamAuthenticator      = require('ibm-cos-sdk-config/auth');

var apiKey = "<API_KEY>"
var bucketName = "<BUCKET_NAME>"
var allowedIP = ["56.131.110.60"]

authenticator = new IamAuthenticator({apikey: apiKey})
rcConfig = {authenticator: authenticator}
const client = new ResourceConfigurationV1(rcConfig);

function addFirewall() {
    console.log('Updating bucket metadata...');

    var params = {
        bucket: bucketName,
        firewall: {
            allowed_ip: allowedIP
        }
    };

    client.updateBucketConfig(params, function (err, response) {
        if (err) {
            console.log("ERROR: " + err);
        } else {
            console.log(response.result);
        }
    });
}

addFirewall()

Enable activity tracking

const ResourceConfigurationV1 = require('ibm-cos-sdk-config/resource-configuration/v1');
IamAuthenticator      = require('ibm-cos-sdk-config/auth');

var apiKey = "<API_KEY>"
var bucketName = "<BUCKET_NAME>"

authenticator = new IamAuthenticator({apikey: apiKey})
rcConfig = {authenticator: authenticator}
const client = new ResourceConfigurationV1(rcConfig);

function addAT() {
    console.log('Updating bucket metadata...');

    var params = {
        bucket: bucketName,
        activityTracking: {
          "activity_tracker_crn": at_crn,
          "read_data_events": true,
          "write_data_events": true
          }
    };

    client.updateBucketConfig(params, function (err, response) {
        if (err) {
            console.log("ERROR: " + err);
        } else {
            console.log(response.result);
        }
    });
}

addAT()

Enable protection management

const ResourceConfigurationV1 = require('ibm-cos-sdk-config/resource-configuration/v1');
const { IamAuthenticator }    = require('ibm-cos-sdk-config/auth');

var apiKey     = "<API_KEY>"
var bucketName = "<BUCKET_NAME>"
var pmToken    = "<PM_TOKEN>"

const authenticator = new IamAuthenticator({apikey: apiKey})
const rcConfig = {authenticator: authenticator}
const client = new ResourceConfigurationV1(rcConfig);

function addPM() {
    var params = {
        bucket: bucketName,
        protectionManagement: {
          "requested_state": "activate",
          "protection_management_token": pmToken
          }
    };

    client.updateBucketConfig(params, function (err, data) {
        if (err) {
            console.log("ERROR: " + err);
        } else {
            console.log(data);
        }
    });
}

addPM()

Enable protection management

import ( 
"github.com/IBM/go-sdk-core/core"
  rc "github.com/IBM/ibm-cos-sdk-go-config/v2/resourceconfigurationv1"
)

apiKey := "<ApiKey>"
bucketName := "<BucketName>"
pmToken := "<PMToken>"

authenticator := new(core.IamAuthenticator)
authenticator.ApiKey = apiKey
optionsRC := new(rc.ResourceConfigurationV1Options)
optionsRC.Authenticator = authenticator
rcClient, _ := rc.NewResourceConfigurationV1(optionsRC)

patchNameMap := make(map[string]interface{})
patchNameMap["protection_management"] = &rc.ProtectionManagement{
  RequestedState:     core.StringPtr("activate"),
  ProtectionManagementToken:    core.StringPtr(pmToken),
}
updateBucketConfigOptions := &rc.UpdateBucketConfigOptions{
  Bucket:      core.StringPtr(bucketName),
  BucketPatch: patchNameMap,
}

rcClient.UpdateBucketConfig(updateBucketConfigOptions)

Response

Status Code

200
Success
400
Bad Request
401
Unauthorized
403
Forbidden
404
Not Found
412
Precondition Failed
500
Internal Server Error

Example responses

Status 400

{
  "code": "InvalidRequest",
  "message": "The request contains invalid elements.",
  "resource": "my-new-bucket",
  "ibm_cos_request_id": "9f39ff2e-55d1-461b-a6f1-2d0b75138861",
  "http_status_code": 400
}

Status 401

{
  "code": "Unauthorized",
  "message": "The token provided is not valid.",
  "resource": "my-new-bucket",
  "ibm_cos_request_id": "9f39ff2e-55d1-461b-a6f1-2d0b75138861",
  "http_status_code": 401
}

Status 403

{
  "code": "AccessDenied",
  "message": "Access Denied",
  "resource": "my-new-bucket",
  "ibm_cos_request_id": "9f39ff2e-55d1-461b-a6f1-2d0b75138861",
  "http_status_code": 403
}

Status 404

{
  "code": "NoSuchBucket",
  "message": "The specified bucket does not exist.",
  "resource": "my-new-bucket",
  "ibm_cos_request_id": "9f39ff2e-55d1-461b-a6f1-2d0b75138861",
  "http_status_code": 404
}

Status 412

{
  "http_status_code": 412,
  "code": "PreconditionFailed",
  "message": "At least one of the preconditions specified were not met.",
  "resource": "my-new-bucket",
  "ibm_cos_request_id": "9f39ff2e-55d1-461b-a6f1-2d0b75138861"
}

Status 500

{
  "http_status_code": 500,
  "code": "InternalError",
  "message": "Internal server error.",
  "resource": "my-new-bucket",
  "ibm_cos_request_id": "9f39ff2e-55d1-461b-a6f1-2d0b75138861"
}

Introduction

Endpoint URLs

Error handling

Authentication

Additional headers

Methods

Returns metadata for the specified bucket.

Authorization

Request

Path Parameters

bucket

Response

Response Body

name

crn

service_instance_id

service_instance_crn

time_created

time_updated

object_count

bytes_used

noncurrent_object_count

noncurrent_bytes_used

delete_marker_count

firewall

activity_tracking

metrics_monitoring

hard_quota

protection_management

Status Code

200

400

401

403

404

500

Make changes to a bucket's configuration.

Request

Custom Headers

If-Match

Path Parameters

bucket

Request Body

firewall

activity_tracking

metrics_monitoring

hard_quota

protection_management

Response

Status Code

200

400

401

403

404

412

500