1 // Copyright 2018 Google LLC
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
7 // http://www.apache.org/licenses/LICENSE-2.0
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
17 package google.datastore.admin.v1;
19 import "google/api/annotations.proto";
20 import "google/datastore/admin/v1/index.proto";
21 import "google/longrunning/operations.proto";
22 import "google/protobuf/timestamp.proto";
24 option csharp_namespace = "Google.Cloud.Datastore.Admin.V1";
25 option go_package = "google.golang.org/genproto/googleapis/datastore/admin/v1;admin";
26 option java_multiple_files = true;
27 option java_outer_classname = "DatastoreAdminProto";
28 option java_package = "com.google.datastore.admin.v1";
30 // Google Cloud Datastore Admin API
32 // The Datastore Admin API provides several admin services for Cloud Datastore.
34 // -----------------------------------------------------------------------------
37 // Project, namespace, kind, and entity as defined in the Google Cloud Datastore
40 // Operation: An Operation represents work being performed in the background.
42 // EntityFilter: Allows specifying a subset of entities in a project. This is
43 // specified as a combination of kinds and namespaces (either or both of which
46 // -----------------------------------------------------------------------------
51 // The Export/Import service provides the ability to copy all or a subset of
52 // entities to/from Google Cloud Storage.
54 // Exported data may be imported into Cloud Datastore for any Google Cloud
55 // Platform project. It is not restricted to the export source project. It is
56 // possible to export from one project and then import into another.
58 // Exported data can also be loaded into Google BigQuery for analysis.
60 // Exports and imports are performed asynchronously. An Operation resource is
61 // created for each export/import. The state (including any errors encountered)
62 // of the export/import may be queried via the Operation resource.
66 // The index service manages Cloud Datastore composite indexes.
68 // Index creation and deletion are performed asynchronously.
69 // An Operation resource is created for each such asynchronous operation.
70 // The state of the operation (including any errors encountered)
71 // may be queried via the Operation resource.
75 // The Operations collection provides a record of actions performed for the
76 // specified project (including any operations in progress). Operations are not
77 // created directly but through calls on other collections or resources.
79 // An operation that is not yet done may be cancelled. The request to cancel is
80 // asynchronous and the operation may continue to run for some time after the
81 // request to cancel is made.
83 // An operation that is done may be deleted so that it is no longer listed as
84 // part of the Operation collection.
86 // ListOperations returns all pending operations, but not completed operations.
88 // Operations are created by service DatastoreAdmin,
89 // but are accessed via service google.longrunning.Operations.
90 service DatastoreAdmin {
91 // Exports a copy of all or a subset of entities from Google Cloud Datastore
92 // to another storage system, such as Google Cloud Storage. Recent updates to
93 // entities may not be reflected in the export. The export occurs in the
94 // background and its progress can be monitored and managed via the
95 // Operation resource that is created. The output of an export may only be
96 // used once the associated operation is done. If an export operation is
97 // cancelled before completion it may leave partial data behind in Google
99 rpc ExportEntities(ExportEntitiesRequest)
100 returns (google.longrunning.Operation) {
101 option (google.api.http) = {
102 post: "/v1/projects/{project_id}:export"
107 // Imports entities into Google Cloud Datastore. Existing entities with the
108 // same key are overwritten. The import occurs in the background and its
109 // progress can be monitored and managed via the Operation resource that is
110 // created. If an ImportEntities operation is cancelled, it is possible
111 // that a subset of the data has already been imported to Cloud Datastore.
112 rpc ImportEntities(ImportEntitiesRequest)
113 returns (google.longrunning.Operation) {
114 option (google.api.http) = {
115 post: "/v1/projects/{project_id}:import"
121 rpc GetIndex(GetIndexRequest) returns (Index) {
122 option (google.api.http) = {
123 get: "/v1/projects/{project_id}/indexes/{index_id}"
127 // Lists the indexes that match the specified filters. Datastore uses an
128 // eventually consistent query to fetch the list of indexes and may
129 // occasionally return stale results.
130 rpc ListIndexes(ListIndexesRequest) returns (ListIndexesResponse) {
131 option (google.api.http) = {
132 get: "/v1/projects/{project_id}/indexes"
137 // Metadata common to all Datastore Admin operations.
138 message CommonMetadata {
139 // The various possible states for an ongoing Operation.
142 STATE_UNSPECIFIED = 0;
144 // Request is being prepared for processing.
147 // Request is actively being processed.
150 // Request is in the process of being cancelled after user called
151 // google.longrunning.Operations.CancelOperation on the operation.
154 // Request has been processed and is in its finalization stage.
157 // Request has completed successfully.
160 // Request has finished being processed, but encountered an error.
163 // Request has finished being cancelled after user called
164 // google.longrunning.Operations.CancelOperation.
168 // The time that work began on the operation.
169 google.protobuf.Timestamp start_time = 1;
171 // The time the operation ended, either successfully or otherwise.
172 google.protobuf.Timestamp end_time = 2;
174 // The type of the operation. Can be used as a filter in
175 // ListOperationsRequest.
176 OperationType operation_type = 3;
178 // The client-assigned labels which were provided when the operation was
179 // created. May also include additional labels.
180 map<string, string> labels = 4;
182 // The current state of the Operation.
186 // Measures the progress of a particular metric.
188 // The amount of work that has been completed. Note that this may be greater
189 // than work_estimated.
190 int64 work_completed = 1;
192 // An estimate of how much work needs to be performed. May be zero if the
193 // work estimate is unavailable.
194 int64 work_estimated = 2;
198 // [google.datastore.admin.v1.DatastoreAdmin.ExportEntities][google.datastore.admin.v1.DatastoreAdmin.ExportEntities].
199 message ExportEntitiesRequest {
200 // Project ID against which to make the request.
201 string project_id = 1;
203 // Client-assigned labels.
204 map<string, string> labels = 2;
206 // Description of what data from the project is included in the export.
207 EntityFilter entity_filter = 3;
209 // Location for the export metadata and data files.
211 // The full resource URL of the external storage location. Currently, only
212 // Google Cloud Storage is supported. So output_url_prefix should be of the
213 // form: `gs://BUCKET_NAME[/NAMESPACE_PATH]`, where `BUCKET_NAME` is the
214 // name of the Cloud Storage bucket and `NAMESPACE_PATH` is an optional Cloud
215 // Storage namespace path (this is not a Cloud Datastore namespace). For more
216 // information about Cloud Storage namespace paths, see
218 // considerations](https://cloud.google.com/storage/docs/naming#object-considerations).
220 // The resulting files will be nested deeper than the specified URL prefix.
221 // The final output URL will be provided in the
222 // [google.datastore.admin.v1.ExportEntitiesResponse.output_url][google.datastore.admin.v1.ExportEntitiesResponse.output_url]
223 // field. That value should be used for subsequent ImportEntities operations.
225 // By nesting the data files deeper, the same Cloud Storage bucket can be used
226 // in multiple ExportEntities operations without conflict.
227 string output_url_prefix = 4;
231 // [google.datastore.admin.v1.DatastoreAdmin.ImportEntities][google.datastore.admin.v1.DatastoreAdmin.ImportEntities].
232 message ImportEntitiesRequest {
233 // Project ID against which to make the request.
234 string project_id = 1;
236 // Client-assigned labels.
237 map<string, string> labels = 2;
239 // The full resource URL of the external storage location. Currently, only
240 // Google Cloud Storage is supported. So input_url should be of the form:
241 // `gs://BUCKET_NAME[/NAMESPACE_PATH]/OVERALL_EXPORT_METADATA_FILE`, where
242 // `BUCKET_NAME` is the name of the Cloud Storage bucket, `NAMESPACE_PATH` is
243 // an optional Cloud Storage namespace path (this is not a Cloud Datastore
244 // namespace), and `OVERALL_EXPORT_METADATA_FILE` is the metadata file written
245 // by the ExportEntities operation. For more information about Cloud Storage
246 // namespace paths, see
248 // considerations](https://cloud.google.com/storage/docs/naming#object-considerations).
250 // For more information, see
251 // [google.datastore.admin.v1.ExportEntitiesResponse.output_url][google.datastore.admin.v1.ExportEntitiesResponse.output_url].
252 string input_url = 3;
254 // Optionally specify which kinds/namespaces are to be imported. If provided,
255 // the list must be a subset of the EntityFilter used in creating the export,
256 // otherwise a FAILED_PRECONDITION error will be returned. If no filter is
257 // specified then all entities from the export are imported.
258 EntityFilter entity_filter = 4;
262 // [google.datastore.admin.v1.DatastoreAdmin.ExportEntities][google.datastore.admin.v1.DatastoreAdmin.ExportEntities].
263 message ExportEntitiesResponse {
264 // Location of the output metadata file. This can be used to begin an import
265 // into Cloud Datastore (this project or another project). See
266 // [google.datastore.admin.v1.ImportEntitiesRequest.input_url][google.datastore.admin.v1.ImportEntitiesRequest.input_url].
267 // Only present if the operation completed successfully.
268 string output_url = 1;
271 // Metadata for ExportEntities operations.
272 message ExportEntitiesMetadata {
273 // Metadata common to all Datastore Admin operations.
274 CommonMetadata common = 1;
276 // An estimate of the number of entities processed.
277 Progress progress_entities = 2;
279 // An estimate of the number of bytes processed.
280 Progress progress_bytes = 3;
282 // Description of which entities are being exported.
283 EntityFilter entity_filter = 4;
285 // Location for the export metadata and data files. This will be the same
287 // [google.datastore.admin.v1.ExportEntitiesRequest.output_url_prefix][google.datastore.admin.v1.ExportEntitiesRequest.output_url_prefix]
288 // field. The final output location is provided in
289 // [google.datastore.admin.v1.ExportEntitiesResponse.output_url][google.datastore.admin.v1.ExportEntitiesResponse.output_url].
290 string output_url_prefix = 5;
293 // Metadata for ImportEntities operations.
294 message ImportEntitiesMetadata {
295 // Metadata common to all Datastore Admin operations.
296 CommonMetadata common = 1;
298 // An estimate of the number of entities processed.
299 Progress progress_entities = 2;
301 // An estimate of the number of bytes processed.
302 Progress progress_bytes = 3;
304 // Description of which entities are being imported.
305 EntityFilter entity_filter = 4;
307 // The location of the import metadata file. This will be the same value as
309 // [google.datastore.admin.v1.ExportEntitiesResponse.output_url][google.datastore.admin.v1.ExportEntitiesResponse.output_url]
311 string input_url = 5;
314 // Identifies a subset of entities in a project. This is specified as
315 // combinations of kinds and namespaces (either or both of which may be all, as
316 // described in the following examples).
320 // kinds=[], namespace_ids=[]
322 // Kinds Foo and Bar in all namespaces:
323 // kinds=['Foo', 'Bar'], namespace_ids=[]
325 // Kinds Foo and Bar only in the default namespace:
326 // kinds=['Foo', 'Bar'], namespace_ids=['']
328 // Kinds Foo and Bar in both the default and Baz namespaces:
329 // kinds=['Foo', 'Bar'], namespace_ids=['', 'Baz']
331 // The entire Baz namespace:
332 // kinds=[], namespace_ids=['Baz']
333 message EntityFilter {
334 // If empty, then this represents all kinds.
335 repeated string kinds = 1;
337 // An empty list represents all namespaces. This is the preferred
338 // usage for projects that don't use namespaces.
340 // An empty string element represents the default namespace. This should be
341 // used if the project has data in non-default namespaces, but doesn't want to
343 // Each namespace in this list must be unique.
344 repeated string namespace_ids = 2;
348 // [google.datastore.admin.v1.DatastoreAdmin.GetIndex][google.datastore.admin.v1.DatastoreAdmin.GetIndex].
349 message GetIndexRequest {
350 // Project ID against which to make the request.
351 string project_id = 1;
353 // The resource ID of the index to get.
358 // [google.datastore.admin.v1.DatastoreAdmin.ListIndexes][google.datastore.admin.v1.DatastoreAdmin.ListIndexes].
359 message ListIndexesRequest {
360 // Project ID against which to make the request.
361 string project_id = 1;
365 // The maximum number of items to return. If zero, then all results will be
369 // The next_page_token value returned from a previous List request, if any.
370 string page_token = 5;
374 // [google.datastore.admin.v1.DatastoreAdmin.ListIndexes][google.datastore.admin.v1.DatastoreAdmin.ListIndexes].
375 message ListIndexesResponse {
377 repeated Index indexes = 1;
379 // The standard List next-page token.
380 string next_page_token = 2;
383 // Metadata for Index operations.
384 message IndexOperationMetadata {
385 // Metadata common to all Datastore Admin operations.
386 CommonMetadata common = 1;
388 // An estimate of the number of entities processed.
389 Progress progress_entities = 2;
391 // The index resource ID that this operation is acting on.
398 OPERATION_TYPE_UNSPECIFIED = 0;