# NAME
Backblaze::B2 - interface to the Backblaze B2 API
# SYNOPSIS
# METHODS
## `Backblaze::B2->new %options`
- **version**
Allows you to specify the API version. The current
default is `v1`, which corresponds to the
Backblaze B2 API version 1 as documented at
[https://www.backblaze.com/b2/docs/](https://www.backblaze.com/b2/docs/).
# SETUP
- 0. Have a telephone / mobile phone number you're willing to
share with Backblaze
- 1. Register at for Backblaze B2 Cloud Storage at
[https://secure.backblaze.com/account\_settings.htm?showPhone=true](https://secure.backblaze.com/account_settings.htm?showPhone=true)
- 2. Add the phone number to your account at
[https://secure.backblaze.com/account\_settings.htm?showPhone=true](https://secure.backblaze.com/account_settings.htm?showPhone=true)
- 3. Enable Two-Factor verification through your phone at
[https://secure.backblaze.com/account\_settings.htm?showPhone=true](https://secure.backblaze.com/account_settings.htm?showPhone=true)
- 4. Create a JSON file named `B2.credentials`
This file should live in your
home directory
with the application key and the account key:
{ "accountId": "...",
"applicationKey": ".............."
}
# NAME
Backblaze::B2::v1 - Backblaze B2 API account
# METHODS
## `->new %options`
my $b2 = Backblaze::B2::v1->new(
api => 'Backblaze::B2::v1::Synchronous', # the default
);
Creates a new instance. Depending on whether you pass in
`<Backblaze::B2::v1::Synchronous`> or `<Backblaze::B2::v1::AnyEvent`>,
you will get a synchronous or asynchronous API.
The synchronous API is what is documented here, as this is the
most likely use case.
my @buckets = $b2->buckets();
for( @buckets ) {
...
}
The asynchronous API is identical to the synchronous API in spirit, but
will return [Promises](https://metacpan.org/pod/Promises) . These condvars usually return
two or more parameters upon completion:
my $results = $b2->buckets();
$results->then( sub{
my( @buckets ) = @_;
for( @buckets ) {
...
}
}
The asynchronous API puts the burden of error handling into your code.
## `->buckets`
my @buckets = $b2->buckets();
Returns a list of [Backblaze::B2::Bucket](https://metacpan.org/pod/Backblaze::B2::Bucket) objects associated with
the B2 account.
## `->bucket_from_id`
my @buckets = $b2->bucket_from_id(
'deadbeef'
);
Returns a [Backblaze::B2::Bucket](https://metacpan.org/pod/Backblaze::B2::Bucket) object that has the given ID. It
does not make an HTTP request to fetch the name and status of that bucket.
## `->create_bucket`
my $new_bucket = $b2->create_bucket(
name => 'my-new-bucket', # only /[A-Za-z0-9-]/i are allowed as bucket names
type => 'allPrivate', # or allPublic
);
print sprintf "Created new bucket %s\n", $new_bucket->id;
Creates a new bucket and returns it.
## `->api`
Returns the underlying API object
## `->files( %options )`
Lists the files contained in this bucket
my @files = $bucket->files(
startFileName => undef,
);
By default it returns only the first 1000
files, but see the `allFiles` parameter.
- `allFiles`
allFiles => 1
Passing in a true value for this parameter will make
as many API calls as necessary to fetch all files.
## `->upload_file( %options )`
Uploads a file into this bucket, potentially creating
a new file version.
my $new_file = $bucket->upload_file(
file => 'some/local/file.txt',
target_file => 'the/public/name.txt',
);
- `file`
Local name of the source file. This file will be loaded
into memory in one go.
- `target_file`
Name of the file on the B2 API. Defaults to the local name.
The target file name will have backslashes replaced by forward slashes
to comply with the B2 API.
- `mime_type`
Content-type of the stored file. Defaults to autodetection by the B2 API.
- `content`
If you don't have the local content in a file on disk, you can
pass the content in as a string.
- `mtime`
Time in miliseconds since the epoch to when the content was created.
Defaults to the current time.
- `sha1`
Hexdigest of the SHA1 of the content. If this is missing, the SHA1
will be calculated upon upload.
## `->download_file_by_name( %options )`
Downloads a file from this bucket by name:
my $content = $bucket->download_file_by_name(
fileName => 'the/public/name.txt',
);
This saves you searching through the list of existing files
if you already know the filename.
## `->get_download_authorization( %options )`
Downloads a file from this bucket by name:
my $authToken = $bucket->get_download_authorization(
fileNamePrefix => '/members/downloads/',
validDurationInSeconds => 300, # five minutes
);
This returns an authorization token that can download files with the
given prefix.
## `->api`
Returns the underlying API object
## `->files( %options )`
Lists the files contained in this bucket
my @files = $bucket->files(
startFileName => undef,
);
By default it returns only the first 1000
files, but see the `allFiles` parameter.
- `allFiles`
allFiles => 1
Passing in a true value for this parameter will make
as many API calls as necessary to fetch all files.
## `->upload_file( %options )`
Uploads a file into this bucket, potentially creating
a new file version.
my $new_file = $bucket->upload_file(
file => 'some/local/file.txt',
target_file => 'the/public/name.txt',
);
- `file`
Local name of the source file. This file will be loaded
into memory in one go.
- `target_file`
Name of the file on the B2 API. Defaults to the local name.
The target file name will have backslashes replaced by forward slashes
to comply with the B2 API.
- `mime_type`
Content-type of the stored file. Defaults to autodetection by the B2 API.
- `content`
If you don't have the local content in a file on disk, you can
pass the content in as a string.
- `mtime`
Time in miliseconds since the epoch to when the content was created.
Defaults to the current time.
- `sha1`
Hexdigest of the SHA1 of the content. If this is missing, the SHA1
will be calculated upon upload.
## `->download_file_by_name( %options )`
Downloads a file from this bucket by name:
my $content = $bucket->download_file_by_name(
file => 'the/public/name.txt',
);
This saves you searching through the list of existing files
if you already know the filename.
## `->api`
Returns the underlying API object
