Use CLI to Create an Application

The following procedures demonstrate how to create an application using AWS command-line interface (AWS CLI).

Install the AWS CLI

Click AWS CLI installation instructions and follow the instructions for your operating system.

Configure AWS CLI

Follow this procedure to create a named profile to access Backblaze B2 Cloud Storage; this allows you to easily access Backblaze B2 and alternative Amazon Simple Storage Service (Amazon S3)-compatible cloud object stores. You can configure your default profile, set environment variables, or use any other configuration mechanism supported by the AWS CLI.

1. In Terminal, enter the following command to create a named profile for the AWS CLI to access your Backblaze B2 account: aws configure.
   1. Use the key ID and the application key that you created for the AWS access key ID and secret access key.
   2. Leave the default region name blank and set the default output format to json.

      $ aws configure --profile b2tutorial
      AWS Access Key ID [None]: <the key id you just created>
      AWS Secret Access Key [None]: <the application key you just created>
      Default region name [None]:
      Default output format [None]: json

2. Enter the following command to set the AWS Signature Version. Backblaze B2 supports AWS Signature Version 4.

   aws configure --profile b2tutorial set default.s3.signature_version s3v4

Since the AWS CLI does not allow you to save the endpoint configuration in a profile, you must specify the endpoint with the --endpoint-url option every time you use the CLI to access Backblaze B2.

The following error is returned if you do not specify the endpoint in an AWS command:

An error occurred (InvalidAccessKeyId) when calling the ListObjectsV3 operation: The AWS Access Key Id you provided does not exist in our records.

The following error is returned if you specify a valid Backblaze B2 endpoint that does not match your application key in an AWS command:

An error occurred (InvalidAccessKeyId) when calling the ListObjectsV3 operation: The key '' is not valid

You must specify the named profile with --profile b2tutorial each time you use the AWS CLI, for example:

aws –-profile b2tutorial --endpoint-url https://s3.us-west-004.backblazeb2.com s3api list-buckets

List Existing Buckets (CLI)

The simplest Amazon S3 action is 'List Buckets'. It requires no parameters and returns a list of all of the buckets within the account.

The AWS CLI contains two commands for working with Amazon S3 and compatible object stores such as Backblaze B2.

• s3api has subcommands that map directly to the Amazon S3 API.
• s3 is a custom set of subcommands that build on the API to provide higher levels of functionality.

This procedure uses the lower-level s3api since it allows greater control over the requests you send to Backblaze B2 and greater flexibility in outputting responses.

1. In a Terminal window, run the following command to list existing buckets in your Backblaze B2 account:

   aws –-profile b2tutorial --endpoint-url https://<your endpoint> s3api list-buckets

   Example:

   % aws --profile b2tutorial --endpoint-url https://s3.us-west-004.backblazeb2.com s3api list-buckets              
        {
          "Buckets": [
              {
                  "Name": "my-unique-bucket-name",
                  "CreationDate": "2022-07-20T21:09:06.528000+00:00"
              }
        ],
        "Owner": {
           "DisplayName": "",
           "ID": "3d81f678b843"
           }
   }

2. Enter the following command to show only the bucket names:

   % aws –-profile b2tutorial --endpoint-url https://s3.us-west-004.backblazeb2.com s3api list-buckets --query 'Buckets[].[Name]' --output text
   my-unique-bucket-name

   This technique lets you build powerful shell scripts to manipulate data in Backblaze B2.

Create a Private Bucket (CLI)

You already created a public bucket in the Backblaze web UI. Use this procedure to use the Amazon S3 'Create Bucket' action to create a private bucket programmatically.

1. In a terminal window, run the following command:

   aws --profile b2tutorial --endpoint-url https://<your endpoint> s3api create-bucket <another-unique-bucket-name>

   Example:

   % aws --profile b2tutorial --endpoint-url https://s3.us-west-004.backblazeb2.com s3api create-bucket --bucket another-unique-bucket-name --acl private

   An output similar to the following example is returned:

   {
       "Location": "/another-unique-bucket-name"
   }

   If the bucket already exists in another account, the following message is returned:

   An error occurred (BucketAlreadyExists) when calling the CreateBucket operation: Bucket name is already in use!

