Represents a Binding which associates a member with a particular role which can be used for Identity and Access management for Cloud Platform Resources.

NativeIamPolicy

Represent the result of a GetIamPolicy or SetIamPolicy request.

NotificationMetadata

Represents the metadata for a Google Cloud Storage Notification resource.

ObjectAccessControl

Wraps the objectAccessControl resource in Google Cloud Storage.

ObjectAccessControlPatchBuilder

Prepares a patch for an ObjectAccessControl resource.

ObjectMetadata

Represents the metadata for a Google Cloud Storage Object.

ObjectMetadataPatchBuilder

Prepares a patch for the Bucket resource.

ObjectReadStream

Defines a std::basic_istream<char> to read from a GCS Object.

ObjectRewriter

Complete long running object rewrite operations.

ObjectWriteStream

Defines a std::basic_ostream<char> to write to a GCS object.

PolicyDocumentCondition

Define a condition for a policy document.

ServiceAccount

Represents the metadata for a Google Cloud Storage service account.

StrictIdempotencyPolicy

A IdempotencyPolicy that only retries strictly idempotent requests.

Structs

AddExtensionFieldOption

Add a extension header to a POST policy.

AutoFinalize

Control whether upload streams auto-finalize on destruction.

BackoffPolicyOption

Set the backoff policy for a GCS client.

BucketAutoclass

The autoclass configuration for a Bucket.

BucketBoundHostname

Use domain-named bucket in a V4 signed URL.

BucketEncryption

Describes the default customer managed encryption key for a bucket.

BucketLifecycle

The Object Lifecycle configuration for a Bucket.

BucketVersioning

The versioning configuration for a Bucket.

ComposeSourceObject

Defines one of the source objects for a compose operation.

ContentEncoding

Sets the contentEncoding option for object uploads.

Crc32cChecksumValue

Provide a pre-computed CRC32C checksum value.

CustomerEncryption

A simple representation for the customerEncryption field.

Deleted

Included deleted HMAC keys in list requests.

Delimiter

Returns results in a directory-like mode.

DestinationKmsKeyName

Configure the Customer-Managed Encryption Key (CMEK) for an rewrite.

DestinationPredefinedAcl

Set the ACL to a predefined value when copying Objects.

DisableMD5Hash

Disable or enable MD5 Hashing computations.

DownloadBufferSizeOption

Control the formatted I/O download buffer.

DownloadStallMinimumRateOption

The minimum accepted bytes/second download rate.

EnableCurlSigpipeHandlerOption

Disables automatic OpenSSL sigpipe handler.

EncryptionKey

An optional parameter to set the Customer-Supplied Encryption key.

EncryptionKeyData

A simple wrapper for the encryption key attributes.

EndOffset

Filter results to objects whose names are lexicographically before EndOffset.

ExpirationTime

Define the expiration time for a signed URL.

Generation

Set the version of an object to operate on.

IamEndpointOption

Configure the IAM endpoint for the GCS client library.

IdempotencyPolicyOption

Set the idempotency policy for a GCS client.

IfGenerationMatch

A pre-condition: the request succeeds only if the object generation matches.

IfGenerationNotMatch

A pre-condition: the request succeeds unless the object generation matches.

IfMatchEtag

A pre-condition: apply this operation only if the HTTP Entity Tag matches.

IfMetagenerationMatch

A pre-condition: the request succeeds if the metadata generation matches.

IfMetagenerationNotMatch

A pre-condition: the request succeeds unless the metadata generation matches.

IfNoneMatchEtag

A pre-condition: apply this operation only if the HTTP Entity Tag does not match.

IfSourceGenerationMatch

A pre-condition: the request succeeds if the source object generation matches.

IfSourceGenerationNotMatch

A pre-condition: the request succeeds unless the source object generation matches.

IfSourceMetagenerationMatch

A pre-condition: the request succeeds if the source object metadata generation matches.

IfSourceMetagenerationNotMatch

A pre-condition: the request succeeds unless the source object metadata generation matches.

IncludeTrailingDelimiter

If true, objects that end in exactly one instance of delimiter have their metadata included in items[] in addition to the relevant part of the object name appearing in prefixes[].

