跳转到正文
皓量云擎文档
接口参考快照与实例备份

编辑备份策略

PATCH /api/v1/backup-policies/{id},updateBackupPolicy 的请求参数和响应结构。

PATCH /api/v1/backup-policies/{id}

项目内容
操作标识updateBackupPolicy
认证登录会话 Cookie

原生 KVM 资源与持久操作。写入需要平台登录、CSRF 及资源权限;执行结果以任务状态和实际观测为准。

会话写请求需要合法的 Origin 和与当前 Cookie 绑定的 X-CSRF-Token。登录成功后应重新获取 CSRF 令牌。具体权限由目标资源归属和当前授权决定,见认证约定。

请求参数

名称位置必填类型说明与约束
idpath是string格式:uuid
Idempotency-Keyheader否string最长 128

请求体

请求体必填。

内容类型:application/json。

字段类型必填说明与约束
namestring是最短 1;最长 64
instance_idstring是格式:uuid
storage_idstring是格式:uuid
schedulestring是可选值:"daily"、"weekly"
run_timestring是Asia/Shanghai 时区 HH:mm;正则:^([01][0-9]|2[0-3]):[0-5][0-9]$
weekdayinteger否周日为 0;最小值 0;最大值 6;默认 1
keep_lastinteger是最小值 1;最大值 365
enabledboolean是—
allow_shutdownboolean是—
descriptionstring否最长 1024
backup_modestring否全量或增量备份,省略时按全量处理。;可选值:"full"、"incremental"
full_everyinteger否增量策略每 N 次备份启动一轮全量,首次及磁盘配置变化时自动全量。;最小值 2;最大值 365
完整请求结构(含引用定义)
{
  "$ref": "#/$defs/BackupPolicyInput",
  "$defs": {
    "BackupPolicyInput": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "name",
        "instance_id",
        "storage_id",
        "schedule",
        "run_time",
        "keep_last",
        "enabled",
        "allow_shutdown"
      ],
      "properties": {
        "name": {
          "type": "string",
          "minLength": 1,
          "maxLength": 64
        },
        "instance_id": {
          "type": "string",
          "format": "uuid"
        },
        "storage_id": {
          "type": "string",
          "format": "uuid"
        },
        "schedule": {
          "type": "string",
          "enum": [
            "daily",
            "weekly"
          ]
        },
        "run_time": {
          "type": "string",
          "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$",
          "description": "Asia/Shanghai 时区 HH:mm"
        },
        "weekday": {
          "type": "integer",
          "minimum": 0,
          "maximum": 6,
          "default": 1,
          "description": "周日为 0"
        },
        "keep_last": {
          "type": "integer",
          "minimum": 1,
          "maximum": 365
        },
        "enabled": {
          "type": "boolean"
        },
        "allow_shutdown": {
          "type": "boolean"
        },
        "description": {
          "type": "string",
          "maxLength": 1024
        },
        "backup_mode": {
          "type": "string",
          "enum": [
            "full",
            "incremental"
          ],
          "description": "全量或增量备份,省略时按全量处理。"
        },
        "full_every": {
          "type": "integer",
          "minimum": 2,
          "maximum": 365,
          "description": "增量策略每 N 次备份启动一轮全量,首次及磁盘配置变化时自动全量。"
        }
      }
    }
  }
}

响应

