jeans/developers.home-assistant
jeans/developers.home-assistant
1
0
Fork 0
mirror of https://github.com/home-assistant/developers.home-assistant.git synced 2025-07-14 21:06:28 +00:00
Code Issues Packages Projects Releases Wiki Activity

Document fields and parameters added to support cloud backup

Browse Source
This commit is contained in:
Mike Degatano 2024-12-17 16:56:53 -05:00
parent 2b2b3f5899
commit d93a0744e0
2 changed files with 101 additions and 45 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

86
docs/api/supervisor/endpoints.md
View File

@ -781,8 +781,10 @@ Return a list of [Backups](api/supervisor/models.md#backup)
"name": "Awesome backup",
"type": "partial",
"size": 44,
"size_bytes": 44070259,
"protected": true,
"location": "MountedBackups",
"locations": ["MountedBackups"],
"compressed": true,
"content": {
"homeassistant": true,
@ -818,9 +820,11 @@ Return information about backup manager.
"name": "Awesome backup",
"type": "partial",
"size": 44,
"size_bytes": 44070259,
"protected": true,
"compressed": true,
"location": null,
"locations": [null],
"content": {
"homeassistant": true,
"addons": ["awesome_addon"],
@ -845,24 +849,45 @@ Create a full backup.
| name | string | True | The name you want to give the backup |
| password | string | True | The password you want to give the backup |
| compressed | boolean | True | `false` to create uncompressed backups |
| location | string or null | True | Name of a backup mount or `null` for /backup |
| location | list, string or null | True | Name of a backup mount or `null` for /backup. Use a list of backup mounts or `null` to make backup in multiple places |
| homeassistant_exclude_database | boolean | True | Exclude the Home Assistant database file from backup |
| background | boolean | True | Return `job_id` immediately, do not wait for backup to complete. Clients must check job for status and slug. |
| extra | dictionary | True | Extra metadata to store with the backup for client-specific use cases |
**Example response:**
```json
{
"slug": "skuwe823"
"slug": "skuwe823",
"job_id": "abc123"
}
```
:::note
Error responses from this API may also include a `job_id` if the message alone cannot accurately describe what happened.
Callers should direct users to review the job or supervisor logs to get an understanding of what occurred.
:::
</ApiEndpoint>
<ApiEndpoint path="/backups/new/upload" method="post">
Upload a backup.
**Query**
| key | multiple | description |
| --------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| location | Yes | The name of the backup mount to upload to. Use empty string for `/backup`. Provide multiple locations to upload to multiple places |
*Examples*
- `?location=` - Upload to `/backup`
- `?location=MountedBackups` - Upload to backup mount named `MountedBackup`
- `?location=&location=MountedBackups` - Upload to both of the above places
**Example response:**
```json
@ -891,15 +916,16 @@ Create a partial backup.
| ------------------------------ | -------------- | -------- | ---------------------------------------------------- |
| name | string | True | The name you want to give the backup |
| password | string | True | The password you want to give the backup |
| homeassistant | boolean | True | Add home assistant core settings to the backup |
| addons | list | True | A list of strings representing add-on slugs |
| folders | list | True | A list of strings representing directories |
| homeassistant | boolean | Content | Add home assistant core settings to the backup |
| addons | list or `ALL` | Content | A list of strings representing add-on slugs. Provide the string `ALL` instead of a list to include all currently installed add-ons |
| folders | list | Content | A list of strings representing directories |
| compressed | boolean | True | `false` to create uncompressed backups |
| location | string or null | True | Name of a backup mount or `null` for /backup |
| location | list, string or null | True | Name of a backup mount or `null` for /backup. Use a list of backup mounts or `null` to make backup in multiple places |
| homeassistant_exclude_database | boolean | True | Exclude the Home Assistant database file from backup |
| background | boolean | True | Return `job_id` immediately, do not wait for backup to complete. Clients must check job for status and slug. |
| extra | dictionary | True | Extra metadata to store with the backup for client-specific use cases |
**You need to supply at least one key in the payload.**
**You need to supply at least one key of the ones marked "Content" in the optional column in the payload.**
**Example response:**
@ -968,6 +994,17 @@ End a freeze initiated by `/backups/freeze` and resume normal behavior in Home A
Download the backup file with the given slug.
**Query**
| key | multiple | description |
| --------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| location | No | Specify which location to download the backup from of the ones it exists in. Use empty string for `/backup` (equivalent to `null` in the `locations` field of [Backup](api/supervisor/models.md#backup)) |
*Examples*
- `?location=` - Download from `/backup`
- `?location=MountedBackups` - Download from backup mount named `MountedBackup`
</ApiEndpoint>
<ApiEndpoint path="/backups/<backup>/info" method="get">
@ -980,6 +1017,12 @@ Returns a [Backup details model](api/supervisor/models.md#backup-details) for th
Removes the backup file with the given slug.
**Payload:**
| key | type | optional | description |
| -------- | ---- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| location | list | True | Specify which locations to remove the backup from instead of removing it from all locations. See `locations` field of [Backup](api/supervisor/models.md#backup)|
</ApiEndpoint>
<ApiEndpoint path="/backups/<backup>/restore/full" method="post">
@ -988,10 +1031,11 @@ Does a full restore of the backup with the given slug.
**Payload:**
| key | type | optional | description |
| ---------- | ------- | -------- | ------------------------------------ |
| password | string | True | The password for the backup if any |
| background | boolean | True | Return `job_id` immediately, do not wait for restore to complete. Clients must check job for status. |
| key | type | optional | description |
| ---------- | -------------- | -------- | ------------------------------------ |
| password | string | True | The password for the backup if any |
| background | boolean | True | Return `job_id` immediately, do not wait for restore to complete. Clients must check job for status. |
| location | string or null | True | Specify which location to restore the backup from of the ones it exists in. See `locations` field of [Backup](api/supervisor/models.md#backup) |
**Example response:**
@ -1016,15 +1060,16 @@ Does a partial restore of the backup with the given slug.
**Payload:**
| key | type | optional | description |
| ------------- | ------- | -------- | ---------------------------------------------- |
| homeassistant | boolean | True | `true` if Home Assistant should be restored |
| addons | list | True | A list of add-on slugs that should be restored |
| folders | list | True | A list of directories that should be restored |
| password | string | True | The password for the backup if any |
| background | boolean | True | Return `job_id` immediately, do not wait for restore to complete. Clients must check job for status. |
| key | type | optional | description |
| ------------- | -------------- | -------- | ---------------------------------------------- |
| homeassistant | boolean | Content | `true` if Home Assistant should be restored |
| addons | list | Content | A list of add-on slugs that should be restored |
| folders | list | Content | A list of directories that should be restored |
| password | string | True | The password for the backup if any |
| background | boolean | True | Return `job_id` immediately, do not wait for restore to complete. Clients must check job for status. |
| location | string or null | True | Specify which location to restore the backup from of the ones it exists in. See `locations` field of [Backup](api/supervisor/models.md#backup) |
**You need to supply at least one key in the payload.**
**You need to supply at least one key of the ones marked "Content" in the optional column in the payload.**
**Example response:**
@ -2105,7 +2150,8 @@ Returns information about mounts configured in Supervisor
"server": "server.local",
"share": "media",
"state": "active",
"read_only": false
"read_only": false,
"user_path": "/media/my_share"
}
]
}

60
docs/api/supervisor/models.md
View File

@ -168,15 +168,19 @@ These models are describing objects that are getting returned from the superviso
## Backup
| key | type | description |
| --------- | ------- | --------------------------------------------------------------------- |
| slug | string | A generated slug for the backup |
| date | string | ISO date string representation of the date the backup was created |
| name | string | The name given to the backup |
| type | string | The type of backup (full, partial) |
| protected | boolean | `true` if the backup is password protected |
| content | dictionary | A dictionary describing the content of the backup |
| compressed | boolean | `true` if the backup is saved in a compressed archive |
| key | type | description |
| ---------- | -------------- | -------------------------------------------------------------------------------------- |
| slug | string | A generated slug for the backup |
| date | string | ISO date string representation of the date the backup was created |
| name | string | The name given to the backup |
| type | string | The type of backup (full, partial) |
| size | float | Size of the backup in MB (rounded) |
| size_bytes | int | Size of the backup in bytes |
| location | string or null | The name of the backup mount it's stored on. `null` if it's stored locally |
| locations | list | List of names of all backup mounts it's stored on and/or `null` if it's stored locally |
| protected | boolean | `true` if the backup is password protected |
| content | dictionary | A dictionary describing the content of the backup |
| compressed | boolean | `true` if the backup is saved in a compressed archive |
### Backup -> content
@ -196,14 +200,19 @@ The `content` key of a backup object contains the following keys:
| type | string | The type of backup (full, partial) |
| name | string | The name given to the backup |
| date | string | ISO date string representation of the date the backup was created |
| size | string | The size of the backup in MB |
| size | float | The size of the backup in MB (rounded) |
| size_bytes | int | Size of the backup in bytes |
| compressed | boolean | `true` if the backup is saved in a compressed archive |
| protected | boolean | `true` if the backup is password protected |
| location | string or null | The name of the backup mount it's stored on. `null` if it's stored locally. |
| homeassistant | string | The version of Home Assistant that was in use |
| supervisor_version | string | The version of Supervisor the backup was created on. Backup can only be restored on Supervisor with same version or later |
| location | string or null | The name of the backup mount it's stored on. `null` if it's stored locally. |
| locations | list | List of names of all backup mounts it's stored on and/or `null` if it's stored locally |
| homeassistant | string or null | The version of Home Assistant that was in use. `null` if Home Assistant is not included in the backup |
| addons | list | A list of add-ons in the backup. Add-ons are represented as a dictionary with these keys [`slug`,`name`,`version`,`size`] |
| repositories | list | A list of add-on repository URL's as strings |
| folders | list | A list of strings representing directories |
| homeassistant_exclude_database | boolean | `true` if the Home Assistant database file was excluded from this backup |
| extra | dictionary | A dictionary of extra metadata set by client on creation of the backup |
## Stats
@ -271,19 +280,20 @@ The `content` key of a backup object contains the following keys:
## Mount
| key | type | description | request/response |
| ---------- | -------------- | ---------------------------------------------------------------------- | ---------------- |
| name | string | Name of the mount | both |
| type | string | Type of the mount (cifs or nfs) | both |
| usage | string | Usage of the mount (backup, media, or share) | both |
| server | string | IP address or hostname of the network share server | both |
| port | int | Port to use (if not using the standard one for the mount type) | both |
| read_only | bool | Mount is read-only (not available for backup mounts) | both |
| path | string | (nfs mounts only) Path to mount from the network share | both |
| share | string | (cifs mounts only) Share to mount from the network share | both |
| username | string | (cifs mounts only) Username to use for authentication | request only |
| password | string | (cifs mounts only) Password to use for authentication | request only |
| state | string | Current state of the mount (active, failed, etc.) | response only |
| key | type | description | request/response |
| ---------- | -------------- | ----------------------------------------------------------------------------------------------- | ---------------- |
| name | string | Name of the mount | both |
| type | string | Type of the mount (cifs or nfs) | both |
| usage | string | Usage of the mount (backup, media, or share) | both |
| server | string | IP address or hostname of the network share server | both |
| port | int | Port to use (if not using the standard one for the mount type) | both |
| read_only | bool | Mount is read-only (not available for backup mounts) | both |
| path | string | (nfs mounts only) Path to mount from the network share | both |
| share | string | (cifs mounts only) Share to mount from the network share | both |
| username | string | (cifs mounts only) Username to use for authentication | request only |
| password | string | (cifs mounts only) Password to use for authentication | request only |
| state | string | Current state of the mount (active, failed, etc.) | response only |
| user_path | string or null | Path to the mount in add-ons or Home Assistant if it can be made available there, `null` if not | response only |
Request only fields may be included in requests but will never be in responses.
Response only fields will be in responses but cannot be included in requests.