Create bucket

Edit online

This sections describes bucket creation.

Base Command

PUT <accesser>:8338/container/{bucket.name}

A PUT issued to the container followed by a string that specifies the name of the bucket to be created. Bucket names must be unique. Bucket names must be DNS-compliant, i.e., 3 - 63 characters long and must be made of lower case letters, numbers, and dashes. Bucket names must begin and end with a lower case letter or number. Bucket names that resemble IP addresses are not allowed. This operation does not use operation-specific headers or query parameters.

Request

Table 1. Request Parameters
Request Parameter Style Required Type Description
storage_location Body Optional String Corresponding to the provisioning code of a container vault; it is also referred as the location of the container in the Cloud mode; when it is not provided, the default provisioning code from container vault template would be used. When this parameter is not provided in either, the request will be rejected with 400 HTTP error.
service_instance Body Required String The service instance or storage account id that owns the bucket.
acl Body Optional Object An array of pairs of grantee and permission. If there are multiple permissions for the same grantee, multiple entries are required.

Refer to table below called "ACL JSON (request)"
hard_quota Body Optional String Container hard quota in bytes, default 0 (no limit). Format BigInteger.
firewall Body Optional Object

The firewall restriction, includes allowed or denied IP addresses lists.

When the field is not specified in the request, it defaults to empty, i.e. no IP restriction at the bucket-level. In such a case, IP access control configured at the container vault level is applied to the bucket. If no IP access control specified for the container vault, then the bucket can be accessed from public IP.

Refer to table below called "Firewall (request)"
notifications Body Optional Object This object is valid in on-premises cloud Container Mode when the Operator has configured the container vault to specify the notification topic for the container using the Service API. If the notifications object is not present, then notifications is disabled for the container.

The Operator should use the Manager UI/REST API to determine the topic configuration setting for a container vault.

Refer to table below called Notifications (request)"
Table 2. ACL JSON (request)
Parameter Type Description
grantee String The Storage account ID or service instance granted to the permissions
permission String The permission for the grantee in the format of "READ", "WRITE, "READ_ACP", "WRITE_ACP" and "FULL_CONTROL"
Table 3. Firewall (request)
Parameter Type Description Format
allowed_ip String Array of string of allowed continuous non-overlapping IP address ranges for the container. If a request from a client IP that is not in this IP address list, the client request is rejected. When this parameter is not provided, the bucket is allowed to be accessed from IP address other than those in denied_ip list. If neither is provided, bucket is allowed to be accessed from any IP address Array of IPv4 or IPv6 addresses in CIDR format
denied_ip String Array of string of denied continuous non-overlapping IP address ranges for the container. If a request from a client IP that is in this IP address list, the client request is rejected. Denied IP addresses might be used together with allowed IP as the “excluded sub-range of IP address” from the allowed large IP address range. When this parameter is not provided, the bucket is allowed to be accessed from IP address defined in allowed_ip list. Array of IPv4 or IPv6 addresses in CIDR format
Table 4. Notifications (request)
Parameter Type Description Format
topic String

The topic on which the container's notifications shall be published.

Notification of object-change events are published on this topic of the Notification Service assigned to the container vault, if the Notification Service is enabled.

Only a single topic is supported for a container.

Note: Required, Yes if the notifications object is present

1-249 characters in length.

Valid characters: Alphanumeric, hyphen, period, underscore.

Response

Table 5. Response Parameters
Response Parameter Style Type Description
X-Timestamp  Head  String The date and time in UNIX Epoch time stamp format when the container was initially created for current version 
storage_location Body String The storage_location of the bucket or the provisioning code of the container vault.
name Body  String  The name of the bucket
service_instance Body String The service instance or storage account id that owns the bucket
acl Body Object A JSON map of grantees and their list of permissions on the bucket. It is not visible if content is not defined.
retention_policy Body String Bucket retention policy. Return JSON element with container vault “status” with value in format of enum of “ENABLED” | “DISABLED”
cors Body Object The bucket's Cross-Origin Resource Sharing (CORS) configuration; when it is not defined, the object is not visible.
hard_quota Body String Container hard quota bytes, default 0, no quota. Format BigInteger.
firewall Body Object Container IP access control restriction information. When it is not defined the object is not visible.
notifications Body Object Configuration of notifications for the container.

