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 APIs only download one file at a time.

Applications intending to use the RANGE header to multithread the download of files can use the more efficient HEAD request to fetch file information, as opposed to making an initial call to download a single byte.

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 because the request is unauthorized. Another cause of these errors is that the file was previously deleted and so 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 downloading 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 multiple downloading threads. You can download in parallel to increase overall throughput.

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.