path: root/contrib/libs/yandex-cloud-api-protos/yandex/cloud/backup/v1/backup_service.proto

syntax = "proto3";

package yandex.cloud.backup.v1;

import "google/api/annotations.proto";
import "yandex/cloud/api/operation.proto";
import "yandex/cloud/backup/v1/backup.proto";
import "yandex/cloud/operation/operation.proto";
import "yandex/cloud/validation.proto";

option go_package = "github.com/yandex-cloud/go-genproto/yandex/cloud/backup/v1;backup";
option java_package = "yandex.cloud.api.backup.v1";

// A set of methods for managing [backups](/docs/backup/concepts/backup).
service BackupService {
  // List backups using filters.
  rpc List(ListBackupsRequest) returns (ListBackupsResponse) {
    option (google.api.http) = {get: "/backup/v1/backups"};
  }

  // List archives that holds backups for specified folder or
  // specified [Compute Cloud instance](/docs/backup/concepts/vm-connection#os).
  rpc ListArchives(ListArchivesRequest) returns (ListArchivesResponse) {
    option (google.api.http) = {get: "/backup/v1/backups/{compute_instance_id}/archives"};
  }

  // ListFiles of the backup.
  rpc ListFiles(ListFilesRequest) returns (ListFilesResponse) {
    option (google.api.http) = {get: "/backup/v1/backups/{backup_id}/files"};
  }

  // Get backup by its id.
  rpc Get(GetBackupRequest) returns (Backup) {
    option (google.api.http) = {get: "/backup/v1/backups/{backup_id}"};
  }

  // Start recovery process of specified backup to specific Compute Cloud instance.
  //
  // For details, see [Restoring a VM from a backup](/docs/backup/operations/backup-vm/recover).
  rpc StartRecovery(StartRecoveryRequest) returns (operation.Operation) {
    option (google.api.http) = {
      post: "/backup/v1/backups/{backup_id}:startRecovery"
      body: "*"
    };
    option (yandex.cloud.api.operation) = {
      metadata: "StartRecoveryMetadata"
      response: "google.protobuf.Empty"
    };
  }

  // StartFilesRecovery runs recovery process of selected files to specific Compute Cloud instance.
  rpc StartFilesRecovery(StartFilesRecoveryRequest) returns (operation.Operation) {
    option (yandex.cloud.api.operation) = {
      metadata: "StartFilesRecoveryMetadata"
      response: "google.protobuf.Empty"
    };
  }

  // Delete specific backup.
  rpc Delete(DeleteBackupRequest) returns (operation.Operation) {
    option (google.api.http) = {delete: "/backup/v1/backups/{compute_instance_id}/{backup_id}"};
    option (yandex.cloud.api.operation) = {
      metadata: "DeleteBackupMetadata"
      response: "google.protobuf.Empty"
    };
  }
}

message ListArchivesRequest {
  oneof id {
    option (exactly_one) = true;
    // List of archives in specified folder.
    string folder_id = 1;
    // List of archives of the specified Compute Cloud instance.
    string compute_instance_id = 2;
  }
}

message ListArchivesResponse {
  repeated Archive archives = 1;
}

message ListBackupsRequest {
  message ArchiveParameters {
    // Archive ID.
    string archive_id = 1 [(required) = true];
    // Folder ID.
    string folder_id = 2 [(required) = true];
  }

  message InstancePolicy {
    // Compute Cloud instance ID.
    string compute_instance_id = 1;
    // Policy ID.
    string policy_id = 2;
  }

  oneof id {
    option (exactly_one) = true;
    // List backups that belongs to specific Compute Cloud instance.
    string compute_instance_id = 1;
    // List backups that belongs to specific archive of specific folder.
    ArchiveParameters archive = 2;
    // List backups that belongs to specific folder.
    string folder_id = 3;
    // List backups that belongs to specific instance and policy at the same time.
    InstancePolicy instance_policy = 4;
    // List backups by specific resource ID.
    string resource_id = 6;
    // List backups by specific policy ID.
    string policy_id = 7;
  }

  // By which column the listing should be ordered and in which direction,
  // format is "createdAt desc". "createdAt desc" if omitted.
  string order_by = 5;

  // Filter list by various parameters.
  // Supported parameters are:
  // * created_at
  //
  // Supported logic operators:
  // * AND
  string filter = 8;
}

message ListBackupsResponse {
  repeated Backup backups = 1;
}

message ListFilesRequest {
  // Folder ID.
  string folder_id = 1 [(required) = true];
  // Backup ID.
  string backup_id = 2 [(required) = true];
  // Empty source will list disks of the backup.
  string source_id = 3 [(required) = false];
}

message ListFilesResponse {
  repeated BackupFile files = 1;
}

message GetBackupRequest {
  // Backup ID.
  string backup_id = 1 [(required) = true];
  // Folder ID.
  string folder_id = 2 [(required) = true];
}

message StartRecoveryRequest {
  // Destination Compute Cloud instance ID to which backup should be applied.
  string compute_instance_id = 1 [
    (required) = true,
    (length) = "<=50"
  ];
  // Backup ID that will be applied to destination Compute Cloud instance.
  string backup_id = 2 [(required) = true];
}

message StartRecoveryMetadata {
  // Progress of the backup process.
  double progress_percentage = 1;
  // Source Backup ID that will be applied.
  string src_backup_id = 2;
  // Destination Compute Cloud instance ID to which backup will be applied.
  string dst_compute_instance_id = 3;
}

message TargetPathOriginal {}

message TargetPathCustom {
  // Custom folder for file recovery.
  string path = 1;
}

message FilesRecoveryOptions {
  reserved 3 to 99;
  enum Overwrite {
    // Unspecified value treated as Overwrite all
    OVERWRITE_UNSPECIFIED = 0;
    // All overwrites all existing files by recovered ones.
    OVERWRITE_ALL = 1;
    // Older overwrites older files only.
    OVERWRITE_OLDER = 2;
    // None does not overwrites files at all.
    OVERWRITE_NONE = 3;
  }

  // Overwrite options declares the behavior for files that already exists on the file system.
  Overwrite overwrite = 1 [(required) = false];
  // specifies whether the recovery plan is able to reboot host if needed.
  bool reboot_if_needed = 2 [(required) = false];

  // Path strategy for selected files.
  oneof type {
    option (exactly_one) = true;

    // Keep original paths of files.
    TargetPathOriginal original = 100;
    // Set custom folder for file recovery.
    TargetPathCustom custom = 101;
  }
}

message StartFilesRecoveryRequest {
  // Destination instance ID.
  string compute_instance_id = 1 [(required) = true];
  // Backup ID.
  string backup_id = 2 [(required) = true];
  FilesRecoveryOptions opts = 3 [(required) = true];
  repeated string source_ids = 4 [(size) = ">0"];
}

message StartFilesRecoveryMetadata {
  double progress_percentage = 1;
  // Destination instance ID.
  string compute_instance_id = 2 [(required) = true];
  // Backup ID.
  string backup_id = 3 [(required) = true];
  repeated string source_ids = 4 [(size) = ">0"];
}

message DeleteBackupRequest {
  // Compute Cloud instance ID of the Backup.
  string compute_instance_id = 1 [
    (required) = true,
    (length) = "<=50"
  ];
  // Backup ID that should be deleted.
  string backup_id = 2 [(required) = true];
}

message DeleteBackupMetadata {
  // Compute Cloud instance ID of the Backup.
  string compute_instance_id = 1;
  // Backup ID that should be deleted.
  string backup_id = 2;
}