Google Cloud Storage C++ Client  1.32.1
A C++ Client Library for Google Cloud Storage
well_known_parameters.h
Go to the documentation of this file.
1 // Copyright 2018 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 // http://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 #ifndef GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_STORAGE_WELL_KNOWN_PARAMETERS_H
16 #define GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_STORAGE_WELL_KNOWN_PARAMETERS_H
17 
18 #include "google/cloud/storage/version.h"
19 #include "google/cloud/internal/ios_flags_saver.h"
20 #include "google/cloud/optional.h"
21 #include "absl/types/optional.h"
22 #include <cstdint>
23 #include <iomanip>
24 #include <string>
25 
26 namespace google {
27 namespace cloud {
28 namespace storage {
29 inline namespace STORAGE_CLIENT_NS {
30 namespace internal {
31 /**
32  * Defines well-known request headers using the CRTP.
33  *
34  * @tparam P the type we will use to represent the query parameter.
35  * @tparam T the C++ type of the query parameter
36  */
37 template <typename P, typename T>
38 class WellKnownParameter {
39  public:
40  WellKnownParameter() = default;
41  explicit WellKnownParameter(T&& value) : value_(std::forward<T>(value)) {}
42  explicit WellKnownParameter(T const& value) : value_(value) {}
43 
44  char const* parameter_name() const { return P::well_known_parameter_name(); }
45  bool has_value() const { return value_.has_value(); }
46  T const& value() const { return value_.value(); }
47  template <typename U>
48  T value_or(U&& default_val) {
49  return value_.value_or(std::forward<U>(default_val));
50  }
51 
52  private:
53  absl::optional<T> value_;
54 };
55 
56 template <typename P, typename T>
57 std::ostream& operator<<(std::ostream& os,
58  WellKnownParameter<P, T> const& rhs) {
59  if (rhs.has_value()) {
60  return os << rhs.parameter_name() << "=" << rhs.value();
61  }
62  return os << rhs.parameter_name() << "=<not set>";
63 }
64 
65 template <typename P>
66 std::ostream& operator<<(std::ostream& os,
67  WellKnownParameter<P, bool> const& rhs) {
68  if (rhs.has_value()) {
69  google::cloud::internal::IosFlagsSaver saver(os);
70  return os << rhs.parameter_name() << "=" << std::boolalpha << rhs.value();
71  }
72  return os << rhs.parameter_name() << "=<not set>";
73 }
74 } // namespace internal
75 
76 /**
77  * Sets the contentEncoding option for object uploads.
78  *
79  * The contentEncoding option allows applications to describe how is the data
80  * encoded (binary or ASCII) in upload requests.
81  */
83  : public internal::WellKnownParameter<ContentEncoding, std::string> {
84  using WellKnownParameter<ContentEncoding, std::string>::WellKnownParameter;
85  static char const* well_known_parameter_name() { return "contentEncoding"; }
86 };
87 
88 /**
89  * Included deleted HMAC keys in list requests.
90  */
91 struct Deleted : public internal::WellKnownParameter<Deleted, bool> {
92  using WellKnownParameter<Deleted, bool>::WellKnownParameter;
93  static char const* well_known_parameter_name() { return "deleted"; }
94 };
95 
96 /**
97  * Configure the Customer-Managed Encryption Key (CMEK) for an rewrite.
98  *
99  * With CMEK you can use keys generated by Google Cloud's Key Management Service
100  * to encrypt the data in your objects. Use this option to configure the CMEK of
101  * an object created as part of a rewrite operation. Key names can be found
102  * from the Google Cloud console, and are in the
103  * `projects/{PROJECT_ID}/locations/{LOCATION_ID}/keyRings/{KEY_RING_ID}/cryptoKeys/{CRYPTO_KEY_ID}`
104  * format.
105  *
106  * @see https://cloud.google.com/storage/docs/encryption/customer-managed-keys
107  * for a general introduction to CMEK in GCS.
108  */
110  : public internal::WellKnownParameter<DestinationKmsKeyName, std::string> {
111  using WellKnownParameter<DestinationKmsKeyName,
112  std::string>::WellKnownParameter;
113  static char const* well_known_parameter_name() {
114  return "destinationKmsKeyName";
115  }
116 };
117 
118 /**
119  * Defines the `fields` query parameter.
120  *
121  * The `fields` parameter can be used to limit the fields returned by a request,
122  * saving bandwidth and possibly improving performance for applications that do
123  * not need a full response from the server.
124  *
125  * @see
126  * https://cloud.google.com/storage/docs/json_api/v1/how-tos/performance#partial-response
127  * for general documentation on how to use this parameter.
128  */
129 struct Fields : public internal::WellKnownParameter<Fields, std::string> {
130  using WellKnownParameter<Fields, std::string>::WellKnownParameter;
131  static char const* well_known_parameter_name() { return "fields"; }
132 };
133 
134 /**
135  * Set the version of an object to operate on.
136  *
137  * For objects in Buckets with `versioning` enabled, the application sometimes
138  * needs to specify which version of the object should the request target. This
139  * is an optional query parameter to control the version.
140  *
141  * @see https://cloud.google.com/storage/docs/object-versioning for more
142  * information on GCS Object versioning.
143  */
145  : public internal::WellKnownParameter<Generation, std::int64_t> {
146  using WellKnownParameter<Generation, std::int64_t>::WellKnownParameter;
147  static char const* well_known_parameter_name() { return "generation"; }
148 };
149 
150 /**
151  * A pre-condition: the request succeeds only if the object generation matches.
152  *
153  * @note Setting this to 0 makes the pre-condition succeed only if there are no
154  * live versions of the object.
155  */
157  : public internal::WellKnownParameter<IfGenerationMatch, std::int64_t> {
158  using WellKnownParameter<IfGenerationMatch, std::int64_t>::WellKnownParameter;
159  static char const* well_known_parameter_name() { return "ifGenerationMatch"; }
160 };
161 
162 /**
163  * A pre-condition: the request succeeds unless the object generation matches.
164  *
165  * @note When set to 0 the pre-condition succeeds only if there are live
166  * versions of the object.
167  */
169  : public internal::WellKnownParameter<IfGenerationNotMatch, std::int64_t> {
170  using WellKnownParameter<IfGenerationNotMatch,
171  std::int64_t>::WellKnownParameter;
172  static char const* well_known_parameter_name() {
173  return "ifGenerationNotMatch";
174  }
175 };
176 
177 /**
178  * A pre-condition: the request succeeds if the metadata generation matches.
179  */
181  : public internal::WellKnownParameter<IfMetagenerationMatch, std::int64_t> {
182  using WellKnownParameter<IfMetagenerationMatch,
183  std::int64_t>::WellKnownParameter;
184  static char const* well_known_parameter_name() {
185  return "ifMetagenerationMatch";
186  }
187 };
188 
189 /**
190  * A pre-condition: the request succeeds unless the metadata generation matches.
191  */
193  : public internal::WellKnownParameter<IfMetagenerationNotMatch,
194  std::int64_t> {
195  using WellKnownParameter<IfMetagenerationNotMatch,
196  std::int64_t>::WellKnownParameter;
197  static char const* well_known_parameter_name() {
198  return "ifMetagenerationNotMatch";
199  }
200 };
201 
202 /**
203  * A pre-condition: the request succeeds if the source object generation
204  * matches.
205  *
206  * This is only used in CopyObject and RewriteObject operations.
207  */
209  : public internal::WellKnownParameter<IfSourceGenerationMatch,
210  std::int64_t> {
211  using WellKnownParameter<IfSourceGenerationMatch,
212  std::int64_t>::WellKnownParameter;
213  static char const* well_known_parameter_name() {
214  return "ifSourceGenerationMatch";
215  }
216 };
217 
218 /**
219  * A pre-condition: the request succeeds unless the source object generation
220  * matches.
221  */
223  : public internal::WellKnownParameter<IfSourceGenerationNotMatch,
224  std::int64_t> {
225  using WellKnownParameter<IfSourceGenerationNotMatch,
226  std::int64_t>::WellKnownParameter;
227  static char const* well_known_parameter_name() {
228  return "ifSourceGenerationNotMatch";
229  }
230 };
231 
232 /**
233  * A pre-condition: the request succeeds if the source object metadata
234  * generation matches.
235  */
237  : public internal::WellKnownParameter<IfSourceMetagenerationMatch,
238  std::int64_t> {
239  using WellKnownParameter<IfSourceMetagenerationMatch,
240  std::int64_t>::WellKnownParameter;
241  static char const* well_known_parameter_name() {
242  return "ifSourceMetagenerationMatch";
243  }
244 };
245 
246 /**
247  * A pre-condition: the request succeeds unless the source object metadata
248  * generation matches.
249  */
251  : public internal::WellKnownParameter<IfSourceMetagenerationNotMatch,
252  std::int64_t> {
253  using WellKnownParameter<IfSourceMetagenerationNotMatch,
254  std::int64_t>::WellKnownParameter;
255  static char const* well_known_parameter_name() {
256  return "ifSourceMetagenerationNotMatch";
257  }
258 };
259 
260 /**
261  * Configure the Customer-Managed Encryption Key (CMEK) for an upload.
262  *
263  * With CMEK you can use keys generated by Google Cloud's Key Management Service
264  * to encrypt the data in your objects. Use this option to configure the CMEK of
265  * an object created as part of a insert or copy. Key names can be found from
266  * the Google Cloud console, and are in the
267  * `projects/{PROJECT_ID}/locations/{LOCATION_ID}/keyRings/{KEY_RING_ID}/cryptoKeys/{CRYPTO_KEY_ID}`
268  * format.
269  *
270  * @see https://cloud.google.com/storage/docs/encryption/customer-managed-keys
271  * for a general introduction to CMEK in GCS.
272  */
274  : public internal::WellKnownParameter<KmsKeyName, std::string> {
275  using WellKnownParameter<KmsKeyName, std::string>::WellKnownParameter;
276  static char const* well_known_parameter_name() { return "kmsKeyName"; }
277 };
278 
279 /**
280  * Limit the number of results per page when listing Buckets and Objects.
281  *
282  * Applications may reduce the memory requirements of the Bucket and Object
283  * iterators by using smaller page sizes. The downside is that more requests
284  * may be needed to iterate over the full range of Buckets and/or Objects.
285  */
287  : public internal::WellKnownParameter<MaxResults, std::int64_t> {
288  using WellKnownParameter<MaxResults, std::int64_t>::WellKnownParameter;
289  static char const* well_known_parameter_name() { return "maxResults"; }
290 };
291 
292 /**
293  * Limit the number of bytes rewritten in a `Objects: rewrite` step.
294  *
295  * Applications should not need for the most part. It is used during testing, to
296  * ensure the code handles partial rewrites properly. Note that the value must
297  * be a multiple of 1 MiB (1048576).
298  */
300  : public internal::WellKnownParameter<MaxBytesRewrittenPerCall,
301  std::int64_t> {
302  using WellKnownParameter<MaxBytesRewrittenPerCall,
303  std::int64_t>::WellKnownParameter;
304  static char const* well_known_parameter_name() {
305  return "maxBytesRewrittenPerCall";
306  }
307 };
308 
309 /**
310  * Set the ACL to predefined values when creating Buckets or Objects.
311  *
312  * A predefined ACL is an alias for a set of specific ACL entries that you can
313  * use to quickly apply many ACL entries at once to a bucket or object.
314  *
315  * @see
316  * https://cloud.google.com/storage/docs/access-control/lists#predefined-acl for
317  * a more detailed description of Predefined ACLs in GCS.
318  */
320  : public internal::WellKnownParameter<PredefinedAcl, std::string> {
321  using WellKnownParameter<PredefinedAcl, std::string>::WellKnownParameter;
322  static char const* well_known_parameter_name() { return "predefinedAcl"; }
323 
325  return PredefinedAcl("authenticatedRead");
326  }
328  return PredefinedAcl("bucketOwnerFullControl");
329  }
331  return PredefinedAcl("bucketOwnerRead");
332  }
333  static PredefinedAcl Private() { return PredefinedAcl("private"); }
335  return PredefinedAcl("projectPrivate");
336  }
337  static PredefinedAcl PublicRead() { return PredefinedAcl("publicRead"); }
339  return PredefinedAcl("publicReadWrite");
340  }
341 
342  std::string HeaderName() const;
343 };
344 
345 /**
346  * Set the ACL to a predefined value when copying Objects.
347  *
348  * A predefined ACL is an alias for a set of specific ACL entries that you can
349  * use to quickly apply many ACL entries at once to a bucket or object.
350  *
351  * @see
352  * https://cloud.google.com/storage/docs/access-control/lists#predefined-acl for
353  * a more detailed description of Predefined ACLs in GCS.
354  */
356  : public internal::WellKnownParameter<DestinationPredefinedAcl,
357  std::string> {
358  using WellKnownParameter<DestinationPredefinedAcl,
359  std::string>::WellKnownParameter;
360  static char const* well_known_parameter_name() {
361  return "destinationPredefinedAcl";
362  }
363 
365  return DestinationPredefinedAcl("authenticatedRead");
366  }
368  return DestinationPredefinedAcl("bucketOwnerFullControl");
369  }
371  return DestinationPredefinedAcl("bucketOwnerRead");
372  }
374  return DestinationPredefinedAcl("private");
375  }
377  return DestinationPredefinedAcl("projectPrivate");
378  }
380  return DestinationPredefinedAcl("publicRead");
381  }
382 };
383 
384 /**
385  * Set the default object ACL to a predefined value in a Bucket.
386  *
387  * Every bucket has a default object ACL, and this ACL is applied to all objects
388  * uploaded to that bucket without a predefined ACL or an ACL specified in the
389  * request. When creating Buckets it is sometimes convenient to define the
390  * default object ACL to one of the predefined values.
391  *
392  * @see
393  * https://cloud.google.com/storage/docs/access-control/lists#defaultobjects for
394  * a mode detailed description of default object ACLs.
395  *
396  * @see
397  * https://cloud.google.com/storage/docs/access-control/lists#predefined-acl for
398  * a more detailed description of Predefined ACLs in GCS.
399  */
401  : public internal::WellKnownParameter<PredefinedDefaultObjectAcl,
402  std::string> {
403  using WellKnownParameter<PredefinedDefaultObjectAcl,
404  std::string>::WellKnownParameter;
405  static char const* well_known_parameter_name() {
406  return "predefinedDefaultObjectAcl";
407  }
408 
410  return PredefinedDefaultObjectAcl("authenticatedRead");
411  }
413  return PredefinedDefaultObjectAcl("bucketOwnerFullControl");
414  }
416  return PredefinedDefaultObjectAcl("bucketOwnerRead");
417  }
419  return PredefinedDefaultObjectAcl("private");
420  }
422  return PredefinedDefaultObjectAcl("projectPrivate");
423  }
425  return PredefinedDefaultObjectAcl("publicRead");
426  }
427 };
428 
429 /**
430  * Restrict list operations to entries starting with this value.
431  *
432  * This optional parameter applies to both the request to list objects and to
433  * the request that lists buckets. Setting a value for this option returns
434  * only the entries that start with the given prefix.
435  */
436 struct Prefix : public internal::WellKnownParameter<Prefix, std::string> {
437  using WellKnownParameter<Prefix, std::string>::WellKnownParameter;
438  static char const* well_known_parameter_name() { return "prefix"; }
439 };
440 
441 /**
442  * Returns results in a directory-like mode.
443  *
444  * Used in `Client::ListObjects` to return only those objects that do **not**
445  * contain the delimiter, unless said delimiter appears in the `Prefix`
446  * parameter (if any).
447  *
448  * @see https://cloud.google.com/storage/docs/json_api/v1/objects/list for more
449  * information.
450  */
451 struct Delimiter : public internal::WellKnownParameter<Delimiter, std::string> {
452  using WellKnownParameter<Delimiter, std::string>::WellKnownParameter;
453  static char const* well_known_parameter_name() { return "delimiter"; }
454 };
455 
456 /**
457  * If `true`, objects that end in exactly one instance of delimiter have their
458  * metadata included in `items[]` in addition to the relevant part of the object
459  * name appearing in `prefixes[]`.
460  *
461  * @see https://cloud.google.com/storage/docs/json_api/v1/objects/list for more
462  * information.
463  */
465  : public internal::WellKnownParameter<IncludeTrailingDelimiter, bool> {
466  using WellKnownParameter<IncludeTrailingDelimiter, bool>::WellKnownParameter;
467  static char const* well_known_parameter_name() {
468  return "includeTrailingDelimiter";
469  }
470 };
471 
472 /**
473  * Filter results to objects whose names are lexicographically equal to or after
474  * StartOffset.
475  *
476  * @see https://cloud.google.com/storage/docs/json_api/v1/objects/list for more
477  * information.
478  */
480  : public internal::WellKnownParameter<StartOffset, std::string> {
481  using WellKnownParameter<StartOffset, std::string>::WellKnownParameter;
482  static char const* well_known_parameter_name() { return "startOffset"; }
483 };
484 
485 /**
486  * Filter results to objects whose names are lexicographically before EndOffset.
487  *
488  * @see https://cloud.google.com/storage/docs/json_api/v1/objects/list for more
489  * information.
490  */
491 struct EndOffset : public internal::WellKnownParameter<EndOffset, std::string> {
492  using WellKnownParameter<EndOffset, std::string>::WellKnownParameter;
493  static char const* well_known_parameter_name() { return "endOffset"; }
494 };
495 
496 /**
497  * Controls what metadata fields are included in the response.
498  *
499  * For those operations that return the metadata of an Object or Bucket, this
500  * option controls if all the fields are returned (using `full`) or if the ACL
501  * fields (which can be long) are to be excluded (using `noACL`).
502  *
503  * Use the `Fields` option for more fine-grained control over the returned
504  * fields.
505  */
507  : public internal::WellKnownParameter<Projection, std::string> {
508  using WellKnownParameter<Projection, std::string>::WellKnownParameter;
509  static char const* well_known_parameter_name() { return "projection"; }
510 
511  static Projection NoAcl() { return Projection("noAcl"); }
512  static Projection Full() { return Projection("full"); }
513 };
514 
515 /**
516  * Sets the user for this operation for quota enforcement purposes.
517  *
518  * Google Cloud Platform allows you to set an arbitrary string, up to 40
519  * characters long, that identifies a "user" for quota enforcement purposes.
520  *
521  * @see https://cloud.google.com/apis/docs/capping-api-usage for an introduction
522  * to quotas in Google Cloud Platform.
523  */
524 struct QuotaUser : public internal::WellKnownParameter<QuotaUser, std::string> {
525  using WellKnownParameter<QuotaUser, std::string>::WellKnownParameter;
526  static char const* well_known_parameter_name() { return "quotaUser"; }
527 };
528 
529 /**
530  * Only list HMAC keys belonging to a specific Service Account.
531  */
533  : public internal::WellKnownParameter<ServiceAccountFilter, std::string> {
534  using WellKnownParameter<ServiceAccountFilter,
535  std::string>::WellKnownParameter;
536  static char const* well_known_parameter_name() {
537  return "serviceAccountEmail";
538  }
539 };
540 
541 /**
542  * Set the generation for the source object in copy operations.
543  *
544  * For objects in Buckets with `versioning` enabled, the application sometimes
545  * needs to specify which version of the object should the request target. This
546  * is an optional query parameter to control the version of the source object
547  * in copy operations.
548  *
549  * @see https://cloud.google.com/storage/docs/object-versioning for more
550  * information on GCS Object versioning.
551  */
553  : public internal::WellKnownParameter<SourceGeneration, std::int64_t> {
554  using WellKnownParameter<SourceGeneration, std::int64_t>::WellKnownParameter;
555  static char const* well_known_parameter_name() { return "sourceGeneration"; }
556 };
557 
558 /**
559  * Set the project used for billing in "requester pays" Buckets.
560  *
561  * GCS Buckets can be configured to charge the requester of an operation for all
562  * charges, as opposed to the project that owns the Bucket. Use this parameter
563  * when accessing such Buckets to control which project is charged. Note that
564  * the caller must have the right permissions in the billed project or the
565  * operation would fail.
566  *
567  * @see https://cloud.google.com/storage/docs/requester-pays for a detailed
568  * description of the requester pays features, which charges are incurred by
569  * the requester, and the exact permissions that you must have to make
570  * such a request.
571  */
573  : public internal::WellKnownParameter<UserProject, std::string> {
574  using WellKnownParameter<UserProject, std::string>::WellKnownParameter;
575  static char const* well_known_parameter_name() { return "userProject"; }
576 };
577 
578 /**
579  * Control if all versions of an object should be included when listing objects.
580  *
581  * By default requests listing objects only included the latest (live) version
582  * of each object, set this option to `true` to get all the previous versions.
583  *
584  * @see https://cloud.google.com/storage/docs/object-versioning for more
585  * information on GCS Object versioning.
586  */
587 struct Versions : public internal::WellKnownParameter<Versions, bool> {
588  using WellKnownParameter<Versions, bool>::WellKnownParameter;
589  static char const* well_known_parameter_name() { return "versions"; }
590 };
591 
592 /**
593  * Controls the IAM policy version returned by IAM queries.
594  *
595  * By default requests version 1 of the IAM policy, set this to 3 (or higher) to
596  * get IAM policies with conditions.
597  *
598  * @see https://cloud.google.com/iam/docs/policies#versions for more
599  * information on GCS iam policies and its versioning.
600  */
602  : public internal::WellKnownParameter<RequestedPolicyVersion,
603  std::int64_t> {
604  using WellKnownParameter<RequestedPolicyVersion,
605  std::int64_t>::WellKnownParameter;
606  static char const* well_known_parameter_name() {
607  return "optionsRequestedPolicyVersion";
608  }
609 };
610 
611 } // namespace STORAGE_CLIENT_NS
612 } // namespace storage
613 } // namespace cloud
614 } // namespace google
615 
616 #endif // GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_STORAGE_WELL_KNOWN_PARAMETERS_H