KmsKeyName

Configure the Customer-Managed Encryption Key (CMEK) for an upload.

LifecycleRuleAction

Implement a wrapper for Lifecycle Rules actions.

LifecycleRuleCondition

Implement a wrapper for Lifecycle Conditions.

MaxBytesRewrittenPerCall

Limit the number of bytes rewritten in a Objects: rewrite step.

MaximumCurlSocketRecvSizeOption

Control the maximum socket receive buffer.

MaximumCurlSocketSendSizeOption

Control the maximum socket send buffer.

MaximumSimpleUploadSizeOption

Defines the threshold to switch from simple to resumable uploads for files.

MaxResults

Limit the number of results per page when listing Buckets and Objects.

Oauth2CredentialsOption

Configure oauth2::Credentials for the GCS client library.

Owner

A simple wrapper for the owner field in object and bucket metadata.

PredefinedAcl

Set the ACL to predefined values when creating Buckets or Objects.

PredefinedDefaultObjectAcl

Set the default object ACL to a predefined value in a Bucket.

Prefix

Restrict list operations to entries starting with this value.

ProjectIdOption

Set the Google Cloud Platform project id.

Projection

Controls what metadata fields are included in the response.

ProjectTeam

Represents the projectTeam field in *AccessControls.

QuotaUser

Sets the user for this operation for quota enforcement purposes.

ReadFromOffset

Download all the data from the GCS object starting at the given offset.

ReadRange

Request only a portion of the GCS object in a ReadObject operation.

RequestedPolicyVersion

Controls the IAM policy version returned by IAM queries.

RestEndpointOption

Configure the REST endpoint for the GCS client library.

RewriteProgress

Represents the status of a rewrite operation.

Scheme

Use the specified scheme (e.g. "http") in a V4 signed URL.

ServiceAccountFilter

Only list HMAC keys belonging to a specific Service Account.

SignedUrlDuration

Define the duration for a V4 signed URL.

SignedUrlTimestamp

Define the timestamp duration for a V4 signed URL.

SigningAccount

Specify the service account used to sign a blob.

SigningAccountDelegates

Specify the sequence of delegates used to sign a blob.

SourceEncryptionKey

An optional parameter to set the Customer-Supplied Encryption key for rewrite source object.

SourceGeneration

Set the generation for the source object in copy operations.

StartOffset

Filter results to objects whose names are lexicographically equal to or after StartOffset.

TransferStallMinimumRateOption

The minimum accepted bytes/second transfer rate.

UniformBucketLevelAccess

Configure if only the IAM policies are used for access control.

UploadBufferSize

Set the buffer size for a stream created in Client::WriteObject().

UploadBufferSizeOption

Control the formatted I/O upload buffer.

UploadContentLength

Provide an expected final length of an uploaded object.

UploadFromOffset

Upload the local file to GCS server starting at the given offset.

UploadLimit

The maximum length of the local file to upload to GCS server.

UseResumableUploadSession

Request a resumable upload, restoring a previous session if necessary.

UserIp

Sets the user IP on an operation for quota enforcement purposes.

UserProject

Set the project used for billing in "requester pays" Buckets.

Versions

Control if all versions of an object should be included when listing objects.

VirtualHostname

Indicate that the bucket should be a part of hostname in the URL.

WithObjectMetadata

A request option to define the object metadata attributes.

Enums

Functions

PublicAccessPreventionEnforced()

Public Access Prevention helper functions

Returns
Type	Description
`std::string`

PublicAccessPreventionInherited()

Public Access Prevention helper functions

Returns
Type	Description
`std::string`

PublicAccessPreventionUnspecified()

Public Access Prevention helper functions

Returns
Type	Description
`std::string`

TEAM_EDITORS()

Well-known values for the project_team().team field..

The following functions are handy to avoid common typos in the team names.

We use functions instead of enums because enums are not backwards compatible and are brittle to changes in the server-side.

Returns
Type	Description
`std::string`

TEAM_OWNERS()

Well-known values for the project_team().team field..

The following functions are handy to avoid common typos in the team names.

