Skip to content

Latest commit

 

History

History
483 lines (371 loc) · 31.7 KB

docs.md

File metadata and controls

483 lines (371 loc) · 31.7 KB

b2CloudStorage

Backblaze B2 Cloud Storage class to handle stream-based uploads and all other API methods.

Kind: global class

new b2CloudStorage(options)

Creates new instance of the b2CloudStorage class.

Param Type Description
options object Required: Class options to set auth and other options
options.auth object Authentication object
options.auth.accountId string Backblaze b2 account ID for the API key.
options.auth.applicationKey string Backblaze b2 application API key.
options.maxSmallFileSize number Maximum filesize for the upload to upload as a single upload. Any larger size will be chunked as a Large File upload.
options.url string URL hostname to use when authenticating to Backblaze B2. This omits b2api/ and the version from the URI.
options.version string API version used in the Backblaze B2 url. This follows hthe b2api/ part of the URI.
options.maxPartAttempts number Maximum retries each part can reattempt before erroring when uploading a Large File.
options.maxTotalErrors number Maximum total errors the collective list of file parts can trigger (below the individual maxPartAttempts) before the Large File upload is considered failed.
options.maxReauthAttempts number Maximum times this library will try to reauthenticate if an auth token expires, before assuming failure.

b2CloudStorage.authorize([callback])

b2_authorize_account method, required before calling any B2 API routes.

Kind: instance method of b2CloudStorage

Param Type
[callback] function

b2CloudStorage.uploadFile(filename, data, [callback]) ⇒ object

Upload file with b2_upload_file or as several parts of a large file upload. This method also will get the filesize & sha1 hash of the entire file.

Kind: instance method of b2CloudStorage
Returns: object - Returns an object with 3 helper methods: cancel(), progress(), & info()

Param Type Description
filename String Path to filename to for upload.
data Object Configuration data passed from the uploadFile method.
data.bucketId String The target bucket the file is to be uploaded.
data.fileName String The object keyname that is being uploaded.
data.contentType String Content/mimetype required for file download.
[data.largeFileId] String The ID of a large File to resume uploading
[data.ignoreFileIdError] String When true and data.largeFileId is set, the upload will always proceed, even if the given fileId is invalid/old/wrong with a new fileId
[data.onUploadProgress] function Callback function on progress of entire upload
[data.onFileId] function Callback function when a fileId is assigned. Triggers at the end of a small file upload. Triggers before the upload of a large file.
[data.progressInterval] Number How frequently the onUploadProgress callback is fired during upload
[data.partSize] Number Overwrite the default part size as defined by the b2 authorization process
[data.info] Object File info metadata for the file.
[data.hash] String Skips the sha1 hash step with hash already provided.
[data.testMode] 'fail_some_uploads' | 'expire_some_account_authorization_tokens' | 'force_cap_exceeded' Enables B2 test mode by setting the X-Bz-Test-Mode header, which will cause intermittent artificial failures.
[callback] function

b2CloudStorage.listParts(data, [callback])

b2_list_parts Lists the parts that have been uploaded for a large file that has not been finished yet.

Kind: instance method of b2CloudStorage

Param Type Description
data Object Message Body Parameters
data.fileId String The ID returned by b2_start_large_file. This is the file whose parts will be listed.
[data.startPartNumber] Number The first part to return. If there is a part with this number, it will be returned as the first in the list. If not, the returned list will start with the first part number after this one.
[data.maxPartCount] Number The maximum number of parts to return from this call. The default value is 100, and the maximum allowed is 1000.
[callback] function

b2CloudStorage.listUnfinishedLargeFiles(data, [callback])

b2_list_unfinished_large_files Lists information about large file uploads that have been started, but have not been finished or canceled.

Kind: instance method of b2CloudStorage

