367 lines
16 KiB
Protocol Buffer
367 lines
16 KiB
Protocol Buffer
// Copyright 2020 Google LLC
|
|
//
|
|
// Licensed under the Apache License, Version 2.0 (the "License");
|
|
// you may not use this file except in compliance with the License.
|
|
// You may obtain a copy of the License at
|
|
//
|
|
// http://www.apache.org/licenses/LICENSE-2.0
|
|
//
|
|
// Unless required by applicable law or agreed to in writing, software
|
|
// distributed under the License is distributed on an "AS IS" BASIS,
|
|
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
// See the License for the specific language governing permissions and
|
|
// limitations under the License.
|
|
|
|
syntax = "proto3";
|
|
|
|
package google.spanner.admin.database.v1;
|
|
|
|
import "google/api/field_behavior.proto";
|
|
import "google/api/resource.proto";
|
|
import "google/longrunning/operations.proto";
|
|
import "google/protobuf/field_mask.proto";
|
|
import "google/protobuf/timestamp.proto";
|
|
import "google/spanner/admin/database/v1/common.proto";
|
|
import "google/api/annotations.proto";
|
|
|
|
option csharp_namespace = "Google.Cloud.Spanner.Admin.Database.V1";
|
|
option go_package = "google.golang.org/genproto/googleapis/spanner/admin/database/v1;database";
|
|
option java_multiple_files = true;
|
|
option java_outer_classname = "BackupProto";
|
|
option java_package = "com.google.spanner.admin.database.v1";
|
|
option php_namespace = "Google\\Cloud\\Spanner\\Admin\\Database\\V1";
|
|
option ruby_package = "Google::Cloud::Spanner::Admin::Database::V1";
|
|
|
|
// A backup of a Cloud Spanner database.
|
|
message Backup {
|
|
option (google.api.resource) = {
|
|
type: "spanner.googleapis.com/Backup"
|
|
pattern: "projects/{project}/instances/{instance}/backups/{backup}"
|
|
};
|
|
|
|
// Indicates the current state of the backup.
|
|
enum State {
|
|
// Not specified.
|
|
STATE_UNSPECIFIED = 0;
|
|
|
|
// The pending backup is still being created. Operations on the
|
|
// backup may fail with `FAILED_PRECONDITION` in this state.
|
|
CREATING = 1;
|
|
|
|
// The backup is complete and ready for use.
|
|
READY = 2;
|
|
}
|
|
|
|
// Required for the [CreateBackup][google.spanner.admin.database.v1.DatabaseAdmin.CreateBackup] operation.
|
|
// Name of the database from which this backup was
|
|
// created. This needs to be in the same instance as the backup.
|
|
// Values are of the form
|
|
// `projects/<project>/instances/<instance>/databases/<database>`.
|
|
string database = 2 [(google.api.resource_reference) = {
|
|
type: "spanner.googleapis.com/Database"
|
|
}];
|
|
|
|
// Required for the [CreateBackup][google.spanner.admin.database.v1.DatabaseAdmin.CreateBackup]
|
|
// operation. The expiration time of the backup, with microseconds
|
|
// granularity that must be at least 6 hours and at most 366 days
|
|
// from the time the CreateBackup request is processed. Once the `expire_time`
|
|
// has passed, the backup is eligible to be automatically deleted by Cloud
|
|
// Spanner to free the resources used by the backup.
|
|
google.protobuf.Timestamp expire_time = 3;
|
|
|
|
// Output only for the [CreateBackup][google.spanner.admin.database.v1.DatabaseAdmin.CreateBackup] operation.
|
|
// Required for the [UpdateBackup][google.spanner.admin.database.v1.DatabaseAdmin.UpdateBackup] operation.
|
|
//
|
|
// A globally unique identifier for the backup which cannot be
|
|
// changed. Values are of the form
|
|
// `projects/<project>/instances/<instance>/backups/[a-z][a-z0-9_\-]*[a-z0-9]`
|
|
// The final segment of the name must be between 2 and 60 characters
|
|
// in length.
|
|
//
|
|
// The backup is stored in the location(s) specified in the instance
|
|
// configuration of the instance containing the backup, identified
|
|
// by the prefix of the backup name of the form
|
|
// `projects/<project>/instances/<instance>`.
|
|
string name = 1;
|
|
|
|
// Output only. The backup will contain an externally consistent
|
|
// copy of the database at the timestamp specified by
|
|
// `create_time`. `create_time` is approximately the time the
|
|
// [CreateBackup][google.spanner.admin.database.v1.DatabaseAdmin.CreateBackup] request is received.
|
|
google.protobuf.Timestamp create_time = 4 [(google.api.field_behavior) = OUTPUT_ONLY];
|
|
|
|
// Output only. Size of the backup in bytes.
|
|
int64 size_bytes = 5 [(google.api.field_behavior) = OUTPUT_ONLY];
|
|
|
|
// Output only. The current state of the backup.
|
|
State state = 6 [(google.api.field_behavior) = OUTPUT_ONLY];
|
|
|
|
// Output only. The names of the restored databases that reference the backup.
|
|
// The database names are of
|
|
// the form `projects/<project>/instances/<instance>/databases/<database>`.
|
|
// Referencing databases may exist in different instances. The existence of
|
|
// any referencing database prevents the backup from being deleted. When a
|
|
// restored database from the backup enters the `READY` state, the reference
|
|
// to the backup is removed.
|
|
repeated string referencing_databases = 7 [(google.api.field_behavior) = OUTPUT_ONLY];
|
|
}
|
|
|
|
// The request for [CreateBackup][google.spanner.admin.database.v1.DatabaseAdmin.CreateBackup].
|
|
message CreateBackupRequest {
|
|
// Required. The name of the instance in which the backup will be
|
|
// created. This must be the same instance that contains the database the
|
|
// backup will be created from. The backup will be stored in the
|
|
// location(s) specified in the instance configuration of this
|
|
// instance. Values are of the form
|
|
// `projects/<project>/instances/<instance>`.
|
|
string parent = 1 [
|
|
(google.api.field_behavior) = REQUIRED,
|
|
(google.api.resource_reference) = {
|
|
type: "spanner.googleapis.com/Instance"
|
|
}
|
|
];
|
|
|
|
// Required. The id of the backup to be created. The `backup_id` appended to
|
|
// `parent` forms the full backup name of the form
|
|
// `projects/<project>/instances/<instance>/backups/<backup_id>`.
|
|
string backup_id = 2 [(google.api.field_behavior) = REQUIRED];
|
|
|
|
// Required. The backup to create.
|
|
Backup backup = 3 [(google.api.field_behavior) = REQUIRED];
|
|
}
|
|
|
|
// Metadata type for the operation returned by
|
|
// [CreateBackup][google.spanner.admin.database.v1.DatabaseAdmin.CreateBackup].
|
|
message CreateBackupMetadata {
|
|
// The name of the backup being created.
|
|
string name = 1;
|
|
|
|
// The name of the database the backup is created from.
|
|
string database = 2;
|
|
|
|
// The progress of the
|
|
// [CreateBackup][google.spanner.admin.database.v1.DatabaseAdmin.CreateBackup] operation.
|
|
OperationProgress progress = 3;
|
|
|
|
// The time at which cancellation of this operation was received.
|
|
// [Operations.CancelOperation][google.longrunning.Operations.CancelOperation]
|
|
// starts asynchronous cancellation on a long-running operation. The server
|
|
// makes a best effort to cancel the operation, but success is not guaranteed.
|
|
// Clients can use
|
|
// [Operations.GetOperation][google.longrunning.Operations.GetOperation] or
|
|
// other methods to check whether the cancellation succeeded or whether the
|
|
// operation completed despite cancellation. On successful cancellation,
|
|
// the operation is not deleted; instead, it becomes an operation with
|
|
// an [Operation.error][] value with a [google.rpc.Status.code][google.rpc.Status.code] of 1,
|
|
// corresponding to `Code.CANCELLED`.
|
|
google.protobuf.Timestamp cancel_time = 4;
|
|
}
|
|
|
|
// The request for [UpdateBackup][google.spanner.admin.database.v1.DatabaseAdmin.UpdateBackup].
|
|
message UpdateBackupRequest {
|
|
// Required. The backup to update. `backup.name`, and the fields to be updated
|
|
// as specified by `update_mask` are required. Other fields are ignored.
|
|
// Update is only supported for the following fields:
|
|
// * `backup.expire_time`.
|
|
Backup backup = 1 [(google.api.field_behavior) = REQUIRED];
|
|
|
|
// Required. A mask specifying which fields (e.g. `expire_time`) in the
|
|
// Backup resource should be updated. This mask is relative to the Backup
|
|
// resource, not to the request message. The field mask must always be
|
|
// specified; this prevents any future fields from being erased accidentally
|
|
// by clients that do not know about them.
|
|
google.protobuf.FieldMask update_mask = 2 [(google.api.field_behavior) = REQUIRED];
|
|
}
|
|
|
|
// The request for [GetBackup][google.spanner.admin.database.v1.DatabaseAdmin.GetBackup].
|
|
message GetBackupRequest {
|
|
// Required. Name of the backup.
|
|
// Values are of the form
|
|
// `projects/<project>/instances/<instance>/backups/<backup>`.
|
|
string name = 1 [
|
|
(google.api.field_behavior) = REQUIRED,
|
|
(google.api.resource_reference) = {
|
|
type: "spanner.googleapis.com/Backup"
|
|
}
|
|
];
|
|
}
|
|
|
|
// The request for [DeleteBackup][google.spanner.admin.database.v1.DatabaseAdmin.DeleteBackup].
|
|
message DeleteBackupRequest {
|
|
// Required. Name of the backup to delete.
|
|
// Values are of the form
|
|
// `projects/<project>/instances/<instance>/backups/<backup>`.
|
|
string name = 1 [
|
|
(google.api.field_behavior) = REQUIRED,
|
|
(google.api.resource_reference) = {
|
|
type: "spanner.googleapis.com/Backup"
|
|
}
|
|
];
|
|
}
|
|
|
|
// The request for [ListBackups][google.spanner.admin.database.v1.DatabaseAdmin.ListBackups].
|
|
message ListBackupsRequest {
|
|
// Required. The instance to list backups from. Values are of the
|
|
// form `projects/<project>/instances/<instance>`.
|
|
string parent = 1 [
|
|
(google.api.field_behavior) = REQUIRED,
|
|
(google.api.resource_reference) = {
|
|
type: "spanner.googleapis.com/Instance"
|
|
}
|
|
];
|
|
|
|
// An expression that filters the list of returned backups.
|
|
//
|
|
// A filter expression consists of a field name, a comparison operator, and a
|
|
// value for filtering.
|
|
// The value must be a string, a number, or a boolean. The comparison operator
|
|
// must be one of: `<`, `>`, `<=`, `>=`, `!=`, `=`, or `:`.
|
|
// Colon `:` is the contains operator. Filter rules are not case sensitive.
|
|
//
|
|
// The following fields in the [Backup][google.spanner.admin.database.v1.Backup] are eligible for filtering:
|
|
//
|
|
// * `name`
|
|
// * `database`
|
|
// * `state`
|
|
// * `create_time` (and values are of the format YYYY-MM-DDTHH:MM:SSZ)
|
|
// * `expire_time` (and values are of the format YYYY-MM-DDTHH:MM:SSZ)
|
|
// * `size_bytes`
|
|
//
|
|
// You can combine multiple expressions by enclosing each expression in
|
|
// parentheses. By default, expressions are combined with AND logic, but
|
|
// you can specify AND, OR, and NOT logic explicitly.
|
|
//
|
|
// Here are a few examples:
|
|
//
|
|
// * `name:Howl` - The backup's name contains the string "howl".
|
|
// * `database:prod`
|
|
// - The database's name contains the string "prod".
|
|
// * `state:CREATING` - The backup is pending creation.
|
|
// * `state:READY` - The backup is fully created and ready for use.
|
|
// * `(name:howl) AND (create_time < \"2018-03-28T14:50:00Z\")`
|
|
// - The backup name contains the string "howl" and `create_time`
|
|
// of the backup is before 2018-03-28T14:50:00Z.
|
|
// * `expire_time < \"2018-03-28T14:50:00Z\"`
|
|
// - The backup `expire_time` is before 2018-03-28T14:50:00Z.
|
|
// * `size_bytes > 10000000000` - The backup's size is greater than 10GB
|
|
string filter = 2;
|
|
|
|
// Number of backups to be returned in the response. If 0 or
|
|
// less, defaults to the server's maximum allowed page size.
|
|
int32 page_size = 3;
|
|
|
|
// If non-empty, `page_token` should contain a
|
|
// [next_page_token][google.spanner.admin.database.v1.ListBackupsResponse.next_page_token] from a
|
|
// previous [ListBackupsResponse][google.spanner.admin.database.v1.ListBackupsResponse] to the same `parent` and with the same
|
|
// `filter`.
|
|
string page_token = 4;
|
|
}
|
|
|
|
// The response for [ListBackups][google.spanner.admin.database.v1.DatabaseAdmin.ListBackups].
|
|
message ListBackupsResponse {
|
|
// The list of matching backups. Backups returned are ordered by `create_time`
|
|
// in descending order, starting from the most recent `create_time`.
|
|
repeated Backup backups = 1;
|
|
|
|
// `next_page_token` can be sent in a subsequent
|
|
// [ListBackups][google.spanner.admin.database.v1.DatabaseAdmin.ListBackups] call to fetch more
|
|
// of the matching backups.
|
|
string next_page_token = 2;
|
|
}
|
|
|
|
// The request for
|
|
// [ListBackupOperations][google.spanner.admin.database.v1.DatabaseAdmin.ListBackupOperations].
|
|
message ListBackupOperationsRequest {
|
|
// Required. The instance of the backup operations. Values are of
|
|
// the form `projects/<project>/instances/<instance>`.
|
|
string parent = 1 [
|
|
(google.api.field_behavior) = REQUIRED,
|
|
(google.api.resource_reference) = {
|
|
type: "spanner.googleapis.com/Instance"
|
|
}
|
|
];
|
|
|
|
// An expression that filters the list of returned backup operations.
|
|
//
|
|
// A filter expression consists of a field name, a
|
|
// comparison operator, and a value for filtering.
|
|
// The value must be a string, a number, or a boolean. The comparison operator
|
|
// must be one of: `<`, `>`, `<=`, `>=`, `!=`, `=`, or `:`.
|
|
// Colon `:` is the contains operator. Filter rules are not case sensitive.
|
|
//
|
|
// The following fields in the [operation][google.longrunning.Operation]
|
|
// are eligible for filtering:
|
|
//
|
|
// * `name` - The name of the long-running operation
|
|
// * `done` - False if the operation is in progress, else true.
|
|
// * `metadata.@type` - the type of metadata. For example, the type string
|
|
// for [CreateBackupMetadata][google.spanner.admin.database.v1.CreateBackupMetadata] is
|
|
// `type.googleapis.com/google.spanner.admin.database.v1.CreateBackupMetadata`.
|
|
// * `metadata.<field_name>` - any field in metadata.value.
|
|
// * `error` - Error associated with the long-running operation.
|
|
// * `response.@type` - the type of response.
|
|
// * `response.<field_name>` - any field in response.value.
|
|
//
|
|
// You can combine multiple expressions by enclosing each expression in
|
|
// parentheses. By default, expressions are combined with AND logic, but
|
|
// you can specify AND, OR, and NOT logic explicitly.
|
|
//
|
|
// Here are a few examples:
|
|
//
|
|
// * `done:true` - The operation is complete.
|
|
// * `metadata.database:prod` - The database the backup was taken from has
|
|
// a name containing the string "prod".
|
|
// * `(metadata.@type=type.googleapis.com/google.spanner.admin.database.v1.CreateBackupMetadata) AND` <br/>
|
|
// `(metadata.name:howl) AND` <br/>
|
|
// `(metadata.progress.start_time < \"2018-03-28T14:50:00Z\") AND` <br/>
|
|
// `(error:*)` - Returns operations where:
|
|
// * The operation's metadata type is [CreateBackupMetadata][google.spanner.admin.database.v1.CreateBackupMetadata].
|
|
// * The backup name contains the string "howl".
|
|
// * The operation started before 2018-03-28T14:50:00Z.
|
|
// * The operation resulted in an error.
|
|
string filter = 2;
|
|
|
|
// Number of operations to be returned in the response. If 0 or
|
|
// less, defaults to the server's maximum allowed page size.
|
|
int32 page_size = 3;
|
|
|
|
// If non-empty, `page_token` should contain a
|
|
// [next_page_token][google.spanner.admin.database.v1.ListBackupOperationsResponse.next_page_token]
|
|
// from a previous [ListBackupOperationsResponse][google.spanner.admin.database.v1.ListBackupOperationsResponse] to the
|
|
// same `parent` and with the same `filter`.
|
|
string page_token = 4;
|
|
}
|
|
|
|
// The response for
|
|
// [ListBackupOperations][google.spanner.admin.database.v1.DatabaseAdmin.ListBackupOperations].
|
|
message ListBackupOperationsResponse {
|
|
// The list of matching backup [long-running
|
|
// operations][google.longrunning.Operation]. Each operation's name will be
|
|
// prefixed by the backup's name and the operation's
|
|
// [metadata][google.longrunning.Operation.metadata] will be of type
|
|
// [CreateBackupMetadata][google.spanner.admin.database.v1.CreateBackupMetadata]. Operations returned include those that are
|
|
// pending or have completed/failed/canceled within the last 7 days.
|
|
// Operations returned are ordered by
|
|
// `operation.metadata.value.progress.start_time` in descending order starting
|
|
// from the most recently started operation.
|
|
repeated google.longrunning.Operation operations = 1;
|
|
|
|
// `next_page_token` can be sent in a subsequent
|
|
// [ListBackupOperations][google.spanner.admin.database.v1.DatabaseAdmin.ListBackupOperations]
|
|
// call to fetch more of the matching metadata.
|
|
string next_page_token = 2;
|
|
}
|
|
|
|
// Information about a backup.
|
|
message BackupInfo {
|
|
// Name of the backup.
|
|
string backup = 1;
|
|
|
|
// The backup contains an externally consistent copy of `source_database` at
|
|
// the timestamp specified by `create_time`.
|
|
google.protobuf.Timestamp create_time = 2;
|
|
|
|
// Name of the database the backup was created from.
|
|
string source_database = 3;
|
|
}
|