We use functions instead of enums because enums are not backwards compatible and are brittle to changes in the server-side.

Returns
Type	Description
`std::string`

TEAM_VIEWERS()

Well-known values for the project_team().team field..

The following functions are handy to avoid common typos in the team names.

We use functions instead of enums because enums are not backwards compatible and are brittle to changes in the server-side.

Returns
Type	Description
`std::string`

AutoFinalizeEnabled()

Configure a stream to automatically finalize an upload on destruction.

Returns
Type	Description
`AutoFinalize`

AutoFinalizeDisabled()

Configure a stream to leave uploads pending (not finalized) on destruction.

Returns
Type	Description
`AutoFinalize`

RpoDefault()

A helper function to avoid typos in the RPO configuration.

Returns
Type	Description
`std::string`

RpoAsyncTurbo()

A helper function to avoid typos in the RPO configuration.

Returns
Type	Description
`std::string`

CreateRandomPrefixName(std::string const &)

Create a random prefix for object names.

This is useful for operations which require a unique prefix for temporary files.

This is a helper function and it doesn't communicate with GCS, so there is a very small chance that names generated this way aren't unique. The chance should be small enough to fit any error budget.

Given the same prefix, the randomly generated names will have the same length.

Parameter
Name	Description
`prefix`	the prefix of the prefix to be created.

Returns
Type	Description
`std::string`	the random prefix name

DeleteByPrefix(Client &, std::string const &, std::string const &, Options &&...)

Delete objects whose names match a given prefix.

Parameters
Name	Description
`client`	the client on which to perform the operation.
`bucket_name`	the name of the bucket that will contain the object.
`prefix`	the prefix of the objects to be deleted.
`options`	a list of optional query parameters and/or request headers. Valid types for this operation include `QuotaUser`, `UserIp`, `UserProject` and `Versions`.
`typename...`

Returns
Type	Description
`Status`

ComposeMany(Client &, std::string const &, std::vector< ComposeSourceObject >, std::string const &, std::string, bool, Options &&...)

Compose existing objects into a new object in the same bucket.

Contrary to Client::ComposeObject, this function doesn't have a limit on the number of source objects.

The implementation may need to perform multiple Client::ComposeObject calls to create intermediate, temporary objects which are then further composed. Due to the lack of atomicity of this series of operations, stray temporary objects might be left over if there are transient failures. In order to allow the user to easily control for such situations, the user is expected to provide a unique prefix parameter, which will become the prefix of all the temporary objects created by this function. Once this function finishes, the user may safely remove all objects with the provided prefix (e.g. via DeleteByPrefix()). We recommend using CreateRandomPrefixName() for selecting a random prefix within a bucket.

Idempotency

This operation is not idempotent. While each request performed by this function is retried based on the client policies, the operation itself stops on the first request that fails.

Example

  namespace gcs = ::google::cloud::storage;
  using ::google::cloud::StatusOr;
  [](gcs::Client client, std::string const& bucket_name,
     std::string const& destination_object_name,
     std::vector<gcs::ComposeSourceObject> const& compose_objects) {
    std::string prefix = gcs::CreateRandomPrefixName(".tmpfiles");
    StatusOr<gcs::ObjectMetadata> composed_object =
        ComposeMany(client, bucket_name, compose_objects, prefix,
                    destination_object_name, false);
    // If this is an effect of some transient unavailability, stray temporary
    // might be left over. You can use `DeleteByPrefix()` with `prefix` as
    // argument to delete them.
    if (!composed_object) throw std::move(composed_object).status();

    std::cout << "Composed new object " << composed_object->name()
              << " in bucket " << composed_object->bucket()
              << "\nFull metadata: " << *composed_object << "\n";
  }

