Google Cloud Spanner C++ Client  1.34.0
A C++ Client Library for Google Cloud Spanner
instance_admin_client.h
Go to the documentation of this file.
1 // Copyright 2021 Google LLC
2 //
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
6 //
7 // https://www.apache.org/licenses/LICENSE-2.0
8 //
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.
14 
15 // Generated by the Codegen C++ plugin.
16 // If you make any local changes, they will be lost.
17 // source: google/spanner/admin/instance/v1/spanner_instance_admin.proto
18 
19 #ifndef GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_SPANNER_ADMIN_INSTANCE_ADMIN_CLIENT_H
20 #define GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_SPANNER_ADMIN_INSTANCE_ADMIN_CLIENT_H
21 
22 #include "google/cloud/spanner/admin/instance_admin_connection.h"
23 #include "google/cloud/future.h"
24 #include "google/cloud/iam_updater.h"
25 #include "google/cloud/options.h"
26 #include "google/cloud/polling_policy.h"
27 #include "google/cloud/status_or.h"
28 #include "google/cloud/version.h"
29 #include <google/longrunning/operations.grpc.pb.h>
30 #include <map>
31 #include <memory>
32 
33 namespace google {
34 namespace cloud {
35 namespace spanner_admin {
37 
38 ///
39 /// Cloud Spanner Instance Admin API
40 ///
41 /// The Cloud Spanner Instance Admin API can be used to create, delete,
42 /// modify and list instances. Instances are dedicated Cloud Spanner serving
43 /// and storage resources to be used by Cloud Spanner databases.
44 ///
45 /// Each instance has a "configuration", which dictates where the
46 /// serving resources for the Cloud Spanner instance are located (e.g.,
47 /// US-central, Europe). Configurations are created by Google based on
48 /// resource availability.
49 ///
50 /// Cloud Spanner billing is based on the instances that exist and their
51 /// sizes. After an instance exists, there are no additional
52 /// per-database or per-operation charges for use of the instance
53 /// (though there may be additional network bandwidth charges).
54 /// Instances offer isolation: problems with databases in one instance
55 /// will not affect other instances. However, within an instance
56 /// databases can affect each other. For example, if one database in an
57 /// instance receives a lot of requests and consumes most of the
58 /// instance resources, fewer resources are available for other
59 /// databases in that instance, and their performance may suffer.
60 ///
61 /// @par Equality
62 ///
63 /// Instances of this class created via copy-construction or copy-assignment
64 /// always compare equal. Instances created with equal
65 /// `std::shared_ptr<*Connection>` objects compare equal. Objects that compare
66 /// equal share the same underlying resources.
67 ///
68 /// @par Performance
69 ///
70 /// Creating a new instance of this class is a relatively expensive operation,
71 /// new objects establish new connections to the service. In contrast,
72 /// copy-construction, move-construction, and the corresponding assignment
73 /// operations are relatively efficient as the copies share all underlying
74 /// resources.
75 ///
76 /// @par Thread Safety
77 ///
78 /// Concurrent access to different instances of this class, even if they compare
79 /// equal, is guaranteed to work. Two or more threads operating on the same
80 /// instance of this class is not guaranteed to work. Since copy-construction
81 /// and move-construction is a relatively efficient operation, consider using
82 /// such a copy when using this class from multiple threads.
83 ///
85  public:
87  std::shared_ptr<InstanceAdminConnection> connection);
89 
90  //@{
91  // @name Copy and move support
96  //@}
97 
98  //@{
99  // @name Equality
100  friend bool operator==(InstanceAdminClient const& a,
101  InstanceAdminClient const& b) {
102  return a.connection_ == b.connection_;
103  }
104  friend bool operator!=(InstanceAdminClient const& a,
105  InstanceAdminClient const& b) {
106  return !(a == b);
107  }
108  //@}
109 
110  ///
111  /// Lists the supported instance configurations for a given project.
112  ///
113  /// @param parent Required. The name of the project for which a list of
114  /// supported instance
115  /// configurations is requested. Values are of the form
116  /// `projects/<project>`.
117  /// @return
118  /// @googleapis_link{google::spanner::admin::instance::v1::InstanceConfig,google/spanner/admin/instance/v1/spanner_instance_admin.proto#L304}
119  ///
120  /// [google.spanner.admin.instance.v1.ListInstanceConfigsRequest]:
121  /// @googleapis_reference_link{google/spanner/admin/instance/v1/spanner_instance_admin.proto#L415}
122  /// [google.spanner.admin.instance.v1.InstanceConfig]:
123  /// @googleapis_reference_link{google/spanner/admin/instance/v1/spanner_instance_admin.proto#L304}
124  ///
125  StreamRange<google::spanner::admin::instance::v1::InstanceConfig>
126  ListInstanceConfigs(std::string const& parent);
127 
128  ///
129  /// Gets information about a particular instance configuration.
130  ///
131  /// @param name Required. The name of the requested instance configuration.
132  /// Values are of
133  /// the form `projects/<project>/instanceConfigs/<config>`.
134  /// @return
135  /// @googleapis_link{google::spanner::admin::instance::v1::InstanceConfig,google/spanner/admin/instance/v1/spanner_instance_admin.proto#L304}
136  ///
137  /// [google.spanner.admin.instance.v1.GetInstanceConfigRequest]:
138  /// @googleapis_reference_link{google/spanner/admin/instance/v1/spanner_instance_admin.proto#L449}
139  /// [google.spanner.admin.instance.v1.InstanceConfig]:
140  /// @googleapis_reference_link{google/spanner/admin/instance/v1/spanner_instance_admin.proto#L304}
141  ///
142  StatusOr<google::spanner::admin::instance::v1::InstanceConfig>
143  GetInstanceConfig(std::string const& name);
144 
145  ///
146  /// Lists all instances in the given project.
147  ///
148  /// @param parent Required. The name of the project for which a list of
149  /// instances is
150  /// requested. Values are of the form `projects/<project>`.
151  /// @return
152  /// @googleapis_link{google::spanner::admin::instance::v1::Instance,google/spanner/admin/instance/v1/spanner_instance_admin.proto#L328}
153  ///
154  /// [google.spanner.admin.instance.v1.ListInstancesRequest]:
155  /// @googleapis_reference_link{google/spanner/admin/instance/v1/spanner_instance_admin.proto#L499}
156  /// [google.spanner.admin.instance.v1.Instance]:
157  /// @googleapis_reference_link{google/spanner/admin/instance/v1/spanner_instance_admin.proto#L328}
158  ///
159  StreamRange<google::spanner::admin::instance::v1::Instance> ListInstances(
160  std::string const& parent);
161 
162  ///
163  /// Gets information about a particular instance.
164  ///
165  /// @param name Required. The name of the requested instance. Values are of
166  /// the form
167  /// `projects/<project>/instances/<instance>`.
168  /// @return
169  /// @googleapis_link{google::spanner::admin::instance::v1::Instance,google/spanner/admin/instance/v1/spanner_instance_admin.proto#L328}
170  ///
171  /// [google.spanner.admin.instance.v1.GetInstanceRequest]:
172  /// @googleapis_reference_link{google/spanner/admin/instance/v1/spanner_instance_admin.proto#L461}
173  /// [google.spanner.admin.instance.v1.Instance]:
174  /// @googleapis_reference_link{google/spanner/admin/instance/v1/spanner_instance_admin.proto#L328}
175  ///
176  StatusOr<google::spanner::admin::instance::v1::Instance> GetInstance(
177  std::string const& name);
178 
179  ///
180  /// Creates an instance and begins preparing it to begin serving. The
181  /// returned [long-running operation][google.longrunning.Operation]
182  /// can be used to track the progress of preparing the new
183  /// instance. The instance name is assigned by the caller. If the
184  /// named instance already exists, `CreateInstance` returns
185  /// `ALREADY_EXISTS`.
186  ///
187  /// Immediately upon completion of this request:
188  ///
189  /// * The instance is readable via the API, with all requested attributes
190  /// but no allocated resources. Its state is `CREATING`.
191  ///
192  /// Until completion of the returned operation:
193  ///
194  /// * Cancelling the operation renders the instance immediately unreadable
195  /// via the API.
196  /// * The instance can be deleted.
197  /// * All other attempts to modify the instance are rejected.
198  ///
199  /// Upon completion of the returned operation:
200  ///
201  /// * Billing for all successfully-allocated resources begins (some types
202  /// may have lower than the requested levels).
203  /// * Databases can be created in the instance.
204  /// * The instance's allocated resource levels are readable via the API.
205  /// * The instance's state becomes `READY`.
206  ///
207  /// The returned [long-running operation][google.longrunning.Operation] will
208  /// have a name of the format `<instance_name>/operations/<operation_id>` and
209  /// can be used to track creation of the instance. The
210  /// [metadata][google.longrunning.Operation.metadata] field type is
211  /// [CreateInstanceMetadata][google.spanner.admin.instance.v1.CreateInstanceMetadata].
212  /// The [response][google.longrunning.Operation.response] field type is
213  /// [Instance][google.spanner.admin.instance.v1.Instance], if successful.
214  ///
215  /// @param parent Required. The name of the project in which to create the
216  /// instance. Values
217  /// are of the form `projects/<project>`.
218  /// @param instance_id Required. The ID of the instance to create. Valid
219  /// identifiers are of the
220  /// form `[a-z][-a-z0-9]*[a-z0-9]` and must be between 2 and 64 characters in
221  /// length.
222  /// @param instance Required. The instance to create. The name may be
223  /// omitted, but if
224  /// specified must be `<parent>/instances/<instance_id>`.
225  /// @return
226  /// @googleapis_link{google::spanner::admin::instance::v1::Instance,google/spanner/admin/instance/v1/spanner_instance_admin.proto#L328}
227  ///
228  /// [google.spanner.admin.instance.v1.CreateInstanceRequest]:
229  /// @googleapis_reference_link{google/spanner/admin/instance/v1/spanner_instance_admin.proto#L478}
230  /// [google.spanner.admin.instance.v1.Instance]:
231  /// @googleapis_reference_link{google/spanner/admin/instance/v1/spanner_instance_admin.proto#L328}
232  ///
233  future<StatusOr<google::spanner::admin::instance::v1::Instance>>
235  std::string const& parent, std::string const& instance_id,
236  google::spanner::admin::instance::v1::Instance const& instance);
237 
238  ///
239  /// Updates an instance, and begins allocating or releasing resources
240  /// as requested. The returned [long-running
241  /// operation][google.longrunning.Operation] can be used to track the
242  /// progress of updating the instance. If the named instance does not
243  /// exist, returns `NOT_FOUND`.
244  ///
245  /// Immediately upon completion of this request:
246  ///
247  /// * For resource types for which a decrease in the instance's allocation
248  /// has been requested, billing is based on the newly-requested level.
249  ///
250  /// Until completion of the returned operation:
251  ///
252  /// * Cancelling the operation sets its metadata's
253  /// [cancel_time][google.spanner.admin.instance.v1.UpdateInstanceMetadata.cancel_time],
254  /// and begins restoring resources to their pre-request values. The
255  /// operation is guaranteed to succeed at undoing all resource changes,
256  /// after which point it terminates with a `CANCELLED` status.
257  /// * All other attempts to modify the instance are rejected.
258  /// * Reading the instance via the API continues to give the pre-request
259  /// resource levels.
260  ///
261  /// Upon completion of the returned operation:
262  ///
263  /// * Billing begins for all successfully-allocated resources (some types
264  /// may have lower than the requested levels).
265  /// * All newly-reserved resources are available for serving the instance's
266  /// tables.
267  /// * The instance's new resource levels are readable via the API.
268  ///
269  /// The returned [long-running operation][google.longrunning.Operation] will
270  /// have a name of the format `<instance_name>/operations/<operation_id>` and
271  /// can be used to track the instance modification. The
272  /// [metadata][google.longrunning.Operation.metadata] field type is
273  /// [UpdateInstanceMetadata][google.spanner.admin.instance.v1.UpdateInstanceMetadata].
274  /// The [response][google.longrunning.Operation.response] field type is
275  /// [Instance][google.spanner.admin.instance.v1.Instance], if successful.
276  ///
277  /// Authorization requires `spanner.instances.update` permission on
278  /// resource [name][google.spanner.admin.instance.v1.Instance.name].
279  ///
280  /// @param instance Required. The instance to update, which must always
281  /// include the instance
282  /// name. Otherwise, only fields mentioned in
283  /// [field_mask][google.spanner.admin.instance.v1.UpdateInstanceRequest.field_mask]
284  /// need be included.
285  /// @param field_mask Required. A mask specifying which fields in
286  /// [Instance][google.spanner.admin.instance.v1.Instance] should be updated.
287  /// The field mask must always be specified; this prevents any future fields
288  /// in [Instance][google.spanner.admin.instance.v1.Instance] from being
289  /// erased accidentally by clients that do not know about them.
290  /// @return
291  /// @googleapis_link{google::spanner::admin::instance::v1::Instance,google/spanner/admin/instance/v1/spanner_instance_admin.proto#L328}
292  ///
293  /// [google.spanner.admin.instance.v1.UpdateInstanceRequest]:
294  /// @googleapis_reference_link{google/spanner/admin/instance/v1/spanner_instance_admin.proto#L552}
295  /// [google.spanner.admin.instance.v1.Instance]:
296  /// @googleapis_reference_link{google/spanner/admin/instance/v1/spanner_instance_admin.proto#L328}
297  ///
298  future<StatusOr<google::spanner::admin::instance::v1::Instance>>
299  UpdateInstance(google::spanner::admin::instance::v1::Instance const& instance,
300  google::protobuf::FieldMask const& field_mask);
301 
302  ///
303  /// Deletes an instance.
304  ///
305  /// Immediately upon completion of the request:
306  ///
307  /// * Billing ceases for all of the instance's reserved resources.
308  ///
309  /// Soon afterward:
310  ///
311  /// * The instance and *all of its databases* immediately and
312  /// irrevocably disappear from the API. All data in the databases
313  /// is permanently deleted.
314  ///
315  /// @param name Required. The name of the instance to be deleted. Values are
316  /// of the form
317  /// `projects/<project>/instances/<instance>`
318  ///
319  /// [google.spanner.admin.instance.v1.DeleteInstanceRequest]:
320  /// @googleapis_reference_link{google/spanner/admin/instance/v1/spanner_instance_admin.proto#L565}
321  ///
322  Status DeleteInstance(std::string const& name);
323 
324  ///
325  /// Sets the access control policy on an instance resource. Replaces any
326  /// existing policy.
327  ///
328  /// Authorization requires `spanner.instances.setIamPolicy` on
329  /// [resource][google.iam.v1.SetIamPolicyRequest.resource].
330  ///
331  /// @param resource REQUIRED: The resource for which the policy is being
332  /// specified.
333  /// See the operation documentation for the appropriate value for this field.
334  /// @param policy REQUIRED: The complete policy to be applied to the
335  /// `resource`. The size of
336  /// the policy is limited to a few 10s of KB. An empty policy is a
337  /// valid policy but certain Cloud Platform services (such as Projects)
338  /// might reject them.
339  /// @return
340  /// @googleapis_link{google::iam::v1::Policy,google/iam/v1/policy.proto#L88}
341  ///
342  /// [google.iam.v1.SetIamPolicyRequest]:
343  /// @googleapis_reference_link{google/iam/v1/iam_policy.proto#L98}
344  /// [google.iam.v1.Policy]:
345  /// @googleapis_reference_link{google/iam/v1/policy.proto#L88}
346  ///
347  StatusOr<google::iam::v1::Policy> SetIamPolicy(
348  std::string const& resource, google::iam::v1::Policy const& policy);
349 
350  /**
351  * Updates the IAM policy for @p resource using an optimistic concurrency
352  * control loop.
353  *
354  * The loop fetches the current policy for @p resource, and passes it to @p
355  * updater, which should return the new policy. This new policy should use the
356  * current etag so that the read-modify-write cycle can detect races and rerun
357  * the update when there is a mismatch. If the new policy does not have an
358  * etag, the existing policy will be blindly overwritten. If @p updater does
359  * not yield a policy, the control loop is terminated and kCancelled is
360  * returned.
361  *
362  * @param resource Required. The resource for which the policy is being
363  * specified. See the operation documentation for the appropriate value for
364  * this field.
365  * @param updater Required. Functor to map the current policy to a new one.
366  * @param options Optional. Options to control the loop. Expected options
367  * are:
368  * - `InstanceAdminBackoffPolicyOption`
369  * @return google::iam::v1::Policy
370  */
371  StatusOr<google::iam::v1::Policy> SetIamPolicy(std::string const& resource,
372  IamUpdater const& updater,
373  Options options = {});
374 
375  ///
376  /// Gets the access control policy for an instance resource. Returns an empty
377  /// policy if an instance exists but does not have a policy set.
378  ///
379  /// Authorization requires `spanner.instances.getIamPolicy` on
380  /// [resource][google.iam.v1.GetIamPolicyRequest.resource].
381  ///
382  /// @param resource REQUIRED: The resource for which the policy is being
383  /// requested.
384  /// See the operation documentation for the appropriate value for this field.
385  /// @return
386  /// @googleapis_link{google::iam::v1::Policy,google/iam/v1/policy.proto#L88}
387  ///
388  /// [google.iam.v1.GetIamPolicyRequest]:
389  /// @googleapis_reference_link{google/iam/v1/iam_policy.proto#L113}
390  /// [google.iam.v1.Policy]:
391  /// @googleapis_reference_link{google/iam/v1/policy.proto#L88}
392  ///
393  StatusOr<google::iam::v1::Policy> GetIamPolicy(std::string const& resource);
394 
395  ///
396  /// Returns permissions that the caller has on the specified instance
397  /// resource.
398  ///
399  /// Attempting this RPC on a non-existent Cloud Spanner instance resource will
400  /// result in a NOT_FOUND error if the user has `spanner.instances.list`
401  /// permission on the containing Google Cloud Project. Otherwise returns an
402  /// empty set of permissions.
403  ///
404  /// @param resource REQUIRED: The resource for which the policy detail is
405  /// being requested.
406  /// See the operation documentation for the appropriate value for this field.
407  /// @param permissions The set of permissions to check for the `resource`.
408  /// Permissions with
409  /// wildcards (such as '*' or 'storage.*') are not allowed. For more
410  /// information see
411  /// [IAM Overview](https://cloud.google.com/iam/docs/overview#permissions).
412  /// @return
413  /// @googleapis_link{google::iam::v1::TestIamPermissionsResponse,google/iam/v1/iam_policy.proto#L141}
414  ///
415  /// [google.iam.v1.TestIamPermissionsRequest]:
416  /// @googleapis_reference_link{google/iam/v1/iam_policy.proto#L126}
417  /// [google.iam.v1.TestIamPermissionsResponse]:
418  /// @googleapis_reference_link{google/iam/v1/iam_policy.proto#L141}
419  ///
420  StatusOr<google::iam::v1::TestIamPermissionsResponse> TestIamPermissions(
421  std::string const& resource, std::vector<std::string> const& permissions);
422 
423  ///
424  /// Lists the supported instance configurations for a given project.
425  ///
426  /// @param request
427  /// @googleapis_link{google::spanner::admin::instance::v1::ListInstanceConfigsRequest,google/spanner/admin/instance/v1/spanner_instance_admin.proto#L415}
428  /// @return
429  /// @googleapis_link{google::spanner::admin::instance::v1::InstanceConfig,google/spanner/admin/instance/v1/spanner_instance_admin.proto#L304}
430  ///
431  /// [google.spanner.admin.instance.v1.ListInstanceConfigsRequest]:
432  /// @googleapis_reference_link{google/spanner/admin/instance/v1/spanner_instance_admin.proto#L415}
433  /// [google.spanner.admin.instance.v1.InstanceConfig]:
434  /// @googleapis_reference_link{google/spanner/admin/instance/v1/spanner_instance_admin.proto#L304}
435  ///
436  StreamRange<google::spanner::admin::instance::v1::InstanceConfig>
438  google::spanner::admin::instance::v1::ListInstanceConfigsRequest request);
439 
440  ///
441  /// Gets information about a particular instance configuration.
442  ///
443  /// @param request
444  /// @googleapis_link{google::spanner::admin::instance::v1::GetInstanceConfigRequest,google/spanner/admin/instance/v1/spanner_instance_admin.proto#L449}
445  /// @return
446  /// @googleapis_link{google::spanner::admin::instance::v1::InstanceConfig,google/spanner/admin/instance/v1/spanner_instance_admin.proto#L304}
447  ///
448  /// [google.spanner.admin.instance.v1.GetInstanceConfigRequest]:
449  /// @googleapis_reference_link{google/spanner/admin/instance/v1/spanner_instance_admin.proto#L449}
450  /// [google.spanner.admin.instance.v1.InstanceConfig]:
451  /// @googleapis_reference_link{google/spanner/admin/instance/v1/spanner_instance_admin.proto#L304}
452  ///
453  StatusOr<google::spanner::admin::instance::v1::InstanceConfig>
455  google::spanner::admin::instance::v1::GetInstanceConfigRequest const&
456  request);
457 
458  ///
459  /// Lists all instances in the given project.
460  ///
461  /// @param request
462  /// @googleapis_link{google::spanner::admin::instance::v1::ListInstancesRequest,google/spanner/admin/instance/v1/spanner_instance_admin.proto#L499}
463  /// @return
464  /// @googleapis_link{google::spanner::admin::instance::v1::Instance,google/spanner/admin/instance/v1/spanner_instance_admin.proto#L328}
465  ///
466  /// [google.spanner.admin.instance.v1.ListInstancesRequest]:
467  /// @googleapis_reference_link{google/spanner/admin/instance/v1/spanner_instance_admin.proto#L499}
468  /// [google.spanner.admin.instance.v1.Instance]:
469  /// @googleapis_reference_link{google/spanner/admin/instance/v1/spanner_instance_admin.proto#L328}
470  ///
471  StreamRange<google::spanner::admin::instance::v1::Instance> ListInstances(
472  google::spanner::admin::instance::v1::ListInstancesRequest request);
473 
474  ///
475  /// Gets information about a particular instance.
476  ///
477  /// @param request
478  /// @googleapis_link{google::spanner::admin::instance::v1::GetInstanceRequest,google/spanner/admin/instance/v1/spanner_instance_admin.proto#L461}
479  /// @return
480  /// @googleapis_link{google::spanner::admin::instance::v1::Instance,google/spanner/admin/instance/v1/spanner_instance_admin.proto#L328}
481  ///
482  /// [google.spanner.admin.instance.v1.GetInstanceRequest]:
483  /// @googleapis_reference_link{google/spanner/admin/instance/v1/spanner_instance_admin.proto#L461}
484  /// [google.spanner.admin.instance.v1.Instance]:
485  /// @googleapis_reference_link{google/spanner/admin/instance/v1/spanner_instance_admin.proto#L328}
486  ///
487  StatusOr<google::spanner::admin::instance::v1::Instance> GetInstance(
488  google::spanner::admin::instance::v1::GetInstanceRequest const& request);
489 
490  ///
491  /// Creates an instance and begins preparing it to begin serving. The
492  /// returned [long-running operation][google.longrunning.Operation]
493  /// can be used to track the progress of preparing the new
494  /// instance. The instance name is assigned by the caller. If the
495  /// named instance already exists, `CreateInstance` returns
496  /// `ALREADY_EXISTS`.
497  ///
498  /// Immediately upon completion of this request:
499  ///
500  /// * The instance is readable via the API, with all requested attributes
501  /// but no allocated resources. Its state is `CREATING`.
502  ///
503  /// Until completion of the returned operation:
504  ///
505  /// * Cancelling the operation renders the instance immediately unreadable
506  /// via the API.
507  /// * The instance can be deleted.
508  /// * All other attempts to modify the instance are rejected.
509  ///
510  /// Upon completion of the returned operation:
511  ///
512  /// * Billing for all successfully-allocated resources begins (some types
513  /// may have lower than the requested levels).
514  /// * Databases can be created in the instance.
515  /// * The instance's allocated resource levels are readable via the API.
516  /// * The instance's state becomes `READY`.
517  ///
518  /// The returned [long-running operation][google.longrunning.Operation] will
519  /// have a name of the format `<instance_name>/operations/<operation_id>` and
520  /// can be used to track creation of the instance. The
521  /// [metadata][google.longrunning.Operation.metadata] field type is
522  /// [CreateInstanceMetadata][google.spanner.admin.instance.v1.CreateInstanceMetadata].
523  /// The [response][google.longrunning.Operation.response] field type is
524  /// [Instance][google.spanner.admin.instance.v1.Instance], if successful.
525  ///
526  /// @param request
527  /// @googleapis_link{google::spanner::admin::instance::v1::CreateInstanceRequest,google/spanner/admin/instance/v1/spanner_instance_admin.proto#L478}
528  /// @return
529  /// @googleapis_link{google::spanner::admin::instance::v1::Instance,google/spanner/admin/instance/v1/spanner_instance_admin.proto#L328}
530  ///
531  /// [google.spanner.admin.instance.v1.CreateInstanceRequest]:
532  /// @googleapis_reference_link{google/spanner/admin/instance/v1/spanner_instance_admin.proto#L478}
533  /// [google.spanner.admin.instance.v1.Instance]:
534  /// @googleapis_reference_link{google/spanner/admin/instance/v1/spanner_instance_admin.proto#L328}
535  ///
536  future<StatusOr<google::spanner::admin::instance::v1::Instance>>
538  google::spanner::admin::instance::v1::CreateInstanceRequest const&
539  request);
540 
541  ///
542  /// Updates an instance, and begins allocating or releasing resources
543  /// as requested. The returned [long-running
544  /// operation][google.longrunning.Operation] can be used to track the
545  /// progress of updating the instance. If the named instance does not
546  /// exist, returns `NOT_FOUND`.
547  ///
548  /// Immediately upon completion of this request:
549  ///
550  /// * For resource types for which a decrease in the instance's allocation
551  /// has been requested, billing is based on the newly-requested level.
552  ///
553  /// Until completion of the returned operation:
554  ///
555  /// * Cancelling the operation sets its metadata's
556  /// [cancel_time][google.spanner.admin.instance.v1.UpdateInstanceMetadata.cancel_time],
557  /// and begins restoring resources to their pre-request values. The
558  /// operation is guaranteed to succeed at undoing all resource changes,
559  /// after which point it terminates with a `CANCELLED` status.
560  /// * All other attempts to modify the instance are rejected.
561  /// * Reading the instance via the API continues to give the pre-request
562  /// resource levels.
563  ///
564  /// Upon completion of the returned operation:
565  ///
566  /// * Billing begins for all successfully-allocated resources (some types
567  /// may have lower than the requested levels).
568  /// * All newly-reserved resources are available for serving the instance's
569  /// tables.
570  /// * The instance's new resource levels are readable via the API.
571  ///
572  /// The returned [long-running operation][google.longrunning.Operation] will
573  /// have a name of the format `<instance_name>/operations/<operation_id>` and
574  /// can be used to track the instance modification. The
575  /// [metadata][google.longrunning.Operation.metadata] field type is
576  /// [UpdateInstanceMetadata][google.spanner.admin.instance.v1.UpdateInstanceMetadata].
577  /// The [response][google.longrunning.Operation.response] field type is
578  /// [Instance][google.spanner.admin.instance.v1.Instance], if successful.
579  ///
580  /// Authorization requires `spanner.instances.update` permission on
581  /// resource [name][google.spanner.admin.instance.v1.Instance.name].
582  ///
583  /// @param request
584  /// @googleapis_link{google::spanner::admin::instance::v1::UpdateInstanceRequest,google/spanner/admin/instance/v1/spanner_instance_admin.proto#L552}
585  /// @return
586  /// @googleapis_link{google::spanner::admin::instance::v1::Instance,google/spanner/admin/instance/v1/spanner_instance_admin.proto#L328}
587  ///
588  /// [google.spanner.admin.instance.v1.UpdateInstanceRequest]:
589  /// @googleapis_reference_link{google/spanner/admin/instance/v1/spanner_instance_admin.proto#L552}
590  /// [google.spanner.admin.instance.v1.Instance]:
591  /// @googleapis_reference_link{google/spanner/admin/instance/v1/spanner_instance_admin.proto#L328}
592  ///
593  future<StatusOr<google::spanner::admin::instance::v1::Instance>>
595  google::spanner::admin::instance::v1::UpdateInstanceRequest const&
596  request);
597 
598  ///
599  /// Deletes an instance.
600  ///
601  /// Immediately upon completion of the request:
602  ///
603  /// * Billing ceases for all of the instance's reserved resources.
604  ///
605  /// Soon afterward:
606  ///
607  /// * The instance and *all of its databases* immediately and
608  /// irrevocably disappear from the API. All data in the databases
609  /// is permanently deleted.
610  ///
611  /// @param request
612  /// @googleapis_link{google::spanner::admin::instance::v1::DeleteInstanceRequest,google/spanner/admin/instance/v1/spanner_instance_admin.proto#L565}
613  ///
614  /// [google.spanner.admin.instance.v1.DeleteInstanceRequest]:
615  /// @googleapis_reference_link{google/spanner/admin/instance/v1/spanner_instance_admin.proto#L565}
616  ///
618  google::spanner::admin::instance::v1::DeleteInstanceRequest const&
619  request);
620 
621  ///
622  /// Sets the access control policy on an instance resource. Replaces any
623  /// existing policy.
624  ///
625  /// Authorization requires `spanner.instances.setIamPolicy` on
626  /// [resource][google.iam.v1.SetIamPolicyRequest.resource].
627  ///
628  /// @param request
629  /// @googleapis_link{google::iam::v1::SetIamPolicyRequest,google/iam/v1/iam_policy.proto#L98}
630  /// @return
631  /// @googleapis_link{google::iam::v1::Policy,google/iam/v1/policy.proto#L88}
632  ///
633  /// [google.iam.v1.SetIamPolicyRequest]:
634  /// @googleapis_reference_link{google/iam/v1/iam_policy.proto#L98}
635  /// [google.iam.v1.Policy]:
636  /// @googleapis_reference_link{google/iam/v1/policy.proto#L88}
637  ///
638  StatusOr<google::iam::v1::Policy> SetIamPolicy(
639  google::iam::v1::SetIamPolicyRequest const& request);
640 
641  ///
642  /// Gets the access control policy for an instance resource. Returns an empty
643  /// policy if an instance exists but does not have a policy set.
644  ///
645  /// Authorization requires `spanner.instances.getIamPolicy` on
646  /// [resource][google.iam.v1.GetIamPolicyRequest.resource].
647  ///
648  /// @param request
649  /// @googleapis_link{google::iam::v1::GetIamPolicyRequest,google/iam/v1/iam_policy.proto#L113}
650  /// @return
651  /// @googleapis_link{google::iam::v1::Policy,google/iam/v1/policy.proto#L88}
652  ///
653  /// [google.iam.v1.GetIamPolicyRequest]:
654  /// @googleapis_reference_link{google/iam/v1/iam_policy.proto#L113}
655  /// [google.iam.v1.Policy]:
656  /// @googleapis_reference_link{google/iam/v1/policy.proto#L88}
657  ///
658  StatusOr<google::iam::v1::Policy> GetIamPolicy(
659  google::iam::v1::GetIamPolicyRequest const& request);
660 
661  ///
662  /// Returns permissions that the caller has on the specified instance
663  /// resource.
664  ///
665  /// Attempting this RPC on a non-existent Cloud Spanner instance resource will
666  /// result in a NOT_FOUND error if the user has `spanner.instances.list`
667  /// permission on the containing Google Cloud Project. Otherwise returns an
668  /// empty set of permissions.
669  ///
670  /// @param request
671  /// @googleapis_link{google::iam::v1::TestIamPermissionsRequest,google/iam/v1/iam_policy.proto#L126}
672  /// @return
673  /// @googleapis_link{google::iam::v1::TestIamPermissionsResponse,google/iam/v1/iam_policy.proto#L141}
674  ///
675  /// [google.iam.v1.TestIamPermissionsRequest]:
676  /// @googleapis_reference_link{google/iam/v1/iam_policy.proto#L126}
677  /// [google.iam.v1.TestIamPermissionsResponse]:
678  /// @googleapis_reference_link{google/iam/v1/iam_policy.proto#L141}
679  ///
680  StatusOr<google::iam::v1::TestIamPermissionsResponse> TestIamPermissions(
681  google::iam::v1::TestIamPermissionsRequest const& request);
682 
683  private:
684  std::shared_ptr<InstanceAdminConnection> connection_;
685 };
686 
688 namespace gcpcxxV1 = GOOGLE_CLOUD_CPP_NS; // NOLINT(misc-unused-alias-decls)
689 } // namespace spanner_admin
690 } // namespace cloud
691 } // namespace google
692 
693 #endif // GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_SPANNER_ADMIN_INSTANCE_ADMIN_CLIENT_H