Param Type Description
data Object Message Body Parameters
data.bucketId String The bucket to look for file names in.
[data.namePrefix] String When a namePrefix is provided, only files whose names match the prefix will be returned. When using an application key that is restricted to a name prefix, you must provide a prefix here that is at least as restrictive.
[data.startFileId] String The first upload to return. If there is an upload with this ID, it will be returned in the list. If not, the first upload after this the first one after this ID.
[data.maxFileCount] Number The maximum number of files to return from this call. The default value is 100, and the maximum allowed is 100.
[callback] function

b2CloudStorage.cancelLargeFile(data, [callback])

b2_delete_unfinished_large_file Cancels the upload of a large file, and deletes all of the parts that have been uploaded.

Kind: instance method of b2CloudStorage

Param Type Description
data Object Message Body Parameters
data.fileId String The ID returned by b2_start_large_file.
[callback] function

b2CloudStorage.getFileInfo(fileId, [callback])

b2_get_file_info Gets information about one file stored in B2.

Kind: instance method of b2CloudStorage

Param Type Description
fileId String The ID of the file, as returned by b2_upload_file, b2_hide_file, b2_list_file_names, or b2_list_file_versions.
[callback] function

b2CloudStorage.listBuckets([data], [callback])

b2_list_buckets Lists buckets associated with an account, in alphabetical order by bucket name.

Kind: instance method of b2CloudStorage

Param Type Description
[data] Object Message Body Parameters
[data.accountId] String The ID of your account. When unset will use the b2_authorize results accountId.
[data.bucketId] String When bucketId is specified, the result will be a list containing just this bucket, if it's present in the account, or no buckets if the account does not have a bucket with this ID.
[data.bucketTypes] Array One of: "allPublic", "allPrivate", "snapshot", or other values added in the future. "allPublic" means that anybody can download the files is the bucket; "allPrivate" means that you need an authorization token to download them; "snapshot" means that it's a private bucket containing snapshots created on the B2 web site.
[callback] function

b2CloudStorage.copyFilePart(data, [callback])

b2_copy_part Creates a new file by copying from an existing file.

Kind: instance method of b2CloudStorage

Param Type Description
data Object Message Body Parameters
data.sourceFileId String The ID of the source file being copied.
data.largeFileId String The ID of the large file the part will belong to, as returned by b2_start_large_file.
data.partNumber Number A number from 1 to 10000. The parts uploaded for one file must have contiguous numbers, starting with 1.
[data.range] Object The range of bytes to copy. If not provided, the whole source file will be copied.
[callback] function

b2CloudStorage.copyFile(data, [callback]) ⇒ object

Copies a any size file using either b2_copy_file or b2_copy_part method automatically.

Kind: instance method of b2CloudStorage
Returns: object - Returns an object with 3 helper methods: cancel(), progress(), & info()

Param Type Description
data Object Message Body Parameters
data.sourceFileId String The ID of the source file being copied.
data.fileName String The name of the new file being created.
[data.size] Number Size of the file. If not specified will be looked up with an extra class C API call to b2_get_file_info.
[data.destinationBucketId] String The ID of the bucket where the copied file will be stored. Uses original file bucket when unset.
[data.range] String The range of bytes to copy. If not provided, the whole source file will be copied.
[data.metadataDirective] String The strategy for how to populate metadata for the new file.
[data.contentType] String Must only be supplied if the metadataDirective is REPLACE. The MIME type of the content of the file, which will be returned in the Content-Type header when downloading the file.
[data.onUploadProgress] function Callback function on progress of entire copy
[data.progressInterval] Number How frequently the onUploadProgress callback is fired during upload
[data.partSize] Number Overwrite the default part size as defined by the b2 authorization process
[data.fileInfo] Object Must only be supplied if the metadataDirective is REPLACE. This field stores the metadata that will be stored with the file.
[callback] function

b2CloudStorage.createBucket(data, [callback])

b2_create_bucket Creates a new bucket. A bucket belongs to the account used to create it.

Kind: instance method of b2CloudStorage

