Retrieve Bucket Metadata

Edit online

This API covers how to retrieve bucket metadata

Base Command :

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

A GET issued to a bucket metadata resource will return the metadata for that bucket.

Response

This operation does not make use of operation specific headers, query parameters, or payload elements

Table 1. Response Parameters
Response Parameter Style Type Description Optional or Mandatory
X-Timestamp Header String The date and time in UNIX Epoch time stamp format when the container was initially created for current version. Mandatory
storage_location Body String Refer to the "provisioning code" in the vault mode, this is typically used as "location" in cloud mode. Mandatory
name Body String The name of the bucket. Mandatory
service_instance Body String

The service instance tor storage account id for the account that owns the bucket.

 Mandatory
acl Body Object

A JSON map of grantees and their permissions on the bucket. Does not return the object if no content is defined.

See Table 2.

 Optional
retention_policy Body Object

Refers to the protection configuration of the bucket which is set through S3 Extension command PUT bucket?protection. If bucket protection configuration is not set, then return the protection configuration configured for the Container Vault if it exists.

See: Table 3.

 Optional
cors Body Array The bucket's Cross-Origin Resource Sharing (CORS) configuration objects. See: Table 4 for CORS configuration Objects. Optional
hard_quota Body String Container hard quota bytes in positive value. When this is not provided, it returns 0 - there is no quota restriction on the bucket. To remove the quota, set the value to 0. Format BigInteger. Mandatory
firewall Body Object
Firewall information including IP access control. When it is not defined, the object is not visible.
Note: Although an integer "format" that is associated to the fields supported in the firewall object, and is stored in the metadata, it is not exposed to end user.

See: Table 5.

 Optional
container_encryption Body Object An object that defines bucket encryption information. Specifically, kms endpoints.

See: Table 6.

 Optional
notifications Body Object

Notifications configuration for the container.

Note: This object is valid in on-premises cloud Container Mode only.

When the Operator has configured the container vault to specify the notification topic for the container using the Service API, the specified notifications configuration is applied to object-change events in the container when the Notification Service is enabled. 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.

If the container vault is configured to use the notification topic specified at the container vault, then the configuration in this object shall not be applied to object-change events and the container vault's topic is used to publish notifications.

If the container vault is configured such that a Notification Service is not assigned to the container vault, then the configuration in this object is not applied and notifications is disabled for the container.

See: Table 7

 Optional
public_access_block_configuration Body Object An object that defines whether the public ACLs are blocked.

If this field is not present, then public access is permitted for a bucket created using this template, when the bucket or its objects are configured to permit public read.

Table 8

  
time_created Body String The creation time of the bucket in RFC 3339 format. Format “date-time” Mandatory
time_updated Body String The modification time of the bucket in RFC 3339 format. Format “date-time” Mandatory
versioning_state Body String Disabled|Suspended|Enabled  
has_lifecycle Body String Refers to if the bucket has a Lifecycle Policy configured or not. Valid values are Present (lifecycle configuration is present on the bucket) or Not Present (lifecycle configuration is not present on the bucket). If both the Expiration and the Archive features are disabled, the has_lifecycle field will be omitted in the response. Optional
static_website Body Object An object that defines the Website Configuration of the bucket. The static_website field is not affected by feature enablement. The value of this parameter will only be visible if a website configuration is Present on the bucket. See: Table 9 Optional
object_lock_configuration Body Object The Object Lock configuration for the bucket. See: Table 15 Optional
has_replication Body String Whether this bucket has replication configured. Present value indicates that replication is configured. Not Present indicates otherwise. Mandatory
Table 2. Each item of the JSON MAP for the ACL (response) Parameter
Parameter Type Description
grantee String The storage account id or service instance granted the permission.
permission Array The list of string of permissions for the grantee as READ, WRITE, READ_ACP, WRITE_ACP and FULL_CONTROL.
Table 3. Retention_Policy (response) Parameter
Parameter Type Description Format
default_retention String The default period int64
maximumRetention String The maximum period int64
minimum_retention String The minimum period int64
permanent_retention_enabled Boolean Retain until explicitly cleared. Default: False
status String Retention status. Valid values are: COMPLIANCE, RETENTION, or DISABLED.
Table 4. CORS (response) Parameter
Parameter Type Description Format
Origin String The list of Origins eligible to receive CORS response headers. Note: "*" is permitted in the list of origins, and means "any Origin" An array of string type
method String The list of HTTP methods on which to include CORS response headers, (GET, OPTIONS, POST, etc) Note: "*" means any method An array of string type
max_age_seconds Integer The value, in seconds, to return in the Access-Control-Max-Age header used in preflight responses. Int32
allowed_header String Headers you want the browser to be allowed to send. An array of string type
exposed_header String Identifies the response headers such as server-side-encryption, request-id etc that customers are able to access from their applications. An array of string type
Table 5. Firewall (response) Parameter
Parameter Type Description Format
allowed_ip Array 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 would be 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 IP v4 or IP V6 addresses in CIDR format
denied_ip Array 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 would be 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 IP v4 or IP V6 addresses in CIDR format.
allowed_network_type Array

Array of string of allowed network types applied during bucket creation. It is enforced on the request headers: x-forwarded-for and ibm-client-originating-ip. If network type is not present in either of the headers, then network type is assumed to be "public" for the IP address in that header.

If the array is empty, there is no restriction on the network_type. The allowed_network_type configuration takes precedence over the allowed_ip configuration for enforcement of firewall.

Internal Note:

"adn" corresponds to the IBM COS network type "direct" .

"service" corresponds to the IBM COS network type "private".

Array of allowed network types

Valid values (any combination of): private, public, direct
Table 6. KMS_Endpoints (response)
Parameter Type Description
public_kms_endpoint String

