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.
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.
-
400 Bad Request
bad_request
- message will describe the problem
-
401 Unauthorized
missing_auth_token
- there is no Authorization headerbad_auth_token
- the authorization token is not validexpired_auth_token
- the authorization token had expiredunauthorized
- the auth token used does not allow access to this file
-
404 Not Found
not_found
- the bucket or file does not exist
-
416 Range Not Satisfiable
range_not_satisfiable
- the request is outside the size of the file content
-
429 Too Many Requests
too_many_requests
- your account has too many concurrent downloads
-
5xx
- There is a problem in the service. Retry with exponential back-off.
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
policy 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.
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/v2/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 Cache-Control response header
will be set according to the Cache-Control policy in the
Bucket Info. If the bucket has no Cache-Control policy setting,
then the default behavior is determined by the creation time of
the bucket. All buckets created on or after September 8, 2021
have no default Cache-Control header included with file downloads.
Any buckets created before September 8, 2021 have a default Cache-Control
header value of "max-age=0, no-cache, no-store"
. The bucket's Cache-Control
policy setting (or default behavior) may also be overridden on a per-file basis
by specifying the X-Bz-Info-b2-cache-control
header at file upload time
(see b2_upload_file
).