Developer Quick-Start Guide
    • Dark
      Light

    Developer Quick-Start Guide

    • Dark
      Light

    Article summary

    Use this guide to build applications that use Backblaze B2 Cloud Storage in thirty minutes or less using the S3-Compatible API even if you do not have experience working with cloud object storage.

    Overview

    Backblaze B2 is public cloud object storage with an S3-Compatible API, so you can configure almost any application, tool, or SDK designed for Amazon Simple Storage Service (Amazon S3).

    As well as its S3-Compatible API, Backblaze B2 provides its own Native API. Most of the native API operations are equivalent to Amazon S3 actions. There are a few native API calls for Backblaze B2-specific functionality, but the S3-Compatible API has everything that most applications need. In fact, the majority of existing applications and tools that were originally written against Amazon S3 work with Backblaze B2's S3-Compatible API.

    Enable B2 Cloud Storage

    Before you begin: You must have a Backblaze B2 Cloud Storage account. If you already have a Backblaze account and the left navigation menu contains a B2 Cloud Storage section, your account is already enabled for Backblaze B2.

    1. Sign in to the Backblaze web console.
    2. In the user menu in the upper-right corner of the page, select My Settings.
    3. Under Enabled Products, select the checkbox to enable B2 Cloud Storage.
    4. Review the Terms and Conditions, and click OK to accept them. 

    Create a Bucket

    1. Sign in to the Backblaze web console.
    2. In the left navigation menu under B2 Cloud Storage, click Buckets.
    3. Click Create a Bucket.
    4. Enter a name for your bucket. Bucket names must be at least six characters and globally unique.
      A message is displayed if your bucket name is already in use.
    5. Select a privacy setting: Private or Public. Files that are in a private bucket require authentication to perform an action, for example, downloading. Public buckets do not require authentication so you can easily share files. You can change a bucket's privacy settings at any time.
    6. If applicable, enable a Backblaze B2 server-side encryption key.
    7. Enable Object Lock to restrict a file from being modified or deleted for a specified period of time.
    8. Click Create a Bucket, and copy the value that is in the Endpoint field; you will need this value later.
    9. Click Lifecycle Settings to control how long to keep the files in your new bucket.

    The file lifecycle configuration defaults to keep all versions of the files. This is in contrast to Amazon S3, which disables versioning on newly created buckets.

    Upload a File

    You can upload files to a Backblaze B2 bucket from your local drive. The maximum single file size that you can upload through the Backblaze web console is 500 MB. If you need to upload larger files, click here for more information. You can also use the B2 Native API or the Command-Line Interface to upload files.

    1. Sign in to the Backblaze web console.
    2. In the left navigation menu under B2 Cloud Storage, click Buckets.
    3. In your bucket details, click Upload/Download and click Upload.
    4. Drop your images from your local drive into the dialog box, or manually select your files.
    5. In the left navigation menu under B2 Cloud Storage, click Browse Files to see your uploaded file and click the image filename to see more details.

    File Details

    You can view the following details after your file is uploaded.

    NameFile name
    Bucket NameUnique bucket name
    Bucket TypeFile visibility in Backblaze B2 is set on the bucket rather than the file. Possible values are private and public.
    If you set this value to public, the file is accessible using any of the three URLs without any credentials. Public buckets are never publicly writable; only publicly readable. You need appropriate credentials to upload files to the bucket.
    If you set this value to false, only the bucket owner can access the bucket.
    Friendly URL
    S3 URL
    Native URL
    If your bucket is public, you can click any of these three URLs to view the image. In general, it is easiest to use the Amazon S3 URL in the format https://<bucket name>.<endpoint>/<file name>.
    KindType of file, for example, image/png
    SizeFile size, for example, 79.6 KB
    UploadedDate and time the file was uploaded
    FguidFile version's unique identifier within Backblaze B2. This is the same value that is in the fileId query parameter in the Native URL.
    Sha1SHA-1 digest of the file content. The digest is useful to verify that the file was not corrupted in transmission.
    File InfoSet of up to 10 key-value pairs that hold user-defined metadata for the file. In the following example, the Backblaze web UI set src_last_modified_millis to the last modified time of the uploaded file on your local drive, a few minutes before it was uploaded.
    src_last_modified_millis: 123456789123 (12/15/2022 14:04)
    File Information corresponds to Amazon S3's user-defined object metadata. It is returned with x-amz-meta- prefixed HTTP headers when getting the file using its Amazon S3 URL:
    % curl -I
    https://my-unique-bucket-name.s3.us-west-004.backblazeb2.com/my-sample-image.png
    HTTP/1.1 200
    Accept-Ranges: bytes
    Last-Modified: Wed, 20 Jul 2022 21:18:44 GMT
    ETag: "94ef3ecd9772a6dd5d4bdaebddce6a16"
    x-amz-meta-src_last_modified_millis: 1658351049017
    x-amz-request-id: a2286d690971ff97
    x-amz-id-2: aM7Vk6DhsMVhmSTaDN1g4DmI7OB80nzMB
    x-amz-version-id: 4_ze30d68217f1617d88b280413_f10477368fe8fd6f1_d20220720_m211844_c004_v0402004_t0001_u01658351924129
    Content-Type: image/png
    Content-Length: 79571
    Date: Wed, 20 Jul 2022 22:07:18 GMT
    EncryptionThis is the value that you saved above.

    Create an Application Key

    Application keys control access to your Backblaze B2 Cloud Storage account and the buckets that are contained in your account.

    1. Sign in to the Backblaze web console.
    2. In the left navigation menu under B2 Cloud Storage, click Application Keys.
    3. Click Add a New Application Key, and enter an app key name.
      You cannot search an app key by this name; therefore, app key names are not required to be globally unique.
    4. Select All or a specific bucket in the Allow Access to Bucket(s) dropdown menu.
    5. Optionally, select your access type (Read and Write, Read Only, or Write Only).
    6. Optionally, select the Allow List All Bucket Names checkbox (required for the B2 Native API b2_list_buckets and the S3-Compatible API S3 List Buckets operations).
    7. Optionally, enter a file name prefix to restrict application key access only to files with that prefix. Depending on what you selected in step #4, this limits application key access to files with the specified prefix for all buckets or just the selected bucket.
    8. Optionally, enter a positive integer to limit the time, in seconds, before the application key expires. The value must be less than 1000 days (in seconds).
    9. Click Create New Key, and note the resulting keyID and applicationKey values.
    Note
    When you create a new app key, the response contains the actual key string, for example N2Zug0evLcHDlh_L0Z0AJhiGGdY. You can always find the keyID on this page, but for security, the applicationKey appears only once. Make sure you copy and securely save this value elsewhere.

    A *keyID* is typically similar to a secret access key or an access key ID. An *application Key* is similar to a password.

    Create Applications to Access Backblaze B2

    You can use AWS developer tools to access Backblaze B2 programmatically. The following guides provide procedures to install, configure, and create applications using the AWS Command-Line Interface (CLI), AWS SDK for Java, or AWS SDK for Python:

    Additional Resources

    You can do more with Backblaze B2:

    • Set up CORS rules to allow scripts to access files across HTTP origin boundaries.
    • Use lifecycle rules to automatically delete hidden files.
    • Use Object Lock to prevent files from being deleted during a configurable retention period.

    Was this article helpful?