2. If no errors are returned, run the following command again:

   aws --profile b2tutorial --endpoint-url https://<your endpoint> s3api create-bucket <another-unique-bucket-name>

   The following message is returned:

   An error occurred (BucketAlreadyOwnedByYou) when calling the CreateBucket operation: Your previous request to create the named bucket succeeded and you already own it.

When you use the AWS command in a script, you can capture the error output and test for the presence of BucketAlreadyExists or BucketAlreadyOwnedByYou so your script can handle the error accordingly.

Use the following Bash example for macOS and Linux:

# Replace the bucket name with your own.
bucket_name=another-unique-bucket-name

# Create a new private bucket, capturing error output from the aws command
if error=$(aws --profile b2tutorial \
    --endpoint-url https://s3.us-west-004.backblazeb2.com \
    s3api create-bucket \
    --bucket ${bucket_name} 2>&1 1>/dev/null); then
  echo "Success! Created ${bucket_name}"
else
  if [[ "$error" == *"BucketAlreadyOwnedByYou"* ]]; then
    echo "You already created ${bucket_name}. \nCarrying on..."
  elif [[ "$error" == *"BucketAlreadyExists"* ]]; then
    echo "${bucket_name} already exists in another account.\nExiting."
  fi
fi

Upload a File to a Bucket (CLI)

In this final section of the tutorial, you will upload a file to the private bucket using the Amazon S3 'Put Object' action.

1. To upload a single file to your private bucket in Backblaze B2, run the following command:

   aws --profile b2tutorial --endpoint-url https://<your endpoint> s3api put-object --bucket <another-unique-bucket-name> --key <file-name-in-b2> --body /path/to/local-file

   Example:

   % aws --profile b2tutorial --endpoint-url https://s3.us-west-004.backblazeb2.com s3api put-object --bucket another-unique-bucket-name --key myimage.png --body ~/Pictures/myimage.png

   An output similar to the following example is returned.

   {
           "ETag": "\"78024721ce114961c53ddb2114e8759d\"",
      "VersionId": "4_z838d18a1bf8627788b280413_f10015013bc918a5f_d20220722_m234152_c004_v0402002_t0040_u01658533312064"
   }

Etag and VersionId Output (CLI)

The Etag value (represented in Boto3 as e_tag) identifies a specific version of the file's content. Etag is a standard HTTP header that is included when clients download files from Backblaze B2. Etag enables caches to be more efficient and save bandwidth because a web server does not need to resend a full response if the content was not changed. VersionId (version_id) identifies a specific version of the file within Backblaze B2. If a file is uploaded to an existing key in a bucket, a new version of the file is stored even if the file content is the same.

To see the difference between ETag and VersionId, run the 'upload file' commands a second time and upload the same file content to the same bucket and key. The ETag is the same since the content hasn't changed, but a new VersionId is returned.

An output similar to the following example is returned.

{
    "ETag": "\"78024721ce114961c53ddb2114e8759d\"",
    "VersionId": "4_z838d18a1bf8627788b280413_f1108c86b42292bdf_d20220722_m234154_c004_v0402002_t0058_u01658533314875"
}

Use the put-object command to upload a single file. You can use the AWS higher level s3 command to upload multiple files in a single command. For example, to copy all PNG files from ~/Pictures to a bucket, run the following command:

aws --profile b2tutorial --endpoint-url https://s3.us-west-004.backblazeb2.com s3 cp ~/Pictures s3://another-unique-bucket-name --recursive --exclude "*" --include "*.png"

Note: The --include and --exclude parameters can be tricky. Use the --dryrun option to verify that the command will run as you expect.

Browse Files (CLI)

In the Backblaze web UI, navigate to your private bucket on the Browse Files page. Your file is displayed with a (2) next to the filename.

If you click the (2), and click one of the file versions, you will see that the Fguid matches the VersionId that was returned when the file was created.

There is also no File Info for this file. The Backblaze web UI set the src_last_modified_millis attribute for the file that you uploaded earlier, but you did not specify one when you uploaded the file.

Click one of the URLs to open it in the browser. You cannot access the file because it is in a private bucket. The S3-Compatible API returns the following XML-formatted error for theAmazon S3 URL.

<Error>
    <Code>UnauthorizedAccess</Code>
    <Message>bucket is not authorized: another-unique-bucket-name</Message>
</Error>

The Native API returns a similar, JSON-formatted error for the Native and Friendly URLs:

{
  "code": "unauthorized",
  "message": "",
  "status": 401
}