Buckets
The storage for your account is grouped into buckets. Each bucket is a container that holds files. You can think of buckets as the top-level folders in your B2 Cloud Storage account. There is no limit to the number of files in a bucket, but there is a limit of 100 buckets per account. Contact our Sales team if you need more than 100 buckets.
The API calls related to buckets are:
b2_create_bucket- creates a new bucket in your accountb2_delete_bucket- deletes one bucketb2_list_buckets- lists all buckets in your accountb2_update_bucket- updates the settings for a bucket
Warning: Do not include Protected Health Information (PHI) or Personally Identifiable Information (PII) in bucket names, object/file/folder names, or other metadata. Such metadata is not encrypted in a way that meets Health Insurance Portability and Accountability Act (HIPAA) protection requirements for PHI/PII data and is not generally encrypted in client-side encryption architectures.
Bucket Names
When you create a bucket, you get to pick the name for the bucket. The name you pick must be a unique name that has not been used before, by you or by anybody else. In other words - a bucket's name is globally unique.
Bucket names can consist
of upper-case letters, lower-case letters, numbers, and "-". No
other characters are allowed. Even though your bucket can have
upper-case letters, bucket names are case insensitive. A bucket
name must be at least 6 characters long, and can be at most 63
characters long. These are all allowed bucket names: myBucket,
backblaze-images, and bucket-74358734.
Bucket names that start with "b2-" are reserved for Backblaze use.
Access Controls
Access controls are simple. Uploads into a bucket always require authorization. Listing files in a bucket always requires authorization, and deleting files always requires authorization. For downloading files, though, you have the option of requiring authorization, or making all of the files in a bucket the files visible to the public.
The bucketType parameter on a bucket sets the access
permissions. Setting it to allPrivate means that every
download requires an authorization token. Setting it to allPublic
means that everybody is allowed to download the files in the bucket.
Note that when a bucket is allPublic, anybody can
download the files, but the downloads will still be charged against your
account. Each day, anything beyond the 1GB of downloads you get for free
will be charged to your account.
Bucket Info
You can add key/value pairs as custom information associated with the bucket. Each key is a UTF-8 string up to 50 bytes long, and can contain letters, numbers, and the following list of special characters: "-", "_", ".", "`", "~", "!", "#", "$", "%", "^", "&", "*", "'", "|", "+". Each key is converted to lowercase. Names that begin with "b2-" are reserved. There is an overall limit of 10,000 bytes for all of the values.
You can store bucket info when you create a bucket with
b2_create_bucket,
and then update the info later with
b2_update_bucket.
There is no limit on the size or content of the values, other than the overall size limit.
This is also where you can set the Cache-Control policy for buckets.
For example, if you wanted the client to cache files for 5 minutes,
you would add a name/value pair such as "Cache-Control" : "max-age=600";
from then on, when any files from this bucket are downloaded, the response
would contain the corresponding header. By default, if no Cache-Control policy
is set, all files downloaded from buckets created before September 8, 2021 have
a Cache-Control header value of "max-age=0, no-cache, no-store". All buckets
created on or after September 8, 2021 include no Cache-Control header by default
with file downloads.
Lifecycle Rules
Each bucket has a set of lifecycle rules that instruct B2 to hide or delete old versions of files.