Module file

Expand description

Backblaze B2 API calls for working with files.

See the B2 documentation on uploading files for an overview of the process.

§Uploading Files

For files larger than 5 GB, see Uploading Large Files.

To upload a file:

Authenticate with B2 to obtain an Authorization object.
Create an UploadFile request.
Call get_upload_authorization to get an UploadAuthorization for a bucket.
Call upload_file with your UploadAuthorization, UploadFile request, and file data.

You can upload multiple files with a single UploadAuthorization, but only one at a time. To upload multiple files in parallel, each thread or task needs to obtain its own UploadAuthorization.

§Uploading Large Files

To upload a large file:

Authenticate with B2 to obtain an Authorization object.
Create a StartLargeFile object with the destination bucket and new file’s information, then pass it to start_large_file. You will receive a File object.
Pass the File to get_upload_part_authorization to receive an UploadPartAuthorization.
- You can upload parts in separate threads for better performance; each thread must call get_upload_part_authorization and use its respective authorization when uploading data.
Create an UploadFilePart object via the UploadFilePartBuilder.
Use the UploadPartAuthorization and UploadFilePart to call upload_file_part with the file data to upload.
Call UploadFilePart::create_next_part to create a new upload part request.
Repeat steps 5 and 6 until all parts have been uploaded.
Call finish_large_file_upload to merge the file parts into a single File. After finishing the file, it can be treated like any other uploaded file.

§Examples

use std::env;
use anyhow;
use b2_client::{self as b2, HttpClient as _};

async fn upload_file(name: &str, bucket: b2::Bucket, data: &[u8])
-> anyhow::Result<b2::File> {
    let key = env::var("B2_KEY").ok().unwrap();
    let key_id = env::var("B2_KEY_ID").ok().unwrap();

    let client = b2::client::SurfClient::default();
    let mut auth = b2::authorize_account(client, &key, &key_id).await?;

    let mut upload_auth = b2::get_upload_authorization(&mut auth, &bucket)
        .await?;

    let checksum = calculate_sha1(&data);

    let file = b2::UploadFile::builder()
        .file_name(name)?
        .sha1_checksum(&checksum)
        .build()?;

    Ok(b2::upload_file(&mut upload_auth, file, &data).await?)
}

use std::env;
use anyhow;
use b2_client::{self as b2, HttpClient as _};

async fn upload_large_file(
    name: &str,
    data_part1: &[u8],
    data_part2: &[u8],
) -> anyhow::Result<b2::File> {
    let key = env::var("B2_KEY").ok().unwrap();
    let key_id = env::var("B2_KEY_ID").ok().unwrap();

    let client = b2::client::SurfClient::default();
    let mut auth = b2::authorize_account(client, &key, &key_id).await?;

    let file = b2::StartLargeFile::builder()
        .bucket_id("some-bucket-id")
        .file_name(name)?
        .content_type("text/plain")
        .build()?;

    let file = b2::start_large_file(&mut auth, file).await?;

    let mut upload_auth = b2::get_upload_part_authorization(
        &mut auth,
        &file
    ).await?;

    // Assuming a `calculate_sha1` function is defined:
    let sha1 = calculate_sha1(&data_part1);
    let sha2 = calculate_sha1(&data_part2);

    let upload_req = b2::UploadFilePart::builder()
        .part_sha1_checksum(&sha1)
        .build();

    let _part1 = b2::upload_file_part(
        &mut upload_auth,
        &upload_req,
        &data_part1,
    ).await?;

    let upload_req = upload_req.create_next_part(Some(&sha2))?;

    let _part2 = b2::upload_file_part(
        &mut upload_auth,
        &upload_req,
        &data_part2,
    ).await?;

    Ok(b2::finish_large_file_upload(
        &mut auth,
        &file,
        &[sha1, sha2],
    ).await?)
}

Structs§