Param Type Description
data Object Message Body Parameters
data.bucketName String The name to give the new bucket.
data.bucketType String Either "allPublic", meaning that files in this bucket can be downloaded by anybody, or "allPrivate", meaning that you need a bucket authorization token to download the files.
[data.accountId] String The ID of your account. When unset will use the b2_authorize results accountId.
[data.bucketInfo] Object User-defined information to be stored with the bucket: a JSON object mapping names to values. See Buckets. Cache-Control policies can be set here on a global level for all the files in the bucket.
[data.corsRules] Array The initial list (a JSON array) of CORS rules for this bucket. See CORS Rules for an overview and the rule structure.
[data.lifecycleRules] Array The initial list (a JSON array) of lifecycle rules for this bucket. Structure defined below. See Lifecycle Rules.
[callback] function

b2CloudStorage.updateBucket(data, [callback])

b2_update_bucket Update an existing bucket.

Kind: instance method of b2CloudStorage

Param Type Description
data Object Message Body Parameters
data.bucketId String The unique ID of the bucket.
[data.accountId] String The ID of your account. When unset will use the b2_authorize results accountId.
[data.bucketType] String Either "allPublic", meaning that files in this bucket can be downloaded by anybody, or "allPrivate", meaning that you need a bucket authorization token to download the files.
[data.bucketInfo] Object User-defined information to be stored with the bucket: a JSON object mapping names to values. See Buckets. Cache-Control policies can be set here on a global level for all the files in the bucket.
[data.corsRules] Array The initial list (a JSON array) of CORS rules for this bucket. See CORS Rules for an overview and the rule structure.
[data.lifecycleRules] Array The initial list (a JSON array) of lifecycle rules for this bucket. Structure defined below. See Lifecycle Rules.
[data.ifRevisionIs] Array When set, the update will only happen if the revision number stored in the B2 service matches the one passed in. This can be used to avoid having simultaneous updates make conflicting changes.
[callback] function

b2CloudStorage.deleteBucket(data, [callback])

b2_delete_bucket Deletes the bucket specified. Only buckets that contain no version of any files can be deleted.

Kind: instance method of b2CloudStorage

Param Type Description
data Object | String Message Body Parameters. If a string is provided it will be treated as the bucketId.
data.bucketId String The unique ID of the bucket.
[data.accountId] String The ID of your account. When unset will use the b2_authorize results accountId.
[callback] function

b2CloudStorage.listFileNames(data, [callback])

b2_list_file_names Lists the names of all files in a bucket, starting at a given name.

Kind: instance method of b2CloudStorage

Param Type Description
data Object Message Body Parameters. If a string is provided it will be treated as the bucketId.
data.bucketId String The unique ID of the bucket.
[data.startFileName] String The first file name to return. If there is a file with this name, it will be returned in the list. If not, the first file name after this the first one after this name.
[data.maxFileCount] Number The maximum number of files to return from this call. The default value is 100, and the maximum is 10000. Passing in 0 means to use the default of 100.
[data.prefix] String Files returned will be limited to those with the given prefix. Defaults to the empty string, which matches all files.
[data.delimiter] String files returned will be limited to those within the top folder, or any one subfolder. Defaults to NULL. Folder names will also be returned. The delimiter character will be used to "break" file names into folders.
[callback] function

b2CloudStorage.listFileVersions(data, [callback])

b2_list_file_versions Lists all of the versions of all of the files contained in one bucket, in alphabetical order by file name, and by reverse of date/time uploaded for versions of files with the same name.

Kind: instance method of b2CloudStorage

Param Type Description
data Object Message Body Parameters. If a string is provided it will be treated as the bucketId.
data.bucketId String The unique ID of the bucket.
[data.startFileName] String The first file name to return. If there is a file with this name, it will be returned in the list. If not, the first file name after this the first one after this name.
[data.startFileId] Number The first file ID to return. startFileName must also be provided if startFileId is specified.
[data.maxFileCount] Number The maximum number of files to return from this call. The default value is 100, and the maximum is 10000. Passing in 0 means to use the default of 100.
[data.prefix] String Files returned will be limited to those with the given prefix. Defaults to the empty string, which matches all files.
[data.delimiter] String files returned will be limited to those within the top folder, or any one subfolder. Defaults to NULL. Folder names will also be returned. The delimiter character will be used to "break" file names into folders.
[callback] function

