This add-on will upload files from your hass[]().io backup folder (typically .tar files created by the hass[]().io SnapShot feature) to your Google Drive. A few key things to note:
You can install this hass[]().io add-on using my add-on repository following these Home Assistant Add-on Instructions.
Example configuration:
{"fromPattern" : "/backup/*.tar",
"backupDirID" : "1CvPDzNz1v-OuOUqKq3jjoKQt020hKK7R",
"purge" : {"enabled" : true, "preserve" : 3},
"purge_google" : {"enabled" : true, "preserve" : 12},
"debug" : false}
fromPattern
Use this to identify the files on your hass[]().io host that you wish to backup.
This pattern is used to identify a list of files to backup. That list is then pared down by checking Google Drive to see if any files in the list have already been backed up by this add-on. This check is performed to avoid backing up the same file twice (Google Drive allows duplicate files with the same name).
Note that this add-on can only see files on your Google Drive that it created itself. Therefore, if you have backed up some of your snapshots on your own to Google Drive, this add-on will not be aware of those and it will back them up anyway.
backupDirID
This identifies the Google Drive folder in which you want to place your backed up files. Because this add-on does not have permission to browse any files or directories on your Google Drive that it does not itself create, you cannot simply provide the folder name. You must instead provide Google Drive's unique opaque ID of the folder. Google Drive doesn't make it easy to get this value. But, here's how you can get it:
backupDirID
value in the configuration.purge
This configures the option to purge (delete) older files from your source location (e.g. your /backup folder on hass[]().io). There two sub-elements:
enabled
Set this boolean to true if you wish to take advantage of this purge feature.preserve
Set this integer value to the number of files that you wish to preserve (to keep) in your source location. If enabled, this purge feature will delete the oldest files (by date modified) in your source location, preserving the number of more recent files that you specify with this value.purge_google
Contrary to its ominous sounding name, this does not purge every file from your Google Drive ;-). This add-on can see only files that it creates on your Google Drive. It can also see the folder that you identify for it to place backup files into, but it cannot see files inside that folder unless this add-on created them itself. This option configures the feature to purge (delete) older files from your Google Drive folder (the one you identify in the backupDirID
option). There two sub-elements:
enabled
Set this boolean to true if you wish to take advantage of this feature.preserve
Set this integer value to the number of files that you wish to preserve (to keep) in your Google Drive folder. If enabled, this feature will delete the oldest files (by date modified) in your Google Drive folder, preserving the number of more recent files that you specify with this value.Important notes about this option:
backupDirID
folder on Google Drive.fromPattern
setting at all.debug
Defaults to false
if not present. Set this to true
to enable debug-level logging.
This add-on requires you to authorize it to a limited scope of access to your Google Drive. The specific scope it requires is https://www.googleapis.com/auth/drive.file
. You can read information about what that scope entails in Google's Guide to OAuth 2.0 Scopes. Essentially, it allows this add-on to view and manage Google Drive files and folders that you have opened or created with this add-on.
Before using the doBackup
service operation, you need to follow these steps to grant this add-on the required authorization:
Start on boot
.Open Web UI
link on the add-on details page. Alternatively, you can open your own browser window and navigate to: http://<Your_Hassio_Host>:<Host_Port>/gb
, substituting your hass[]().io host name and the Host Port number you've configured for this add-on.AUTHORIZE
button to launch a separate browser tab to the Google Authorization Server.Allow
button.INGEST CODE
button.doBackup
Service as described below.doBackup
OperationBackups are performed by calling the doBackup
service operation exposed by this add-on. When you start this add-on, the service becomes available on the Host Port that you've configured this add-on to use.
The doBackup
service operation does not require any arguments. It gets the information it needs from the Configuration Options and from your having completed the authorization process described above.
You call the doBackup service operation by simply performing a GET against this URI (in fact, you can just click this link):
http://<YOUR_HASSIO_HOST>:<HOST_PORT>/gb/doBackup
Substitute in your hass[]().io host name (usually hassio.local
) and the Host Port number you've configured for this add-on.
The doBackup
service operation will respond with JSON reminding you of the configuration settings that it used and indicating:
fromPattern
doBackup
service operation actually backed up during this run{
"backupTimestamp": "2018-11-26T09:57:36.206259",
"fromPattern": "/backup/*.tar",
"backupDirID": "1CvPDzNz1v-OuOUqKq3jjoKQt020hKK7R",
"fileCount": 5,
"alreadyCount": 2,
"backedUpCount": 3,
"deletedCount": 2,
"deletedFromGoogle": 1
}
Unexpected errors will return an HTTP Status Code of some value other than the normal 200 Success Code.
adhocBackup
OperationAs a completely separate feature, adhoc backups may be performed. These backups do not use the configured options fromPattern
, backupDirID
, purge
and purge_google
. Instead, an adhoc backup request identifies which files are to be backed up and which Google Drive folder is to be targeted each time it is placed (hence the name, "adhoc"). The concept of "purging" of older files while preserving more recent files does not apply at all to adhoc backups. Adhoc backups simply copy each identified file from your hass[]().io host to your Google Drive, replacing the target file on Google Drive if it already exists. Adhoc backups are performed by calling the adhocBackup
service operation exposed by this add-on. When you start this add-on, the service becomes available on the Host Port that you've configured this add-on to use.
The adhocBackup
service operation has two required arguments that must be provided in the form of a JSON body on the HTTP POST.
fromPatterns
This is an array of file name patterns to be used to identify which files to copy from your hass[]().io host (only the following folders are accessible for this add-on to copy from: config
, ssl
, addons
, backup
, and share
).backupDirID
This is identifies the particular folder on your Google Drive where you want the files to be copied to. See the description of the backupDirID configuration operation, above, for details on how to obtain the identifier of a Google Drive folder. Keep in mind that you must have completed the one-time authorization process described above in order for either of these service operations to work.WARNING: It is recommended that you do NOT specify the same target Google Drive folder for adhoc backups that you have specified in the add-on options configuration for the normal backup operation, especially if you are using the purge_google
feature.
You call the adhocBackup service operation by performing a POST against this URI:
http://<YOUR_HASSIO_HOST>:<HOST_PORT>/gb/adhocBackup
Substitute in your hass[]().io host name (usually hassio.local
) and the Host Port number you've configured for this add-on.
{"fromPatterns" : ["/config/configuration.yaml", "/config/automations.yaml"],
"backupDirID" : "4FtLMzNz1v-OuOUqKq3jjoKQt020hLL9P"}
The adhocBackup
service operation will respond with JSON indicating:
{
"adhocBackupTimestamp": "2019-03-15T07:59:56.205540",
"fromPatterns": [
"/config/configuration.yaml",
"/config/automations.yaml"
],
"backupDirID": "4FtLMzNz1v-OuOUqKq3jjoKQt020hLL9P",
"copyCount": 2,
"newCount": 0,
"replacedCount": 2
}
Unexpected errors will return an HTTP Status Code of some value other than the normal 200 Success Code.
You can easily integrate this add-on's doBackup
REST service operation into Home Assistant using Home Assistant's RESTful Command. You'll probably need to use localhost
instead of hassio.local
in this configuration. You'll also want to specify an adequate timeout value. Here's how I setup mine:
rest_command:
google_backup:
url: 'http://localhost:8055/gb/doBackup'
timeout: '300'
With this REST Command created, you'll see your Google Backup Service available as rest_command.google_backup
in Home Assistant's Services Development Tool, and you'll also be able to call it as part of Home Assistant Automations.
Because the adhocBackup
operation requires a JSON array, I've not been able to figure out how to configure a REST Command for it in Home Assistant. If you figure it out, let me know. For now, you can call the adhocBackup
operation from tools like Postman. You'll want to setup your tool do a POST method, passing in JSON (Content-Type of appliction/json). Here's an example JSON request: {"fromPatterns" : ["/config/configuration.yaml", "/config/automations.yaml"], "backupDirID" : "4FtLMzNz1v-OuOUqKq3jjoKQt020hLL9P"}
.
Everytime the doBackup operation, or the adhocBackup operation, is executed, an event is published to the MQTT broker that you have configured in Home Assistant. The payload of the event is a copy of the JSON response described above. The event is published to either the googlebackup/result
or the googlebackup/adhocresult
topic, depending on which operation was called.
Here is an example Home Assistant Sensor configuration that monitors for these events:
- platform: mqtt
name: "Google Backup Results"
state_topic: "googlebackup/result"
json_attributes_topic: "googlebackup/result"
- platform: mqtt
name: "Google Adhoc Backup Results"
state_topic: "googlebackup/adhocresult"
json_attributes_topic: "googlebackup/adhocresult"