This object is optional and valid in On-Prem Container Mode only. If the notifications object is not present in the request, then notifications is disabled for this container.

Refer to table below called "Notifications (response) Parameter"
time_created Body String The creation time of the bucket in RFC 3339 format. Format “date-time”
time_updated Body String The modification time of the bucket in RFC 3339 format. Format “date-time”
Table 6. Notifications (response)
Parameter Type Description Format
topic String

The topic on which the container's notifications shall be published.

Notification of object-change events are published on this topic of the Notification Service assigned to the container vault, if the Notification Service is enabled.

Only a single topic is supported for a container.

Note: Required, Yes if the notifications object is present

1-249 characters in length.

Valid characters: Alphanumeric, hyphen, period, underscore.
Table 7. HTTP response code
HTTP Response Code Description
201 Created The bucket was properly created
400 Bad Request

Request contains too many request element, request timeout, duplicate request header/fields, invalid argument, the bucket is a vault, invalid hard_quota, invalid storage_location, malformed acl, firewall or JSON, UnresolvableGrantByEmailAddress, metadata too large, too many buckets, missing request body, invalid format for notifications object, notifications object present when container vault is not assigned to a Notification Service or is not set to configure the topic at the container, notifications object specified in cloud mode, Notifications Service is disabled, etc.

Detail error message is be provided on specific error.
401 Unauthorized The provided token is invalid or could not be verified.
403 Forbidden Access Denied
404 Not Found The specified account does not exist
409 Conflict Conflict from the ranges in IP restriction, or a conflict bucket creation is in progress.
500 Internal Server Error Internal Server Error

Examples

Example: Create bucket example without mutable parameters

Request

PUT <accesser>:8338/container/my-bucket
{ 
   "storage_location":"us-south", 
   "service_instance":"731fc6f265cd486d900f16e84c5cb594" 
}
Response

HTTP/1.1 201 CREATED
Content-Length: 263 
Content-Type: application/JSON; charset=utf-8 
X-Trans-Id: tx8ea13a3a835544d8bebf1-0056eb522a 
Date: Fri, 12 Apr 2019 00:56:10 GMT 
X-Timestamp: 1555083117.22774 
{ 
   "storage_location":"us-south", 
   "name":"my-bucket", 
   "service_instance":"731fc6f265cd486d900f16e84c5cb594", 
   "retention_policy":{ 
       "status":"DISABLED" 
   }, 
   "hard_quota":0, 
   "time_created":"2019-04-12T00:56:10Z", 
   "time_updated":"2019-04-12T00:56:10Z" 
}
Example: Create bucket command with ACL, IP, notifications, and quota Request

Request
{ 
   "storage_location":"us-south", 
   "service_instance":"731fc6f265cd486d900f16e84c5cb594", 
   "acl":[
      { 
       "grantee":"user1", 
       "permission":"WRITE"
      }
   ], 
   "hard_quota":107374182400, 
   "firewall":{ 
       "allowed_ip":[ "192.168.28.100/24", "192.168.25.200/32" ], 
       "denied_ip":[ "192.169.10.100/30" ] 
   },
   "notifications":{ 
      "topic":"my-bucket_topic" 
   }
}
Response
HTTP/1.1 201 CREATED 
Content-Length: 263 
Content-Type: application/JSON; charset=utf-8 
X-Trans-Id: tx8ea13a3a835544d8bebf1-0056eb522a 
Date: Fri, 12 Apr 2019 00:56:10 GMT 
X-Timestamp: 1555083117.22774 
{ 
   "storage_location":"us-south", 
   "name":"my-bucket", 
   "service_instance":"731fc6f265cd486d900f16e84c5cb594", 
   "acl":{ 
      "user1":[ "WRITE" ] 
    }, 
   "retention_policy":{ 
      "status":"DISABLED" 
    }, 
   "hard_quota":107374182400, 
   "firewall":{ 
     "allowed_ip":[ "192.168.28.100/24", "192.168.25.200/32" ], 
     "denied_ip":[ "192.169.10.100/30" ] 
    }, 
    "notifications":{ 
        "topic": "my-bucket_topic" 
    },
    "time_created":"2019-04-12T00:56:10Z", 
    "time_updated":"2019-04-12T00:56:10Z" 
}