Downloading

The B2 APIs are simple and straightforward, but there are still a few things that you need to look out for when writing code to download files.

Downloading Files

There are two ways to download files. b2_download_file_by_id, is used to download a file, given you have the file id, and b2_download_file_by_name using the file name. Both API's only download one file at a time.

Some buckets may be private and require you to have an authorization token to access files, see b2_authorize_account. Alternatively, you can use b2_get_download_authorization as an authorization token to access files with a specific filename prefix.

Some errors returned from b2_download_file_by_id and b2_download_file_by_name are usually because of a bad request, or the request is unauthorized. Otherwise, the file might have been previously deleted and can no longer be found.

  • Unable to make an HTTP connection, including connection timeout.
  • Status of 401 Unauthorized, and an error code of expired_auth_token
  • Status of 404 file_state_deleted/none/unknown or bucket does not exist , error code of not_found
  • Status of 416 the Range Header in the request is outside the size of the file content , error code range_not_satisfiable
  • Any HTTP status in the 5xx range, including 503 Service Unavailable

Other errors you may get while uploading are:

  • 400 Bad Request
    • bad_request - message will describe the problem
  • 401 Unauthorized
    • missing_auth_token - there is no Authorization header
    • bad_auth_token - the authorization token is not valid

Downloading in Parallel

The URL and authorization token that you get from b2_authorize_account can be used by only one thread at a time. If you want multiple threads running, each one needs to get its own auth token.

Cache-Control Policies

B2 allows you to configure Cache-Control policies on a bucket level. During the creation of a bucket or when updating a bucket, you can configure the policy by setting the Cache-Control in the Bucket Info. For general information about Bucket Info, see Buckets

When setting the policy the key must be Cache-Control, which is case-sensitive, and the value must be max-age=number, which specifies the number of seconds to cache the file.

Below is a java example of b2_create_bucket, where we set the cache policy for the bucket.

import java.io.*;
import java.util.*;
import java.net.HttpURLConnection;
import java.net.URL;

String apiUrl = ""; // Provided by b2_authorize_account
String accountId = ""; // Obtained from your B2 account page.
String accountAuthorizationToken = "";  // Provided by b2_authorize_account
HttpURLConnection connection = null;

try {
    URL url = new URL(apiUrl + "/b2api/v1/b2_create_bucket");
    connection = (HttpURLConnection)url.openConnection();
    connection.setRequestMethod("POST");
    connection.setRequestProperty("Authorization", accountAuthorizationToken);
    connection.setRequestProperty("Content-Type", "application/x-www-form-urlencoded");
    connection.setRequestProperty("charset", "utf-8");
    connection.setRequestProperty("Content-Length", Integer.toString(postData.length));
    connection.setDoOutput(true);
    DataOutputStream writer = new DataOutputStream(connection.getOutputStream());
    writer.write(
    "{" +
        "\"accountId\":\"" + accountId + "\"," +
        "\"bucketName\":\"photos\",
        \"bucketType\":\"allPrivate\",
        \"bucketInfo\": {\"Cache-Control\":\"max-age=600\"}"
    + "}"
        .getBytes(StandardCharsets.UTF_8));
} catch (Exception e) {
    e.printStackTrace();
} finally {
    connection.disconnect();
}

Upon downloading a file, the response headers will contain the policy set by the bucket. If the bucket has no policy set, the default is Cache-Control : max-age=0, no-cache, no-store. If the bucket has a setting, that will be used instead.