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-15 13:26: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

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

@ -781,8 +781,10 @@ Return a list of [Backups](api/supervisor/models.md#backup)
"name": "Awesome backup", "name": "Awesome backup",
"type": "partial", "type": "partial",
"size": 44, "size": 44,
"size_bytes": 44070259,
"protected": true, "protected": true,
"location": "MountedBackups", "location": "MountedBackups",
"locations": ["MountedBackups"],
"compressed": true, "compressed": true,
"content": { "content": {
"homeassistant": true, "homeassistant": true,
@ -818,9 +820,11 @@ Return information about backup manager.
"name": "Awesome backup", "name": "Awesome backup",
"type": "partial", "type": "partial",
"size": 44, "size": 44,
"size_bytes": 44070259,
"protected": true, "protected": true,
"compressed": true, "compressed": true,
"location": null, "location": null,
"locations": [null],
"content": { "content": {
"homeassistant": true, "homeassistant": true,
"addons": ["awesome_addon"], "addons": ["awesome_addon"],
@ -845,24 +849,45 @@ Create a full backup.
| name | string | True | The name you want to give the backup | | name | string | True | The name you want to give the backup |
| password | string | True | The password 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 | | 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 | | 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. | | 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:** **Example response:**
```json ```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>
<ApiEndpoint path="/backups/new/upload" method="post"> <ApiEndpoint path="/backups/new/upload" method="post">
Upload a backup. 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:** **Example response:**
```json ```json
@ -891,15 +916,16 @@ Create a partial backup.
| ------------------------------ | -------------- | -------- | ---------------------------------------------------- | | ------------------------------ | -------------- | -------- | ---------------------------------------------------- |
| name | string | True | The name you want to give the backup | | name | string | True | The name you want to give the backup |
| password | string | True | The password 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 | | homeassistant | boolean | Content | Add home assistant core settings to the backup |
| addons | list | True | A list of strings representing add-on slugs | | 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 | True | A list of strings representing directories | | folders | list | Content | A list of strings representing directories |
| compressed | boolean | True | `false` to create uncompressed backups | | 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 | | 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. | | 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:** **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. 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>
<ApiEndpoint path="/backups/<backup>/info" method="get"> <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. 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>
<ApiEndpoint path="/backups/<backup>/restore/full" method="post"> <ApiEndpoint path="/backups/<backup>/restore/full" method="post">
@ -989,9 +1032,10 @@ Does a full restore of the backup with the given slug.
**Payload:** **Payload:**
| key | type | optional | description | | key | type | optional | description |
| ---------- | ------- | -------- | ------------------------------------ | | ---------- | -------------- | -------- | ------------------------------------ |
| password | string | True | The password for the backup if any | | 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. | | 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:** **Example response:**
@ -1017,14 +1061,15 @@ Does a partial restore of the backup with the given slug.
**Payload:** **Payload:**
| key | type | optional | description | | key | type | optional | description |
| ------------- | ------- | -------- | ---------------------------------------------- | | ------------- | -------------- | -------- | ---------------------------------------------- |
| homeassistant | boolean | True | `true` if Home Assistant should be restored | | homeassistant | boolean | Content | `true` if Home Assistant should be restored |
| addons | list | True | A list of add-on slugs that should be restored | | addons | list | Content | A list of add-on slugs that should be restored |
| folders | list | True | A list of directories 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 | | 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. | | 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:** **Example response:**
@ -2105,7 +2150,8 @@ Returns information about mounts configured in Supervisor
"server": "server.local", "server": "server.local",
"share": "media", "share": "media",
"state": "active", "state": "active",
"read_only": false "read_only": false,
"user_path": "/media/my_share"
} }
] ]
} }

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

@ -169,11 +169,15 @@ These models are describing objects that are getting returned from the superviso
## Backup ## Backup
| key | type | description | | key | type | description |
| --------- | ------- | --------------------------------------------------------------------- | | ---------- | -------------- | -------------------------------------------------------------------------------------- |
| slug | string | A generated slug for the backup | | slug | string | A generated slug for the backup |
| date | string | ISO date string representation of the date the backup was created | | date | string | ISO date string representation of the date the backup was created |
| name | string | The name given to the backup | | name | string | The name given to the backup |
| type | string | The type of backup (full, partial) | | 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 | | protected | boolean | `true` if the backup is password protected |
| content | dictionary | A dictionary describing the content of the backup | | content | dictionary | A dictionary describing the content of the backup |
| compressed | boolean | `true` if the backup is saved in a compressed archive | | compressed | boolean | `true` if the backup is saved in a compressed archive |
@ -196,14 +200,19 @@ The `content` key of a backup object contains the following keys:
| type | string | The type of backup (full, partial) | | type | string | The type of backup (full, partial) |
| name | string | The name given to the backup | | name | string | The name given to the backup |
| date | string | ISO date string representation of the date the backup was created | | 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 | | protected | boolean | `true` if the backup is password protected |
| 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. | | 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 | | 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`] | | 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 | | repositories | list | A list of add-on repository URL's as strings |
| folders | list | A list of strings representing directories | | folders | list | A list of strings representing directories |
| homeassistant_exclude_database | boolean | `true` if the Home Assistant database file was excluded from this backup | | 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 ## Stats
@ -272,7 +281,7 @@ The `content` key of a backup object contains the following keys:
## Mount ## Mount
| key | type | description | request/response | | key | type | description | request/response |
| ---------- | -------------- | ---------------------------------------------------------------------- | ---------------- | | ---------- | -------------- | ----------------------------------------------------------------------------------------------- | ---------------- |
| name | string | Name of the mount | both | | name | string | Name of the mount | both |
| type | string | Type of the mount (cifs or nfs) | both | | type | string | Type of the mount (cifs or nfs) | both |
| usage | string | Usage of the mount (backup, media, or share) | both | | usage | string | Usage of the mount (backup, media, or share) | both |
@ -284,6 +293,7 @@ The `content` key of a backup object contains the following keys:
| username | string | (cifs mounts only) Username to use for authentication | request only | | username | string | (cifs mounts only) Username to use for authentication | request only |
| password | string | (cifs mounts only) Password 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 | | 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. 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. Response only fields will be in responses but cannot be included in requests.