Parameters
Name	Description
`client`	the client on which to perform the operations needed by this function
`bucket_name`	the name of the bucket used for source object and destination object.
`source_objects`	objects used to compose `destination_object_name`.
`prefix`	prefix for temporary objects created by this function; there should not be any objects with this prefix; in order to avoid race conditions, this function will create an object with this name
`destination_object_name`	the composed object name.
`ignore_cleanup_failures`	if the composition succeeds but cleanup of temporary objects fails, depending on this parameter either a success will be returned (`true`) or the relevant cleanup error (`false`)
`options`	a list of optional query parameters and/or request headers. Valid types for this operation include `DestinationPredefinedAcl`, `EncryptionKey`, `IfGenerationMatch`, `IfMetagenerationMatchKmsKeyName`, `QuotaUser`, `UserIp`, `UserProject` and `WithObjectMetadata`.
`typename...`

Returns
Type	Description
`StatusOr< ObjectMetadata >`

ComputeMD5Hash(absl::string_view)

Compute the MD5 Hash of a buffer in the format preferred by GCS.

Parameter
Name	Description
`payload`

Returns
Type	Description
`std::string`

ComputeMD5Hash(std::string const &)

Compute the MD5 Hash of a buffer in the format preferred by GCS.

Parameter
Name	Description
`payload`

Returns
Type	Description
`std::string`

ComputeMD5Hash(char const *)

Compute the MD5 Hash of a buffer in the format preferred by GCS.

Parameter
Name	Description
`payload`

Returns
Type	Description
`std::string`

EnableMD5Hash()

Enable MD5 hashes in upload and download operations.

Use this function where the option DisableMD5Hash is expected to enable MD5 hashes.

Returns
Type	Description
`DisableMD5Hash`

ComputeCrc32cChecksum(absl::string_view)

Compute the CRC32C checksum of a buffer in the format preferred by GCS.

Parameter
Name	Description
`payload`

Returns
Type	Description
`std::string`

ComputeCrc32cChecksum(std::string const &)

Compute the CRC32C checksum of a buffer in the format preferred by GCS.

Parameter
Name	Description
`payload`

Returns
Type	Description
`std::string`

ComputeCrc32cChecksum(char const *)

Compute the CRC32C checksum of a buffer in the format preferred by GCS.

Parameter
Name	Description
`payload`

Returns
Type	Description
`std::string`

ParallelUploadFile(Client, std::string, std::string, std::string, std::string, bool, Options &&...)

Perform a parallel upload of a given file.

You can affect how many shards will be created by using the MaxStreams and MinStreamSize options.

Idempotency

This operation is not idempotent. While each request performed by this function is retried based on the client policies, the operation itself stops on the first request that fails.

Example

  namespace gcs = ::google::cloud::storage;
  using ::google::cloud::StatusOr;
  [](gcs::Client client, std::string const& file_name,
     std::string const& bucket_name, std::string const& object_name) {
    // Pick a unique random prefix for the temporary objects created by the
    // parallel upload.
    auto prefix = gcs::CreateRandomPrefixName("");

    auto metadata = gcs::ParallelUploadFile(
        std::move(client), file_name, bucket_name, object_name, prefix, false);
    if (!metadata) throw std::move(metadata).status();

    std::cout << "Uploaded " << file_name << " to object " << metadata->name()
              << " in bucket " << metadata->bucket()
              << "\nFull metadata: " << *metadata << "\n";
  }

