Backblaze-B2V4
view release on metacpan or search on metacpan
Revision history for Perl extension Backblaze-B2V4
0.05 2026-08-03T01:25:33Z
- Add comment for the included testing key
0.04 2026-07-09T01:44:03Z
- Fix bug in retrieving results for b2_upload_file
- Show new guid for upload function in b2_client
- Small typo fixes
0.03 2026-07-01T03:27:57Z
- Fix cpanfile typos, so that Marlin installs
0.02 2026-06-10T03:14:08Z
- Improve documentation / add current_status_is_ok()
# create an API client object
my $b2 = Backblaze::B2V4->new(
application_key => $application_key,
application_key_id => $application_key_id,
);
# please encrypt/protect those keys when not in use!
# let's say we have a B2 bucket called 'GingerAnna' and a JPG called 'ginger_was_perfect.jpg'.
# upload a file from your file system
my $response = $b2->b2_upload_file(
bucket_name => 'GingerAnna',
file_location => '/path/to/ginger_was_perfect.jpg'
);
# upload a file you have in a scalar
my $response = $b2->b2_upload_file(
bucket_name => 'GingerAnna',
new_file_name => 'ginger_was_perfect.jpg',
file_contents => $file_contents
);
# B2 file ID (fGUID) is now in $response->{fileId}
# Best to load $file_contents via Path::Tiny's slurp_raw() method
# download that file to /opt/majestica/tmp
my $response = $b2->b2_download_file_by_name(
bucket_name => 'GingerAnna',
will need a key with Read and Write access. Be sure to note the Application Key
ID as well as the Application Key itself. They do not show you that Application
Key again, so copy it immediately.
Please store the Application Key pair in a secure way, preferably encrypted
when not in use by your software.
## b2\_client Command Line Utility
Backblaze::B2V4 includes the 'b2\_client' command line utility to
easily download or upload files from B2. Please execute 'b2\_client help'
for more details, and here are a few examples:
# download a file to current directory
b2_client get MyPictures FamilyPhoto.jpg
# download a file to a target directory
b2_client get MyPictures FamilyPhoto.jpg /home/ginger/photos
# upload a file to B2
b2_client put MyPictures /home/ginger/photos/AnotherFamilyPhoto.jpg
There is also an official command line utility from Backblaze that does a
whole lot more:
https://www.backblaze.com/b2/docs/quick_command_line.html
## BackBlaze B2 also has a S3-compatible API
Backblaze has added an S3-compatible API, which you can read about here:
## b2\_download\_file\_by\_name
Works like b2\_download\_file\_by\_id() except that it expects 'bucket\_name'
and 'file\_name' named arguments arguments.
If you would like to auto-save the file, provide a path to an
existing directory via the 'save\_to\_location' argument.
See https://www.backblaze.com/b2/docs/b2\_download\_file\_by\_name.html
## b2\_upload\_file
Uploads a new file into B2. Accepts these named arguments:
bucket_name => required, name of destination bucket,
content_type => optional mime type; defaults to b2/x-auto,
file_location => optional, full path of file to upload incl name
new_file_name => optional, filename for file on B2
file_contents => optional scalar with file contents
If you do not provide 'file\_location', then you need to provide
'new\_file\_name' and 'file\_contents' (or vice versa).
If you are going to use the 'file\_contents' method, it's best
to load the scalar using the 'slurp\_raw' method in Path::Tiny.
(I believe 'read\_file' in File::Slurp will work, but have yet to test.)
If successful, returns the GUID for the new file (aka the fileId); otherwise
returns 0.
See: https://www.backblaze.com/b2/docs/b2\_upload\_file.html
Example 1: Uploading from a file on disk:
my $file_id = $b2->b2_upload_file(
bucket_name => 'GingerAnna',
file_location => '/opt/majestica/tmp/ginger_was_perfect.jpg',
);
Example 2: Uploading when the file is loaded into a scalar:
my $file_id = $b2->b2_upload_file(
bucket_name => 'GingerAnna',
new_file_name => 'ginger_was_perfect.jpg',
file_contents => $file_contents
);
## b2\_upload\_large\_file
Uploads a large file into B2. Recommended for uploading files larger
than 100MB.
Example:
my $file_id = $b2->b2_upload_large_file(
bucket_name => 'GingerAnna',
file_location => '/opt/majestica/tmp/gingers_whole_life_story.mp4',
);
## b2\_list\_file\_info
Retrieves an arrayref hashrefs with file infomrmation for a bucket.
Backblaze calls if 'b2\_list\_file\_names' but it really is for file info.
Limited to 10,000 file results per call, so you will may need to
call repeatedly to retrieve all names.
Example:
my $success = $b2->b2_delete_bucket(
bucket_name => 'DeletingBucketName'
);
## b2\_delete\_file\_version
Deletes a version of a file, AKA a stored object. If you use unique
file names for each file you upload, then one version equals one file.
If you upload multiple files with the same name under a single bucket,
you will create multiple versions of a particular file in B2.
Required named args
file_name => the name of the file
file_id => the Backblaze GUID for the file
Returns 1 (success) or 0 (failure)
my $success = $b2->b2_delete_file_version(
my $bucket_id = $b2->b2_get_bucket_id(
bucket_name => 'MyBucketName',
auto_create_bucket => 0 or 1,
);
Pass 1 for 'auto\_create\_bucket' to make the bucket if one does not exist for your 'bucket\_name'
and return the new bucket ID. If you pass 0 for 'auto\_create\_bucket' and the bucket doesn't
exist, you will receive back a 0.
## b2\_get\_upload\_info
Almost all the API calls use the Account Authorization Token for the
authorization header, but the file uploader calls require a bucket-specific
token and upload URL. You can retrieve these via b2\_get\_upload\_info()
with the bucket name as an argument.
Example:
my $results = $b2->b2_get_upload_info(
bucket_name => 'MyBucketName'
);
The %$results hash now has 'upload\_url' and 'authorization\_token'
Note: You have to call b2\_get\_upload\_info on a bucket for each file
upload operation. My b2\_upload\_file method does that for you, so that's
just FYI if you roll your own.
See: https://www.backblaze.com/b2/docs/b2\_get\_upload\_info.html
## send\_request
send\_request() handles all the communications with B2.
You should be able to use this to make calls not explicitly
provided by this library.
If send\_request() gets a 200 HTTP status from B2, then the call went
great, $b2->current\_status\_is\_not\_ok will be 0, and
the JSON response will be returned.
B2 API V4 Docs: https://www.backblaze.com/apidocs/b2-authorize-account
Paws::S3 - If using Backblaze's S3-compatible API.
# AUTHOR / BUGS
Eric Chernoff <eric@weaverstreet.net> - Please send me a note with any bugs or suggestions.
ESTRABD <estrabd@cpan.org> - Enhanced b2\_list\_file\_names() to fully use options and a great bugfix
when using the 'file\_contents' option in the b2\_upload\_file() method.
# LICENSE
MIT License
Copyright (c) 2026 Eric Chernoff
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modi...
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
lib/Backblaze/B2V4.pm view on Meta::CPAN
package Backblaze::B2V4;
# API client library for V2 of the API to Backblaze B2 object storage
# Allows for creating/deleting buckets, listing files in buckets, and uploading/downloading files
use strict;
use warnings;
our $VERSION = "0.05";
use v5.38; # or higher
use Cpanel::JSON::XS;
use Digest::SHA qw(sha1_hex);
use HTTP::Tiny;
lib/Backblaze/B2V4.pm view on Meta::CPAN
# track the error / set current state
return $self->error_tracker(
'error_message' => "Problem logging into Backblaze. Please check the 'errors' array in this object.",
'url' => $args->url,
);
}
my $b2_response = {};
my $response;
# are we uploading a file?
if ($args->url =~ /b2_upload_file|b2_upload_part/) {
# now upload the file
eval {
$response = HTTP::Tiny->new->post($api_url, {
'headers' => $headers,
'content' => $args->file_contents
});
$b2_response = decode_json( $response->{content} );
};
# if not uploading and they sent POST params, we are doing a POST
} elsif ($args->post_params) {
eval {
$response = HTTP::Tiny->new->post($api_url, {
'headers' => $headers,
'content' => encode_json($args->post_params)
});
$b2_response = decode_json( $response->{content} );
};
# otherwise, we are attempting a GET
lib/Backblaze/B2V4.pm view on Meta::CPAN
$self->save_downloaded_file(
save_to_location => $args->save_to_location,
response => $response
);
}
# return file contents
return $response;
}
# method to upload a file into Backblaze B2
signature_for b2_upload_file => (
method => true,
named => [
new_file_name => NonEmptyStr, { optional => true },
bucket_name => NonEmptyStr,
content_type => Str, { optional => true, default => 'b2/x-auto' },
file_location => Str, { optional => true },
file_contents => Value, { optional => true },
],
returns => Bool|Str,
);
sub b2_upload_file ($self, $args) {
# send the file contents?
my $file_contents = $args->file_contents;
my $new_file_name = $args->new_file_name;
# did they provide a file location or path?
if (!$file_contents && $args->file_location && -e $args->file_location) {
$file_contents = path( $args->file_location )->slurp_raw;
# if they didn't provide a file-name, use the one on this file
if (!$new_file_name) {
$new_file_name = path( $args->file_location )->basename;
}
}
if (!$file_contents) {
return $self->error_tracker(
'error_message' => qq{You must provide either a valid 'file_location' or 'file_contents' arg for b2_upload_file()},
'url' => 'b2_upload_file',
);
}
if (!$new_file_name || !$args->bucket_name) {
return $self->error_tracker(
'error_message' => qq{You must provide 'bucket_name' and 'new_file_name' args for b2_upload_file().},
'url' => 'b2_upload_file',
);
}
my $content_type = $args->content_type || 'b2/x-auto';
my $upload_info = $self->b2_get_upload_info( bucket_name => $args->bucket_name );
if (!$upload_info) {
return 0;
}
# send the special request
my $response = $self->send_request(
'url' => $upload_info->{upload_url},
'authorization' => $upload_info->{authorization_token},
'file_contents' => $file_contents,
'headers' => {
'X-Bz-File-Name' => uri_escape( $new_file_name ),
'X-Bz-Content-Sha1' => sha1_hex( $file_contents ),
'Content-Type' => $content_type,
},
);
return $self->current_status_is_not_ok ? 0 : $response->{fileId};
}
# method to get the information needed to upload into a specific B2 bucket
signature_for b2_get_upload_info => (
method => true,
named => [
bucket_name => NonEmptyStr,
],
returns => HashRef|Bool,
);
sub b2_get_upload_info ($self, $args) {
my $response = $self->send_request(
'url' => 'b2_get_upload_url',
'post_params' => {
'bucketId' => $self->b2_get_bucket_id(
'bucket_name' => $args->bucket_name,
),
},
);
if (!$response) {
return 0;
}
return {
'upload_url' => $response->{uploadUrl},
'authorization_token' => $response->{authorizationToken},
};
}
signature_for b2_get_bucket_id => (
method => true,
named => [
bucket_name => NonEmptyStr,
auto_create_bucket => Bool, { optional => true, default => true },
],
lib/Backblaze/B2V4.pm view on Meta::CPAN
'url' => 'b2_delete_file_version',
'post_params' => {
'fileName' => $args->file_name,
'fileId' => $args->file_id,
},
);
return $self->current_status_is_not_ok ? 0 : 1;
}
# method to upload a large file (>100MB)
signature_for b2_upload_large_file => (
method => true,
named => [
new_file_name => NonEmptyStr,
bucket_name => NonEmptyStr,
file_location => NonEmptyStr,
content_type => NonEmptyStr, { optional => true, default => 'b2/x-auto' },
],
returns => Bool|Str,
);
sub b2_upload_large_file ($self, $args) {
# did they provide a file location or path?
if ($args->file_location && -e $args->file_location) {
# if they didn't provide a file-name, use the one on this file
$args->new_file_name = path( $args->file_location )->basename;
} else {
return $self->error_tracker(
'error_message' => "You must provide a valid 'file_location' arg for b2_upload_large_file().",
);
}
# must be 100MB or bigger
my $stat = path($args->file_location)->stat;
if ($stat->size < $self->api_info->{recommended_part_size} ) {
return $self->error_tracker(
'error_message' => 'Please use b2_upload_large_file() for files larger than ' . $self->api_info->{recommended_part_size},
);
}
# default content-type
$args->content_type ||= 'b2/x-auto';
my $bucket_id = $self->b2_get_bucket_id($args->bucket_name);
if (!$bucket_id) {
return $self->error_tracker(
'error_message' => 'Can not upload to ' . $args->bucket_name . ' because bucket not found.',
);
}
# kick off the upload in the API
my $response = $self->send_request(
'url' => 'b2_start_large_file',
'post_params' => {
'bucketId' => $bucket_id,
'fileName' => $args->new_file_name,
'contentType' => $args->content_type,
},
);
# these are all needed for each b2_upload_part web call
my $large_file_id = $response->{fileId};
if (!$bucket_id) {
return $self->error_tracker(
'error_message' => 'Error in b2_upload_large_file for ' . $args->new_file_name,
);
}
# open the large file
open(my $fh, $args->file_location);
my $remaining_file_size = $stat->size;
my $part_number = 1;
# cycle thru each chunk of the file
my $size_sent = 0;
my @sha1_array = ();
while ($remaining_file_size >= 0) {
# how much to send?
if ($remaining_file_size < $self->{recommended_part_size} ) {
$size_sent = $remaining_file_size;
} else {
$size_sent = $self->apit_info->{recommended_part_size};
}
# get the next upload url for this part
$self->send_request(
'url' => 'b2_get_upload_part_url',
'post_params' => {
'fileId' => $large_file_id,
},
);
# read in that section of the file and prep the SHA
my $file_contents_part;
sysread $fh, $file_contents_part, $size_sent;
push(@sha1_array, sha1_hex( $file_contents_part ));
# upload that part
$self->send_request(
'url' => $response->{uploadUrl},
'authorization' => $response->{authorizationToken},
'headers' => {
'X-Bz-Content-Sha1' => $sha1_array[-1],
'X-Bz-Part-Number' => $part_number,
'Content-Length' => $size_sent,
},
'file_contents' => $file_contents_part,
);
# advance
lib/Backblaze/B2V4.pm view on Meta::CPAN
# create an API client object
my $b2 = Backblaze::B2V4->new(
application_key => $application_key,
application_key_id => $application_key_id,
);
# please encrypt/protect those keys when not in use!
# let's say we have a B2 bucket called 'GingerAnna' and a JPG called 'ginger_was_perfect.jpg'.
# upload a file from your file system
my $response = $b2->b2_upload_file(
bucket_name => 'GingerAnna',
file_location => '/path/to/ginger_was_perfect.jpg'
);
# upload a file you have in a scalar
my $response = $b2->b2_upload_file(
bucket_name => 'GingerAnna',
new_file_name => 'ginger_was_perfect.jpg',
file_contents => $file_contents
);
# B2 file ID (fGUID) is now in $response->{fileId}
# Best to load $file_contents via Path::Tiny's slurp_raw() method
# download that file to /opt/majestica/tmp
my $response = $b2->b2_download_file_by_name(
bucket_name => 'GingerAnna',
lib/Backblaze/B2V4.pm view on Meta::CPAN
will need a key with Read and Write access. Be sure to note the Application Key
ID as well as the Application Key itself. They do not show you that Application
Key again, so copy it immediately.
Please store the Application Key pair in a secure way, preferably encrypted
when not in use by your software.
=head2 b2_client Command Line Utility
Backblaze::B2V4 includes the 'b2_client' command line utility to
easily download or upload files from B2. Please execute 'b2_client help'
for more details, and here are a few examples:
# download a file to current directory
b2_client get MyPictures FamilyPhoto.jpg
# download a file to a target directory
b2_client get MyPictures FamilyPhoto.jpg /home/ginger/photos
# upload a file to B2
b2_client put MyPictures /home/ginger/photos/AnotherFamilyPhoto.jpg
There is also an official command line utility from Backblaze that does a
whole lot more:
https://www.backblaze.com/b2/docs/quick_command_line.html
=head2 BackBlaze B2 also has a S3-compatible API
Backblaze has added an S3-compatible API, which you can read about here:
lib/Backblaze/B2V4.pm view on Meta::CPAN
=head2 b2_download_file_by_name
Works like b2_download_file_by_id() except that it expects 'bucket_name'
and 'file_name' named arguments arguments.
If you would like to auto-save the file, provide a path to an
existing directory via the 'save_to_location' argument.
See https://www.backblaze.com/b2/docs/b2_download_file_by_name.html
=head2 b2_upload_file
Uploads a new file into B2. Accepts these named arguments:
bucket_name => required, name of destination bucket,
content_type => optional mime type; defaults to b2/x-auto,
file_location => optional, full path of file to upload incl name
new_file_name => optional, filename for file on B2
file_contents => optional scalar with file contents
If you do not provide 'file_location', then you need to provide
'new_file_name' and 'file_contents' (or vice versa).
If you are going to use the 'file_contents' method, it's best
to load the scalar using the 'slurp_raw' method in Path::Tiny.
(I believe 'read_file' in File::Slurp will work, but have yet to test.)
If successful, returns the GUID for the new file (aka the fileId); otherwise
returns 0.
See: https://www.backblaze.com/b2/docs/b2_upload_file.html
Example 1: Uploading from a file on disk:
my $file_id = $b2->b2_upload_file(
bucket_name => 'GingerAnna',
file_location => '/opt/majestica/tmp/ginger_was_perfect.jpg',
);
Example 2: Uploading when the file is loaded into a scalar:
my $file_id = $b2->b2_upload_file(
bucket_name => 'GingerAnna',
new_file_name => 'ginger_was_perfect.jpg',
file_contents => $file_contents
);
=head2 b2_upload_large_file
Uploads a large file into B2. Recommended for uploading files larger
than 100MB.
Example:
my $file_id = $b2->b2_upload_large_file(
bucket_name => 'GingerAnna',
file_location => '/opt/majestica/tmp/gingers_whole_life_story.mp4',
);
=head2 b2_list_file_info
Retrieves an arrayref hashrefs with file infomrmation for a bucket.
Backblaze calls if 'b2_list_file_names' but it really is for file info.
Limited to 10,000 file results per call, so you will may need to
call repeatedly to retrieve all names.
lib/Backblaze/B2V4.pm view on Meta::CPAN
Example:
my $success = $b2->b2_delete_bucket(
bucket_name => 'DeletingBucketName'
);
=head2 b2_delete_file_version
Deletes a version of a file, AKA a stored object. If you use unique
file names for each file you upload, then one version equals one file.
If you upload multiple files with the same name under a single bucket,
you will create multiple versions of a particular file in B2.
Required named args
file_name => the name of the file
file_id => the Backblaze GUID for the file
Returns 1 (success) or 0 (failure)
my $success = $b2->b2_delete_file_version(
lib/Backblaze/B2V4.pm view on Meta::CPAN
my $bucket_id = $b2->b2_get_bucket_id(
bucket_name => 'MyBucketName',
auto_create_bucket => 0 or 1,
);
Pass 1 for 'auto_create_bucket' to make the bucket if one does not exist for your 'bucket_name'
and return the new bucket ID. If you pass 0 for 'auto_create_bucket' and the bucket doesn't
exist, you will receive back a 0.
=head2 b2_get_upload_info
Almost all the API calls use the Account Authorization Token for the
authorization header, but the file uploader calls require a bucket-specific
token and upload URL. You can retrieve these via b2_get_upload_info()
with the bucket name as an argument.
Example:
my $results = $b2->b2_get_upload_info(
bucket_name => 'MyBucketName'
);
The %$results hash now has 'upload_url' and 'authorization_token'
Note: You have to call b2_get_upload_info on a bucket for each file
upload operation. My b2_upload_file method does that for you, so that's
just FYI if you roll your own.
See: https://www.backblaze.com/b2/docs/b2_get_upload_info.html
=head2 send_request
send_request() handles all the communications with B2.
You should be able to use this to make calls not explicitly
provided by this library.
If send_request() gets a 200 HTTP status from B2, then the call went
great, $b2->current_status_is_not_ok will be 0, and
the JSON response will be returned.
lib/Backblaze/B2V4.pm view on Meta::CPAN
B2 API V4 Docs: https://www.backblaze.com/apidocs/b2-authorize-account
Paws::S3 - If using Backblaze's S3-compatible API.
=head1 AUTHOR / BUGS
Eric Chernoff <eric@weaverstreet.net> - Please send me a note with any bugs or suggestions.
ESTRABD <estrabd@cpan.org> - Enhanced b2_list_file_names() to fully use options and a great bugfix
when using the 'file_contents' option in the b2_upload_file() method.
=head1 LICENSE
MIT License
Copyright (c) 2026 Eric Chernoff
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modi...
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
script/b2_client view on Meta::CPAN
use v5.38; # or higher
use strict;
use warnings;
use Backblaze::B2V4;
use Path::Tiny;
use Cwd;
my $dispatch = {
'get' => 'download_file',
'put' => 'upload_file',
'download' => 'download_file',
'upload' => 'upload_file',
'file_info' => 'file_info',
'list_items' => 'list_items',
'new_bucket' => 'new_bucket',
'save_tokens' => 'save_b2_tokens',
'help' => 'print_help',
};
$ARGV[0] ||= 'help';
my $subroutine = $$dispatch{ $ARGV[0] } || 'print_help';
script/b2_client view on Meta::CPAN
my $b2 = get_b2_session();
$b2->b2_download_file_by_name(
bucket_name => $args[0],
file_name => $args[1],
save_to_location => $args[2],
);
return show_result($b2, "Success: $args[1] saved to $args[2]");
}
sub upload_file {
my (@args) = @_;
if (!$args[0] || !$args[1]) {
return "Usage: b2_client put BUCKET_NAME PATH_TO_FILE\n";
}
# login in and upload the file
my $b2 = get_b2_session();
my $new_guid = $b2->b2_upload_file(
'bucket_name' => $args[0],
'file_location' => $args[1],
);
if (!$new_guid) {
return get_error_message($b2);
}
return show_result($b2, "Success: $args[1] uploaded to bucket $args[0]\nNew GUID: $new_guid");
}
sub list_items {
my (@args) = @_;
my $b2 = get_b2_session();
my $result = 0;
my $output;
# if they passed an arg, it would be a bucket name to get the files
script/b2_client view on Meta::CPAN
);
return show_result($b2, "Success: New bucket '$args[0]' was created");
}
sub print_help {
return qq{
b2_client: Simple Backblaze B2 client
This utility can download and upload files from the Backblaze B2 service.
It is part of Backblaze::B2V4 Perl library:
https://metacpan.org/pod/Backblaze::B2V4
# b2_client save_tokens APPLICATION_KEY_ID APPLICATION_KEY
Both arguments are required. Saves your B2 API key tokens to ~/.b2_tokens . Provision a key under 'App Keys' in the B2 Web UI. Choose carefully on the privileges you wish to give this app key, bearing in mind that the client can only complete the op...
# b2_client get BUCKET_NAME FILE_NAME [DESTINATION_DIRECTORY]
Downloads a file from B2. Required arguments are the name of the bucket containing the file and the name of the file in B2 (not the ID). Optional third argument is a destination directory, defaulting to the current working directory. Be sure you can ...
# b2_client put BUCKET_NAME PATH_TO_FILE
Upload a file to B2. Required arguments are the name of the destination B2 bucket and the path to the file to be uploaded. Best if the file has a standard extension (i.e. .txt, .png, .js, etc.). Can substitute 'upload' for 'put'.
# b2_client list_items [BUCKET_NAME] [START_FILE_NAME]
If no argument provided, lists the B2 buckets in your account.
Provide the bucket name as the first arg to list file id's and names that buclet.
Provide a starting file name as the second arg if your bucket has more than 10,000 files and you need to list them in groups.
# b2_client file_info FILE_ID
( run in 2.990 seconds using v1.01-cache-2.11-cpan-b16cb0d3907 )