ByteRange: A byte-range to retrieve a portion of a file.
CacheControl: A Cache-Control header.
CancelledFileUpload: A large file that was cancelled prior to upload completion.
ContentEncoding: Specify the compression algorithm.
CopyFile: A request to copy a file from a bucket, potentially to a different bucket.
CopyFileBuilder: A builder to create a CopyFile request.
CopyFilePart: A request to copy from an existing file to a part of a large file.
CopyFilePartBuilder: A builder to create a CopyFilePart request.
DeletedFile
DownloadAuthorization: A capability token that authorizes downloading files from a private bucket.
DownloadAuthorizationRequest: A request to obtain a DownloadAuthorization.
DownloadAuthorizationRequestBuilder: A builder to create a DownloadAuthorizationRequest.
DownloadFile: A request to download a file or a portion of a file from the B2 API.
DownloadFileBuilder
Expires: HTTP Expires header
File: Metadata of a file stored in B2.
FileLegalHold: Determines whether there is a legal hold on a file.
FilePart: A part of a large file currently being uploaded.
FileRetention: The retention settings for a file.
FileRetentionSetting: Sets the file retention mode and date/time during which the retention rule applies.
ListFileNames: A request to list the names of files stored in a bucket.
ListFileNamesBuilder: A builder for a ListFileNames request.
ListFileParts
ListFilePartsBuilder
ListFileVersions: A request to list the names of files stored in a bucket.
ListFileVersionsBuilder: A builder for a ListFileVersions request.
ListUnfinishedLargeFiles
ListUnfinishedLargeFilesBuilder
Mime: An IANA media type.
StartLargeFile: A request to prepare to upload a large file.
StartLargeFileBuilder: A builder for a StartLargeFile request.
UpdateFileLegalHold: A request to enable or disable a legal hold on a specific file.
UpdateFileLegalHoldBuilder: A builder for an UpdateFileLegalHold request.
UpdateFileRetention: A request to update file retention settings on a file.
UpdateFileRetentionBuilder: A builder for an UpdateFileRetention request.
UploadAuthorization: An authorization to upload a file to a B2 bucket.
UploadFile: A request to upload a file to B2.
UploadFileBuilder: A builder to create an UploadFile request.
UploadFilePart: A request to upload part of a large file.
UploadFilePartBuilder: A builder for an UploadFilePart request.
UploadPartAuthorization: An authorization to upload file contents to a B2 file.

Enums§

BypassGovernance: Declare whether to bypass file lock restrictions when performing an action on a File.
DownloadAuth: Allow downloading files via an Authorization or DownloadAuthorization.
FileAction: The action taken that resulted in a File object returned by the B2 API.
MetadataDirective: Describe the action to take with file metadata when copying a file.

Functions§

cancel_large_file: Cancel the uploading of a large file and delete any parts already uploaded.
cancel_large_file_by_id: Cancel the uploading of a large file and delete any parts already uploaded.
copy_file: Copy an existing file to a new file, possibly on a different bucket.
copy_file_part: Copy from an existing file to a new large file.
delete_file_version: Delete a version of a file.
delete_file_version_by_name_id: Delete a version of a file.
download_file: Download a file from the B2 service.
download_file_headers: Retrieve the headers that will be returned when the specified file is downloaded.
download_file_headers_by_id: Retrieve the headers that will be returned when the specified file is downloaded.
finish_large_file_upload: Complete the upload of a large file, merging all parts into a single File.
finish_large_file_upload_by_id: Complete the upload of a large file, merging all parts into a single File.
get_download_authorization: Generate a download authorization token to download files with a specific prefix from a private B2 bucket.
get_file_info: Retrieve metadata about a file stored in B2.
get_upload_authorization: Obtain an authorization to upload files to a bucket.
get_upload_authorization_by_id: Obtain an authorization to upload files to a bucket.
get_upload_part_authorization: Get an UploadPartAuthorization to upload data to a new B2 file.
get_upload_part_authorization_by_id: Get an UploadPartAuthorization to upload data to a new B2 file.
hide_file: Hide a file so that it cannot be downloaded by name.
hide_file_by_name: Hide a file so that it cannot be downloaded by name.
list_file_names: Get a list of file names in a bucket.
list_file_parts: List the parts of a large file that has not yet been completed.
list_file_versions: List all versions of the files contained in a bucket.
list_unfinished_large_files: Get a list of the unfinished large files stored by B2.
start_large_file: Prepare to upload a large file in multiple parts.
update_file_legal_hold: Enable or disable a legal hold on a file.
update_file_retention: Modify the file lock retention settings for a file.
upload_file: Upload a file to a B2 bucket.
upload_file_part: Upload a part of a large file to B2.