File Versions
To keep your data safe, even if you upload a bad file or get rid of the wrong file, B2 Cloud Storage lets you keep a history of previous versions of each file stored. Not only can you keep previous versions of a file, but B2 can keep track of when a file has gone away and when it has been put back, allowing you to keep a full history.
The first time you upload a file called puppy.jpg
, you
have just one version of the file, so it's clear which one you get
when you download puppy.jpg
.
You can think of a file as always having a list of versions, newest first. When you download a file by name, you always get the most recent version, the first one in the list. If you want an older version, you can find its File ID, and then download it.
If you upload a new file called puppy.jpg, you get this:
If you upload another file with the same name later, there are now two versions in the list, with the newest one first:
At this point, if you download “puppy.jpg”, you’ll get the new one. You can still download either puppy image by using its file ID.
The b2_list_file_names
operation returns one entry for each
file name, so at this point it will return just one file name, and it
will have the file ID of the more recent version. If you want to see
all of the versions of the file, you can use
the b2_list_file_versions
operation, which will list both
versions of “puppy.jpg”
Now, the b2_hide_file
operation makes it look like the file
has been deleted, without removing any of the history. It adds a new
version of the file that is a "hide marker" saying the file is no longer there.
With the file hidden, downloading the file by name will return a 404 error saying that the file is not there.
Uploading yet another cute puppy picture at this point adds a new version, which is the one that you get when downloading the file by name. The fact that an older version was hidden is still in the history.
The b2_list_file_versions
operation will give you all of this
information. The results returned look like this:
{ "files" : [ { "fileId": "4_z4a48fe8875c6214145260818_f0000000000823564_d20150725_m091433_c001_v0000123_t0104", "fileName": "puppy.jpg", "action": "upload", "uploadTimestamp": 1437815673000, }, { "fileId": "4_z4a48fe8875c6214145260818_f0000000057265835_d20150723_m160005_c001_v0000123_t0104",, "fileName": "puppy.jpg", "action": "hide", "uploadTimestamp": 1437667205000, }, { "fileId": "4_z4a48fe8875c6214145260818_f0000000000562156_d20150721_m045924_c001_v0000123_t0104", "fileName": "puppy.jpg", "action": "upload", "uploadTimestamp": 1437454764000, }, { "fileId": "4_z4a48fe8875c6214145260818_f000000000000472a_d20150721_m032942_c001_v0000123_t0104", "fileName": "puppy.jpg", "action": "upload", "uploadTimestamp": 1437449382000, } ] }
And finally, the last thing about file versions is that you can delete
them. Deleting a file version cannot be undone, and is permanent.
The b2_delete_file_version
operation makes it as if that version
of the file had never been there. You'll usually use this to clean up
old versions of a file that you don't need any more. Removing the first
puppy uploaded results in this:
It is even possible to delete the marker saying a file is hidden. If, at this point, you delete the newest version and the deletion marker, you get back to just one version:
To summarize, the things you can do to files are:
b2_upload_file |
Creates a new file version. As the newest version, this is the one that you will get when downloading by name. |
b2_download_file_by_id |
Fetches the specific file version for the given File ID. |
b2_download_file_by_name |
Fetches the most recent version of the file. If the file is not there at all, or the most recent version is "hidden", returns 404. |
b2_hide_file |
Creates a "hidden" marker as the most recent version of the file. Downloading the file by name will return 404. |
b2_delete_file_version |
Permanently deletes the file version and all of its data. It will be as if that version had never been uploaded. |
b2_list_file_names |
Returns file names for the bucket, in alphabetical order, starting at a given point. |
b2_list_file_versions |
Returns a list of all versions of all files in a bucket, sorted by file name, then by upload time. May be restricted to just list the version for a given file name. |