HTTP 状态含义
200操作已记录;data.id 为任务 UUID,data.resource_id 为资源 UUID。执行是否完成以任务状态和真实观测为准。
400请求无法完成
401请求无法完成
403请求无法完成
404请求无法完成
409请求无法完成
503请求无法完成
200 · application/json 响应结构
字段类型必填说明与约束
dataNativeResource是—
request_idstring是—
{
  "$ref": "#/$defs/NativeResourceResponse",
  "$defs": {
    "NativeResourceResponse": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "data": {
          "$ref": "#/$defs/NativeResource"
        },
        "request_id": {
          "type": "string"
        }
      },
      "required": [
        "data",
        "request_id"
      ]
    },
    "NativeResource": {
      "type": "object",
      "additionalProperties": true,
      "properties": {
        "id": {
          "type": "string",
          "format": "uuid",
          "description": "对象 UUID。异步操作响应中为任务 UUID,资源 UUID 由 resource_id 提供。"
        },
        "name": {
          "type": "string"
        },
        "state": {
          "type": "string"
        },
        "eip_external_network_id": {
          "type": "string",
          "format": "uuid",
          "nullable": true
        },
        "eip_external_network_name": {
          "type": "string",
          "nullable": true
        },
        "publication_state": {
          "type": "string",
          "enum": [
            "allocated",
            "pending",
            "published",
            "withdrawal_pending"
          ],
          "description": "OVN 发布状态,不代表公网探测结果。"
        },
        "published_host_id": {
          "type": "string",
          "format": "uuid",
          "nullable": true
        },
        "created_at": {
          "type": "string",
          "format": "date-time"
        },
        "error": {
          "type": "string"
        },
        "host_id": {
          "type": "string",
          "format": "uuid",
          "nullable": true
        },
        "host_name": {
          "type": "string"
        },
        "availability_zone_id": {
          "type": "string"
        },
        "storage_id": {
          "type": "string"
        },
        "storage_name": {
          "type": "string"
        },
        "storage_type": {
          "$ref": "#/$defs/StorageBackendType"
        },
        "image_id": {
          "type": "string"
        },
        "image_name": {
          "type": "string"
        },
        "flavor_id": {
          "type": "string"
        },
        "flavor_name": {
          "type": "string"
        },
        "network_id": {
          "type": "string"
        },
        "network_name": {
          "type": "string"
        },
        "instance_name": {
          "type": "string",
          "nullable": true
        },
        "architecture": {
          "type": "string"
        },
        "type": {
          "type": "string",
          "description": "资源类型。对于存储池及候选池,表示存储后端类型,当前仅有 local。"
        },
        "selectable": {
          "type": "boolean",
          "description": "存储池是否可作为新磁盘候选,取决于存储状态、主机可达性和地域归属;不表示容量足够。"
        },
        "action": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "ip": {
          "type": "string"
        },
        "mac": {
          "type": "string"
        },
        "cidr": {
          "type": "string",
          "nullable": true
        },
        "gateway": {
          "type": "string"
        },
        "os": {
          "type": "string"
        },
        "version": {
          "type": "string"
        },
        "login_user": {
          "type": "string"
        },
        "guest_os": {
          "type": "string"
        },
        "guest_hostname": {
          "type": "string"
        },
        "updated_at": {
          "type": "string"
        },
        "host_last_seen": {
          "type": "string"
        },
        "region_id": {
          "type": "string"
        },
        "actor_id": {
          "type": "string"
        },
        "actor_name": {
          "type": "string"
        },
        "resource_id": {
          "type": "string",
          "description": "异步操作的目标资源 UUID。"
        },
        "resource_name": {
          "type": "string"
        },
        "status": {
          "type": "string"
        },
        "lifecycle": {
          "type": "string"
        },
        "power_state": {
          "type": "string"
        },
        "readiness": {
          "type": "string"
        },
        "source_url": {
          "type": "string"
        },
        "sha256": {
          "type": "string"
        },
        "description": {
          "type": "string"
        },
        "request_digest": {
          "type": "string"
        },
        "idempotency_key": {
          "type": "string"
        },
        "tenant_id": {
          "type": "string",
          "nullable": true
        },
        "instance_id": {
          "type": "string",
          "nullable": true
        },
        "operation_id": {
          "type": "string",
          "nullable": true
        },
        "recycled_at": {
          "type": "string",
          "nullable": true
        },
        "observed_at": {
          "type": "string",
          "nullable": true
        },
        "vcpus": {
          "type": "integer"
        },
        "memory_mib": {
          "type": "integer"
        },
        "disk_gib": {
          "type": "integer"
        },
        "size_gib": {
          "type": "integer"
        },
        "size_bytes": {
          "type": "integer"
        },
        "capacity_bytes": {
          "type": "integer"
        },
        "available_bytes": {
          "type": "integer"
        },
        "min_disk_gib": {
          "type": "integer"
        },
        "progress": {
          "type": "integer"
        },
        "locked": {
          "type": "boolean"
        },
        "guest_agent": {
          "type": "boolean"
        },
        "enabled": {
          "type": "boolean"
        },
        "ready": {
          "type": "boolean"
        },
        "host_ready": {
          "type": "boolean"
        },
        "host_finished": {
          "type": "boolean"
        },
        "network_ready": {
          "type": "boolean"
        },
        "guest_addresses": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "rules": {
          "type": "array",
          "items": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "direction": {
                "type": "string",
                "enum": [
                  "ingress",
                  "egress"
                ]
              },
              "protocol": {
                "type": "string",
                "enum": [
                  "all",
                  "tcp",
                  "udp",
                  "icmp"
                ]
              },
              "cidr": {
                "type": "string"
              },
              "port_min": {
                "type": "integer"
              },
              "port_max": {
                "type": "integer"
              }
            },
            "required": [
              "direction",
              "protocol",
              "cidr"
            ]
          }
        },
        "events": {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "at",
              "message",
              "progress",
              "state"
            ],
            "properties": {
              "at": {
                "type": "string",
                "format": "date-time"
              },
              "message": {
                "type": "string"
              },
              "progress": {
                "type": "integer"
              },
              "state": {
                "type": "string"
              }
            }
          }
        },
        "provider_name": {
          "type": "string"
        },
        "pool_start": {
          "type": "string"
        },
        "pool_end": {
          "type": "string"
        },
        "external_network_id": {
          "type": "string",
          "format": "uuid",
          "nullable": true
        },
        "external_network_name": {
          "type": "string"
        },
        "external_ip": {
          "type": "string"
        },
        "target_flavor_id": {
          "type": "string",
          "format": "uuid",
          "nullable": true
        },
        "target_security_group_id": {
          "type": "string",
          "format": "uuid",
          "nullable": true
        },
        "target_vcpus": {
          "type": "integer",
          "nullable": true
        },
        "target_memory_mib": {
          "type": "integer",
          "nullable": true
        },
        "target_disk_gib": {
          "type": "integer",
          "nullable": true
        },
        "security_group_name": {
          "type": "string"
        },
        "target_security_group_name": {
          "type": "string",
          "nullable": true
        },
        "agent_version": {
          "type": "string"
        },
        "applied_rules": {
          "type": "array",
          "items": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "direction": {
                "type": "string",
                "enum": [
                  "ingress",
                  "egress"
                ]
              },
              "protocol": {
                "type": "string",
                "enum": [
                  "all",
                  "tcp",
                  "udp",
                  "icmp"
                ]
              },
              "cidr": {
                "type": "string"
              },
              "port_min": {
                "type": "integer"
              },
              "port_max": {
                "type": "integer"
              }
            },
            "required": [
              "direction",
              "protocol",
              "cidr"
            ]
          }
        },
        "target_image_id": {
          "type": "string",
          "format": "uuid",
          "nullable": true
        },
        "target_reinstall_id": {
          "type": "string",
          "format": "uuid",
          "nullable": true
        },
        "target_image_name": {
          "type": "string",
          "nullable": true
        },
        "ssh_keys": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "登录公钥快照。"
        },
        "active_operation": {
          "type": "object",
          "nullable": true,
          "required": [
            "id",
            "action",
            "state",
            "progress",
            "message"
          ],
          "properties": {
            "id": {
              "type": "string",
              "format": "uuid"
            },
            "action": {
              "type": "string"
            },
            "state": {
              "type": "string"
            },
            "progress": {
              "type": "integer"
            },
            "message": {
              "type": "string"
            }
          }
        },
        "public_ip": {
          "type": "string",
          "nullable": true
        },
        "private_ip": {
          "type": "string",
          "nullable": true
        },
        "target_instance_name": {
          "type": "string",
          "nullable": true
        },
        "target_instance_id": {
          "type": "string",
          "format": "uuid",
          "nullable": true
        },
        "vpc_id": {
          "type": "string",
          "format": "uuid",
          "nullable": true
        },
        "vpc_name": {
          "type": "string",
          "nullable": true
        },
        "mode": {
          "type": "string",
          "nullable": true
        },
        "network_mode": {
          "type": "string",
          "nullable": true
        },
        "public_ip_mode": {
          "type": "string",
          "nullable": true
        },
        "address_scope": {
          "type": "string",
          "nullable": true
        },
        "allocation_type": {
          "type": "string",
          "nullable": true
        },
        "subnet_count": {
          "type": "integer"
        },
        "instance_count": {
          "type": "integer"
        },
        "pool_size": {
          "type": "integer"
        },
        "allocated_count": {
          "type": "integer"
        },
        "vlan_id": {
          "type": "integer"
        },
        "mtu": {
          "type": "integer"
        },
        "dns_servers": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "nullable": true
        },
        "format": {
          "type": "string"
        },
        "image_format": {
          "type": "string"
        },
        "path": {
          "type": "string"
        },
        "verified_at": {
          "type": "string"
        },
        "installation_state": {
          "type": "string"
        },
        "replica_count": {
          "type": "integer"
        },
        "ready_replica_count": {
          "type": "integer"
        },
        "virtual_size_bytes": {
          "type": "integer"
        },
        "cloud_init_enabled": {
          "type": "boolean"
        },
        "qemu_guest_agent_enabled": {
          "type": "boolean"
        },
        "installation_replica_id": {
          "type": "string",
          "format": "uuid",
          "nullable": true
        },
        "ready_storage_ids": {
          "type": "array",
          "items": {
            "type": "string",
            "format": "uuid"
          }
        },
        "operations": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/NativeResource"
          }
        },
        "configuration": {
          "type": "object",
          "additionalProperties": true
        },
        "format_version": {
          "type": "integer"
        },
        "source_name": {
          "type": "string"
        },
        "policy_id": {
          "type": "string",
          "nullable": true
        },
        "schedule": {
          "type": "string"
        },
        "run_time": {
          "type": "string"
        },
        "weekday": {
          "type": "integer"
        },
        "keep_last": {
          "type": "integer"
        },
        "allow_shutdown": {
          "type": "boolean"
        },
        "next_run_at": {
          "type": "string",
          "format": "date-time"
        },
        "scheduled_at": {
          "type": "string",
          "format": "date-time"
        },
        "result_message": {
          "type": "string"
        },
        "target_checkpoint_id": {
          "type": "string",
          "nullable": true
        },
        "instance_state": {
          "type": "string",
          "nullable": true,
          "description": "挂载实例的实际状态"
        },
        "instance_locked": {
          "type": "boolean",
          "nullable": true,
          "description": "挂载实例是否锁定"
        },
        "instance_recycled_at": {
          "type": "string",
          "nullable": true,
          "description": "挂载实例的回收时间"
        },
        "instance_busy": {
          "type": "boolean",
          "description": "挂载实例存在执行中任务或未完成变更"
        },
        "target": {
          "type": "string",
          "description": "客户机中的磁盘设备名,如 vdb"
        },
        "hostname": {
          "type": "string",
          "description": "已配置的客户机主机名"
        },
        "target_hostname": {
          "type": "string",
          "nullable": true,
          "description": "尚未完成的目标主机名"
        },
        "tags": {
          "type": "array",
          "items": {
            "type": "string",
            "minLength": 1,
            "maxLength": 32
          },
          "maxItems": 20,
          "description": "资源标签,去除首尾空格并去重"
        },
        "cluster_id": {
          "type": "string",
          "format": "uuid",
          "nullable": true
        },
        "cluster_name": {
          "type": "string"
        },
        "cluster_status": {
          "type": "string"
        },
        "code": {
          "type": "string"
        },
        "online": {
          "type": "boolean"
        },
        "schedulable": {
          "type": "boolean"
        },
        "member_count": {
          "type": "integer",
          "format": "int64"
        },
        "online_count": {
          "type": "integer",
          "format": "int64"
        },
        "schedulable_count": {
          "type": "integer",
          "format": "int64"
        },
        "allocated_vcpus": {
          "type": "integer",
          "format": "int64"
        },
        "allocated_memory_mib": {
          "type": "integer",
          "format": "int64"
        },
        "available_vcpus": {
          "type": "integer",
          "format": "int64"
        },
        "available_memory_mib": {
          "type": "integer",
          "format": "int64"
        },
        "joined_at": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "availability_zone_name": {
          "type": "string"
        },
        "created_by": {
          "type": "string",
          "format": "uuid",
          "nullable": true,
          "readOnly": true,
          "description": "实例创建用户,由服务端取当前认证用户。历史创建记录缺失时为空。"
        },
        "creator_name": {
          "type": "string",
          "nullable": true,
          "readOnly": true
        },
        "creator_username": {
          "type": "string",
          "nullable": true,
          "readOnly": true
        },
        "tenant_name": {
          "type": "string",
          "readOnly": true
        },
        "backup_mode": {
          "type": "string",
          "enum": [
            "full",
            "incremental"
          ],
          "description": "全量或增量备份,省略时按全量处理。"
        },
        "parent_backup_id": {
          "type": "string",
          "format": "uuid",
          "nullable": true
        },
        "parent_backup_name": {
          "type": "string",
          "nullable": true
        },
        "chain_depth": {
          "type": "integer",
          "minimum": 0
        },
        "dependent_count": {
          "type": "integer",
          "minimum": 0
        },
        "stored_bytes": {
          "type": "integer",
          "format": "int64",
          "nullable": true,
          "minimum": 0
        },
        "full_every": {
          "type": "integer",
          "minimum": 2,
          "maximum": 365
        },
        "os_type": {
          "type": "string",
          "enum": [
            "linux",
            "windows"
          ],
          "description": "客户机系统类型;Windows 自动初始化通过 QEMU Guest Agent 执行。"
        },
        "firmware": {
          "type": "string",
          "enum": [
            "bios",
            "uefi"
          ],
          "description": "启动固件。新 Windows 实例必须使用 UEFI,镜像须已具备 GPT/EFI 引导。"
        },
        "available_ip_count": {
          "description": "按实际自动分配范围计算的剩余 IP 数量。",
          "type": "integer",
          "minimum": 0
        },
        "assigned_user_id": {
          "type": "string",
          "format": "uuid",
          "nullable": true
        },
        "assignee_name": {
          "type": "string",
          "nullable": true
        },
        "assignee_username": {
          "type": "string",
          "nullable": true
        },
        "note": {
          "type": "string",
          "description": "手动预留地址的备注。"
        },
        "storage_group": {
          "type": "string",
          "description": "当前网络下的本地存储兼容组标识。"
        },
        "upload_limit_kbps": {
          "type": "integer",
          "minimum": 1,
          "maximum": 4294967295,
          "nullable": true,
          "description": "上行带宽上限,单位 kbps。对应实例发出的流量。空值表示不限速。"
        },
        "download_limit_kbps": {
          "type": "integer",
          "minimum": 1,
          "maximum": 4294967295,
          "nullable": true,
          "description": "下行带宽上限,单位 kbps。对应实例接收的流量。空值表示不限速。"
        },
        "max_iops": {
          "type": "integer",
          "minimum": 1,
          "maximum": 1000000,
          "nullable": true,
          "description": "读写合计 IOPS 上限。空值表示不限速。"
        },
        "max_bytes_per_second": {
          "type": "integer",
          "format": "int64",
          "minimum": 1,
          "maximum": 1099511627776,
          "nullable": true,
          "description": "读写合计吞吐量上限,单位字节/秒。空值表示不限速。"
        }
      },
      "required": [
        "id"
      ]
    },
    "StorageBackendType": {
      "type": "string",
      "enum": [
        "local",
        "lvm",
        "rbd"
      ],
      "description": "存储后端类型,与云硬盘用途无关:local(本地目录 / QCOW2)、lvm(本地专用 VG 逻辑卷)、rbd(Ceph RBD 镜像)。"
    }
  }
}
400 / 401 / 403 / 404 / 409 / 503 · application/json 响应结构
{
  "$ref": "#/$defs/ErrorResponse",
  "$defs": {
    "ErrorResponse": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "error": {
          "$ref": "#/$defs/ErrorDetail"
        },
        "request_id": {
          "type": "string"
        }
      },
      "required": [
        "error",
        "request_id"
      ]
    },
    "ErrorDetail": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "NOT_IMPLEMENTED",
            "NOT_FOUND",
            "AUTH_REQUIRED",
            "FORBIDDEN",
            "VALIDATION_FAILED",
            "CONFLICT",
            "SERVICE_UNAVAILABLE",
            "INTERNAL_ERROR",
            "RATE_LIMITED"
          ]
        },
        "message": {
          "type": "string"
        },
        "retryable": {
          "type": "boolean"
        },
        "fields": {
          "type": "object",
          "additionalProperties": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "required": [
        "code",
        "message",
        "retryable"
      ]
    }
  }
}

响应中的 request_id 用于排查请求;异步操作以任务最终状态为准。参阅调用约定、异步任务和错误处理。

本页由版本化 OpenAPI 契约生成。通用资源响应允许的任意字段以运行服务为准,不据此推断尚未定义的字段。

本页目录