b2CloudStorage.listKeys([data], [callback])

b2_list_keys Lists application keys associated with an account.

Kind: instance method of b2CloudStorage

Param Type Description
[data] Object Message Body Parameters. If a string is provided it will be treated as the bucketId.
[data.accountId] String The ID of your account. When unset will use the b2_authorize results accountId.
[data.maxKeyCount] Number The maximum number of keys to return in the response. Default is 100, maximum is 10000.
[data.startApplicationKeyId] String The first key to return. Used when a query hits the maxKeyCount, and you want to get more. Set to the value returned as the nextApplicationKeyId in the previous query.
[callback] function

b2CloudStorage.createKey(data, [callback])

b2_create_key Creates a new application key.

Kind: instance method of b2CloudStorage

Param Type Description
data Object Message Body Parameters.
data.capabilities Array A list of strings, each one naming a capability the new key should have. Possibilities are: listKeys, writeKeys, deleteKeys, listBuckets, writeBuckets, deleteBuckets, listFiles, readFiles, shareFiles, writeFiles, and deleteFiles.
data.keyName String A name for this key. There is no requirement that the name be unique. The name cannot be used to look up the key. Names can contain letters, numbers, and "-", and are limited to 100 characters.
[data.accountId] String The ID of your account. When unset will use the b2_authorize results accountId.
[data.validDurationInSeconds] Number When provided, the key will expire after the given number of seconds, and will have expirationTimestamp set. Value must be a positive integer, and must be less than 1000 days (in seconds).
[data.bucketId] String When present, the new key can only access this bucket. When set, only these capabilities can be specified: listBuckets, listFiles, readFiles, shareFiles, writeFiles, and deleteFiles.
[data.namePrefix] String When present, restricts access to files whose names start with the prefix. You must set bucketId when setting this.
[callback] function

b2CloudStorage.deleteKey(applicationKeyId, [callback])

b2_delete_key Deletes the application key specified.

Kind: instance method of b2CloudStorage

Param Type Description
applicationKeyId String The key to delete.
[callback] function

b2CloudStorage.deleteFileVersion(data, [callback])

b2_delete_file_version Deletes one version of a file from B2.

Kind: instance method of b2CloudStorage

Param Type Description
data Object Message Body Parameters.
data.fileName String The name of the file.
data.fileId String The ID of the file, as returned by b2_upload_file, b2_list_file_names, or b2_list_file_versions.
[callback] function

b2CloudStorage.downloadFileById(data, [callback])

b2_download_file_by_id Downloads one file from B2.

Kind: instance method of b2CloudStorage

Param Type Description
data Object Request Details
data.fileId String Request Details
[data.Authorization] String An account authorization token.
[data.Range] String A standard byte-range request, which will return just part of the stored file.
[data.b2ContentDisposition] String If this is present, B2 will use it as the value of the 'Content-Disposition' header, overriding any 'b2-content-disposition' specified when the file was uploaded.
[callback] function

b2CloudStorage.downloadFileByName(data, [callback])

b2_download_file_by_name Downloads one file by providing the name of the bucket and the name of the file.

Kind: instance method of b2CloudStorage

Param Type Description
data Object Request HTTP Headers
data.bucket String Bucket name.
data.fileName String file name.
[data.Authorization] String An account authorization token.
[data.Range] String A standard byte-range request, which will return just part of the stored file.
[data.b2ContentDisposition] String If this is present, B2 will use it as the value of the 'Content-Disposition' header, overriding any 'b2-content-disposition' specified when the file was uploaded.
[callback] function

b2CloudStorage.getDownloadAuthorization(data, [callback])

b2_get_download_authorization Used to generate an authorization token that can be used to download files with the specified prefix (and other optional headers) from a private B2 bucket. Returns an authorization token that can be passed to b2_download_file_by_name in the Authorization header or as an Authorization parameter.

