Contents x
Developer Quick-Start Guide
    • Print
    • Dark
      Light
    Contents

    Developer Quick-Start Guide

      • Print
      • 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. You can sign up here. 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 your Backblaze account.
      2. In the left navigation menu under Account, click 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 your Backblaze account.
      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 may need this value for other processes.
      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 UI 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 your Backblaze account.
      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, 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 your Backblaze account.
      2. In the left navigation menu under Account, 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. In the Allow Access to Bucket(s) dropdown menu, select All or a specific bucket.
      5. Select your access type (for example, Read and Write).
      6. Select the optional Allow List All Bucket Names checkbox (required for the Backblaze B2 S3-compatible API List Buckets operation).
      7. 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?
      Related articles
      What's Next