- Print
- DarkLight
Download Files with the Native API
- Print
- DarkLight
Downloading files using the Backblaze B2 Cloud Storage Native API is simple and straightforward.
Download Files
There are two ways to download files. You can use the b2_download_file_by_id
operation to download a file if you have the file ID. Use the b2_download_file_by_name
operation if you have the file name. Both of these methods download only one file at a time.
Applications that intend 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 the files in the bucket (see b2_authorize_account
). Alternatively, you can use the b2_get_download_authorization
operation as an authorization token to access files with a specific filename prefix.
Errors that are returned from b2_download_file_by_id
and b2_download_file_by_name
are usually due to a bad request, or the request is unauthorized. Another cause of these errors may be because the file was previously deleted and can no longer be found.
- 400 Bad Request
bad_request
Returns a message that describes the issue.
- 401 Unauthorized
missing_auth_token
There is no Authorization header.bad_auth_token
The authorization token is not valid.expired_auth_token
The authorization token has expired.unauthorized
The authorization token that you 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.
Download Files by ID
Requests to b2_download_file_by_id
follow a typical pattern, but you must use the downloadUrl
instead of the apiUrl
that is returned by b2_authorize_account
.
The URL to download a file by ID looks like the following example:
https://f123.backblazeb2.com/b2api/v3/b2_download_file_by_id
Download Files by Name
The URL to download a file by name a GET request, and it is comprised of the following parts:
- The
downloadUrl
that is returned byb2_authorize_account
/
bucketName/
fileName
The download URL is similar to the following example:
$ curl https://f001.backblazeb2.com/file/photos/cats/kitten.jpg
The file is returned, as well as the information about the file including its SHA1 and MIME type in the HTTP headers.
List Files
You can call b2_list_file_names
to get a list of the files in a bucket, and call b2_list_file_versions
to list all of the versions of the files in a bucket. For more information, see File Versions.
View Uploaded Files
If you upload a file called cats/kitten.jpg
to a bucket called cute_pictures
, you can view the file in a browser with a URL that looks like the following example:
https://f001.backblazeb2.com/file/cute_pictures/cats/kitten.jpg
The first part of the URL is the download URL that is returned from the b2_authorize_account
call, /file/
, the bucket name, /
, and the file name.
Download in Parallel
You can use the URL and authorization token that are returned from the b2_authorize_account
operation by multiple downloading threads. You can download in parallel to increase overall throughput.
Unauthorized Errors
You are not able to view the URLs for files online from a bucket that is set to allPrivate
. If you use either the Friendly or Native URL from a file through the Backblaze web UI, and the following error is returned, you should check your bucket settings.
{
"code": "unauthorized",
"message": "unauthorized",
"status": 401
}
To use the Friendly or Native URLs for files through the Backblaze web UI, you must change your bucket setting to allPublic
. You can edit your bucket settings on the Buckets page of your account. Click Bucket Settings, and change the setting to allPublic.