Kind: instance method of b2CloudStorage

Param Type Description
data Object Message Body Parameters.
data.bucketId String The identifier for the bucket.
data.fileNamePrefix String The file name prefix of files the download authorization token will allow b2_download_file_by_name to access.
data.validDurationInSeconds Number The number of seconds before the authorization token will expire. The minimum value is 1 second. The maximum value is 604800 which is one week in seconds.
[data.b2ContentDisposition] Number If this is present, download requests using the returned authorization must include the same value for b2ContentDisposition. The value must match the grammar specified in RFC 6266 (except that parameter names that contain an '*' are not allowed).
[callback] function

b2CloudStorage.hideFile(data, [callback])

b2_hide_file Hides a file so that downloading by name will not find the file, but previous versions of the file are still stored. See File Versions about what it means to hide a file.

Kind: instance method of b2CloudStorage

Param Type Description
data Object Message Body Parameters.
data.bucketId String The bucket containing the file to hide.
data.fileName String The name of the file to hide.
[callback] function

b2CloudStorage.request(data, callback)

Helper method: Request wrapper used to call Backblaze B2 API. All class methods consume this method internally.

Kind: instance method of b2CloudStorage

Param Type Description
data object Options object. Matches the same of the request npm module. The options listed below are changed or modified for this api.
data.url string URI path to append after the hostname, api path, and version.
data.appendPath boolean (internal) When set to false will prevent extra URI and hostname changes. Most useful when combined with apiUrl
data.apiUrl boolean (internal) Full URL path or hostname to replace. Most useful when combined with appendPath.
callback function [description]

b2CloudStorage.copySmallFile(data, [callback]) ⇒ object

Helper function for b2_copy_file Creates a new file by copying from an existing file. Limited to 5GB

Kind: instance method of b2CloudStorage
Returns: object - Returns an object with 1 helper method: cancel()

Param Type Description
data Object Message Body Parameters
data.sourceFileId String The ID of the source file being copied.
data.fileName String The name of the new file being created.
[data.destinationBucketId] String The ID of the bucket where the copied file will be stored. Uses original file bucket when unset.
[data.range] Object The range of bytes to copy. If not provided, the whole source file will be copied.
[data.metadataDirective] String The strategy for how to populate metadata for the new file.
[data.contentType] String Must only be supplied if the metadataDirective is REPLACE. The MIME type of the content of the file, which will be returned in the Content-Type header when downloading the file.
[data.fileInfo] Object Must only be supplied if the metadataDirective is REPLACE. This field stores the metadata that will be stored with the file.
[callback] function

b2CloudStorage.copyLargeFile(data, [callback])

Helper function for b2_copy_file Creates a new file by copying from an existing file. Limited to 5GB

Kind: instance method of b2CloudStorage

Param Type Description
data Object Message Body Parameters
data.sourceFileId String The ID of the source file being copied.
data.fileName String The name of the new file being created.
data.destinationBucketId String The ID of the bucket where the copied file will be stored. Uses original file bucket when unset.
data.contentType String Must only be supplied if the metadataDirective is REPLACE. The MIME type of the content of the file, which will be returned in the Content-Type header when downloading the file.
data.size Number Content size of target large file
data.hash String sha1 hash for the target large file
[data.onUploadProgress] function Callback function on progress of entire copy
[data.progressInterval] Number How frequently the onUploadProgress callback is fired during upload
[data.partSize] Number Overwrite the default part size as defined by the b2 authorization process
[data.fileInfo] Object Must only be supplied if the metadataDirective is REPLACE. This field stores the metadata that will be stored with the file.
[callback] function

b2CloudStorage.getUrlEncodedFileName(fileName) ⇒ string

Helper method: Properly URL encode filenames to prevent B2 throwing errors with spaces, etc.

Kind: static method of b2CloudStorage
Returns: string - Returns a safe and URL encoded file name for upload

Param Type Description
fileName string File name for upload