The public endpoint, in URL form, of the kms service; An empty endpoint ("") would remove the existing public endpoint stored in the container encryption md; At least one of the endpoints, public_kms_endpoint or private_kms_endpoint is required if kms_endpoints is included in the request.
private_kms_endpoint String The private endpoint, in URL form, of the kms service; An empty endpoint ("") would remove the existing private endpoint stored in the container encryption md; At least one of the endpoints, public_kms_endpoint or private_kms_endpoint is required if kms_endpoints is included in the request.
Table 7. 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 8. Public_Access_Block_Configuration (response)
Parameter Type Description Format
block_public_acls Boolean

This field controls public access for the container and its objects when access is set via S3 settings (canned-ACL, etc).

Blocking public access due to IAM policy (when no credentials are present) should be set in IAM.

false indicates that public access is permitted if the appropriate request is issued.

If the public_block_access_configuration is set to an empty block, then block_public_acls is set to false.

Note: Required, Optional

default: false

Response

Table 9. static_website (response)
Parameter Type Description Format
index_document_suffix String Name of the index document for the website.  
error_document_key String Name of the error document for the website  
redirect_all_requests Object Defines the redirect behavior for every request to the bucket’s website endpoint See: Table 10
routing_rules Array Rules that define when a redirect is applied and the corresponding redirect behavior Array of routing_rule. See: Table 11
Table 10. redirect_all_requests (response)
Parameter Type Description Format
hostname String Name of the host where requests are redirected.  
protocol String Protocol to use when redirecting requests. Valid values are http or https
Table 11. routing_rule (response)
Parameter Type Description Format
condition Object Defines a condition that must be met for a specified redirect to apply. See: Table 12.
redirect Object Defines redirect information to another host, another page or another protocol. In the event of an error a different error code to return can also be specified. See: Table 13.
Table 12. condition (response)
Parameter Type Description Format
key_prefix String Defines the object key name prefix when the redirect is applied.  
http_error_code Integer Defines an HTTP error code when the redirect is applied.  
Table 13. redirect (response)
Parameter Type Description Format
hostname String Hostname to use in the redirect request.  
protocol String Protocol to use when redirecting requests.  
http_redirect_code String Defines the HTTP redirect code to include in the response.  
replace_key_prefix_with String Defines object key prefix to use in the redirect request.  
replace_key_with String Defines the object key to use in the redirect request.  
Table 14. HTTP response codes
HTTP Response Code Description
200 OK The bucket metadata retrieval was successful.
400 Bad Request The bucket name is invalid.
401 Unauthorized The provided token is invalid or could not be verified.
403 Forbidden Access Denied
404 Not Found The specified bucket does not exist.
Table 15. object_lock_configuration (response)
Parameter Type Description Format
object_lock_enabled Boolean Indicates the enablement state of the Object Lock configuration for a container (true represents Enabled) 
format for Object Lock enabled without default retention:
  "object_lock_configuration": {
    "object_lock_enabled": true,
    "last_modified_time": "1666881399753"
  }
days Integer Valid range of value for days is 1 to 36500 

format for Object Lock enabled with default retention (time unit in days):
  "object_lock_configuration": {
    "days": 1,
    "mode": "COMPLIANCE, GOVERNANCE",
    "object_lock_enabled": true,
    "last_modified_time": "1666881399753"
  }
years Integer Valid range of value for years is 1 to 100 

format for Object Lock enabled with default retention (time unit in years):
  "object_lock_configuration": {
    "years": 1,
    "mode": "COMPLIANCE, GOVERNANCE",
    "object_lock_enabled": true,
    "last_modified_time": "1666881399753"
  }
mode String Only valid value for mode is “COMPLIANCE, GOVERNANCE”  
last_modified_time String Timestamp for most recent change to Object Lock Configuration Last modified time is an epoch time in ms.

Examples

Example: Retrieve bucket configuration in on-premises cloud (Bucket has notifications enabled)

Request
GET <accesser>:8338/container/my-bucket
Response
This example does not show the firewall since it is not configured.

HTTP/1.1 200 OK
Content-Length: 63
Content-Type: application/JSON; charset=utf-8
X-Trans-Id: tx8ea13a3a835544d8bebf1-0056eb522a
Date: Fri, 01 Jan 2021 00:56:10 GMT
X-Timestamp: 1537818417.22774
    {
        "storage_location":"us-south",
        "name":"my-bucket",
        "service_instance":"0050b1acd467454cbd693b279d72c3d2",
        "acl": { 
            "user1":[ "WRITE" ], 
            "user2":[ "FULL-CONTROL" ] 
        },
        "retention_policy": { 
            "minimum_retention":"3650", 
            "maximumRetention":"7300", 
            "default_retention":"3650", 
            "permanent_retention":false 
        }, 
        "cors": { 
            "max_age_seconds":"6000", 
            "method":["GET"], 
            "origin":"*.ibm.com", 
            "allowed_header": ["*"], 
            "expose_header":[ "x-amz-server-side-encryption", "x-maz-request-id" ] 
        ], 
        "notifications": { 
            "topic":"my-bucket_topic", 
        },
        "hard_quota":54975581388800,
        "time_created":"2019-04-12T00:56:10Z",
        "time_updated":"2019-04-12T00:56:10Z",
        "versioning_state": "Enabled",
        "static_website": {
            "index_document_suffix": "index.html",
            "error_document_key": "errors/my_error.html",
            "routing_rules": [ {
                "condition": {
                    "key_prefix": "foo/",
                    "http_error_code": 404
                    }
                "redirect": {
                    "replace_key_prefix_with": "bar/",
                    "replace_key_with": "something",
                    "http_redirect_code": 301,
                    "hostname": "ibm.com",
                    "protocol": "HTTP"
                }
            }
        ]
    }
}