Parameters
Name	Description
`client`	the client on which to perform the operation.
`file_name`	the path to the file to be uploaded
`bucket_name`	the name of the bucket that will contain the object.
`object_name`	the uploaded object name.
`prefix`	the prefix with which temporary objects will be created.
`ignore_cleanup_failures`	treat failures to cleanup the temporary objects as not fatal.
`options`	a list of optional query parameters and/or request headers. Valid types for this operation include `DestinationPredefinedAcl`, `EncryptionKey`, `IfGenerationMatch`, `IfMetagenerationMatch`, `KmsKeyName`, `MaxStreams,`MinStreamSize`,`QuotaUser`,`UserIp`,`UserProject`,`WithObjectMetadata`,`UseResumableUploadSession`.
`typename...`

Returns
Type	Description
`StatusOr< ObjectMetadata >`	the metadata of the object created by the upload.

FormatDateForForm(PolicyDocumentV4Result const &)

Format the current date in the format expected by a POST form.

Parameter
Name	Description

Returns
Type	Description
`std::string`

AddExtensionHeader(std::string, std::string)

Parameters
Name	Description
`header`
`value`

Returns
Type	Description
`AddExtensionHeaderOption`

WithGeneration(std::uint64_t)

Parameter
Name	Description
`generation`

Returns
Type	Description
`AddQueryParameterOption`

WithGenerationMarker(std::uint64_t)

Parameter
Name	Description
`generation`

Returns
Type	Description
`AddQueryParameterOption`

WithUserProject(std::string)

Parameter
Name	Description
`user_project`

Returns
Type	Description
`AddQueryParameterOption`

WithMarker(std::string)

Parameter
Name	Description
`marker`

Returns
Type	Description
`AddQueryParameterOption`

WithResponseContentDisposition(std::string)

Parameter
Name	Description
`disposition`

Returns
Type	Description
`AddQueryParameterOption`

WithResponseContentType(std::string const &)

Parameter
Name	Description
`type`

Returns
Type	Description
`AddQueryParameterOption`

WithAcl()

Returns
Type	Description
`SubResourceOption`

WithBilling()

Returns
Type	Description
`SubResourceOption`

WithCompose()

Returns
Type	Description
`SubResourceOption`

WithCors()

Returns
Type	Description
`SubResourceOption`

WithEncryption()

Returns
Type	Description
`SubResourceOption`

WithEncryptionConfig()

Returns
Type	Description
`SubResourceOption`

WithLifecycle()

Returns
Type	Description
`SubResourceOption`

WithLocation()

Returns
Type	Description
`SubResourceOption`

WithLogging()

Returns
Type	Description
`SubResourceOption`

WithStorageClass()

Returns
Type	Description
`SubResourceOption`

WithTagging()

Returns
Type	Description
`SubResourceOption`

AddExtensionField(std::string, std::string)

Parameters
Name	Description
`field`
`value`

Returns
Type	Description
`AddExtensionFieldOption`

RestoreResumableUploadSession(std::string)

Create a UseResumableUploadSession option that restores previous sessions.

Parameter
Name	Description
`session_id`

Returns
Type	Description
`UseResumableUploadSession`

NewResumableUploadSession()

Create a UseResumableUploadSession option that requests new sessions.

Returns
Type	Description
`UseResumableUploadSession`

version_major()

Returns the Google Cloud Storage C++ Client major version.

version_minor()

Returns the Google Cloud Storage C++ Client minor version.

version_patch()

Returns the Google Cloud Storage C++ Client patch version.

version_pre_release()

Returns the Google Cloud Storage C++ Client pre-release version.

version()

Returns a single integer representing the Major/Minor/Patch version.

Returns
Type	Description
`int constexpr`

version_string()

Returns the version as a string, in MAJOR.MINOR.PATCH[-PRE][+gitrev] format.

Returns
Type	Description
`std::string`

x_goog_api_client()

Returns the value for x-goog-api-client header.

Returns
Type	Description
`std::string`

EncryptionDataFromBinaryKey(std::string const &)

Formats a (potentially binary) encryption key in the format required by the Google Cloud Storage API.

Parameter
Name	Description
`key`	a binary key, must have exactly 32 bytes.

Returns
Type	Description
`EncryptionKeyData`

EncryptionDataFromBase64Key(std::string const &)

Formats an encryption key in base64 format to the data structure required by the Google Cloud Storage API.

Parameter
Name	Description
`key`	a base64-encoded key, must have exactly 32 bytes when decoded.

Returns
Type	Description
`EncryptionKeyData`

CreateKeyFromGenerator(Generator &)

Creates an encryption key parameter from a pseudo-random number generator.

Example

  // Create a pseudo-random number generator (PRNG), this is included for
  // demonstration purposes only. You should consult your security team about
  // best practices to initialize PRNG. In particular, you should verify that
  // the C++ library and operating system provide enough entropy to meet the
  // security policies in your organization.

  // Use the Mersenne-Twister Engine in this example:
  //   https://en.cppreference.com/w/cpp/numeric/random/mersenne_twister_engine
  // Any C++ PRNG can be used below, the choice is arbitrary.
  using GeneratorType = std::mt19937_64;

  // Create the default random device to fetch entropy.
  std::random_device rd;

  // Compute how much entropy we need to initialize the GeneratorType:
  constexpr auto kRequiredEntropyWords =
      GeneratorType::state_size *
      (GeneratorType::word_size / std::numeric_limits<unsigned int>::digits);

  // Capture the entropy bits into a vector.
  std::vector<std::uint64_t> entropy(kRequiredEntropyWords);
  std::generate(entropy.begin(), entropy.end(), [&rd] { return rd(); });

  // Create the PRNG with the fetched entropy.
  std::seed_seq seed(entropy.begin(), entropy.end());

  // initialized with enough entropy such that the encryption keys are not
  // predictable. Note that the default constructor for all the generators in
  // the C++ standard library produce predictable keys.
  std::mt19937_64 gen(seed);

  namespace gcs = ::google::cloud::storage;
  gcs::EncryptionKeyData data = gcs::CreateKeyFromGenerator(gen);

  std::cout << "Base64 encoded key = " << data.key << "\n"
            << "Base64 encoded SHA256 of key = " << data.sha256 << "\n";

AcceptEncodingGzip()

Returns
Type	Description
`AcceptEncoding`

AcceptEncodingIdentity()

Returns
Type	Description
`AcceptEncoding`

Type Aliases

BucketPolicyOnly

Alias Of: UniformBucketLevelAccess

HeadersMap

Alias Of: std::multimap< std::string, std::string >

Represents the headers returned in a streaming upload or download operation.

ListBucketsReader

Alias Of: google::cloud::internal::PaginationRange< BucketMetadata >

ListBucketsIterator

Alias Of: ListBucketsReader::iterator

ListHmacKeysReader

Alias Of: google::cloud::internal::PaginationRange< HmacKeyMetadata >

A range to paginate over the HmacKeys for a project.

ListHmacKeysIterator

Alias Of: ListHmacKeysReader::iterator

ObjectOrPrefix

Alias Of: absl::variant< ObjectMetadata, std::string >

ListObjectsAndPrefixesReader

Alias Of: google::cloud::internal::PaginationRange< ObjectOrPrefix >

ListObjectsAndPrefixesIterator

Alias Of: ListObjectsAndPrefixesReader::iterator

ListObjectsReader

Alias Of: google::cloud::internal::PaginationRange< ObjectMetadata >

ListObjectsIterator

Alias Of: ListObjectsReader::iterator

ClientOptionList

Alias Of:

::google::cloud::OptionList< RestEndpointOption, IamEndpointOption, Oauth2CredentialsOption, ProjectIdOption, ProjectIdOption, ConnectionPoolSizeOption, DownloadBufferSizeOption, UploadBufferSizeOption, EnableCurlSslLockingOption, EnableCurlSigpipeHandlerOption, MaximumCurlSocketRecvSizeOption, MaximumCurlSocketSendSizeOption, TransferStallTimeoutOption, RetryPolicyOption, BackoffPolicyOption, IdempotencyPolicyOption, CARootsFilePathOption, storage_experimental::HttpVersionOption >

The complete list of options accepted by storage::Client.

RetryPolicy

Alias Of: ::google::cloud::internal::TraitBasedRetryPolicy< internal::StatusTraits >

The retry policy base class.

LimitedTimeRetryPolicy

Alias Of: ::google::cloud::internal::LimitedTimeRetryPolicy< internal::StatusTraits >

Keep retrying until some time has expired.

LimitedErrorCountRetryPolicy

Alias Of: ::google::cloud::internal::LimitedErrorCountRetryPolicy< internal::StatusTraits >

Keep retrying until the error count has been exceeded.

BackoffPolicy

Alias Of: ::google::cloud::internal::BackoffPolicy

The backoff policy base class.

ExponentialBackoffPolicy

Alias Of: ::google::cloud::internal::ExponentialBackoffPolicy

Implement truncated exponential backoff with randomization.

Parameters
Name	Description
`gen`	the pseudo-random number generator.
`typename Generator`	the pseudo-random number generator type, it must meet the `UniformRandomBitGenerator` requirements.