Download Files with the Native API
    • Dark
      Light

    Download Files with the Native API

    • Dark
      Light

    Article Summary

    Downloading files using the Backblaze B2 Cloud Storage Native API is simple and straightforward.

    For all of the Backblaze API operations and their corresponding documentation, see API Documentation.

    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:

    1. The downloadUrl that is returned by b2_authorize_account
    2. /bucketName
    3. /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.


    Was this article helpful?