google::cloud::storage_experimental::AsyncClient Class Reference

A client for Google Cloud Storage offering asynchronous operations. More...

#include <google/cloud/storage/async_client.h>

Public Member Functions
	~AsyncClient ()=default
template<typename... RequestOptions>
future< AsyncReadObjectRangeResponse >	ReadObject (std::string const &bucket_name, std::string const &object_name, std::int64_t offset, std::int64_t limit, RequestOptions &&... options)
	Reads the contents of an object. More...
template<typename... Options>
future< StatusOr< storage::ObjectMetadata > >	ComposeObject (std::string bucket_name, std::vector< storage::ComposeSourceObject > source_objects, std::string destination_object_name, Options &&... options)
	Composes existing objects into a new object in the same bucket. More...
template<typename... RequestOptions>
future< Status >	DeleteObject (std::string const &bucket_name, std::string const &object_name, RequestOptions &&... options)
	Deletes an object. More...
template<typename... RequestOptions>
future< StatusOr< std::string > >	StartResumableUpload (std::string const &bucket_name, std::string const &object_name, RequestOptions &&... options)
	Starts a resumable upload. More...

Friends
AsyncClient	MakeAsyncClient (Options opts)
	Creates a new GCS client exposing asynchronous APIs. More...

Detailed Description

A client for Google Cloud Storage offering asynchronous operations.

Note

This class is experimental, it is subject to change without notice.

Optional Request Options

Most of the member functions in this class can receive optional request options. For example, the default when deleting an object is to delete the latest version:

auto pending = gcs.DeleteObject("my-bucket", "my-object");

Some applications may want to delete a specific version. In this case just provide the Generation request option:

auto pending = gcs.DeleteObject(
    "my-bucket", "my-object", gcs::Generation(generation));

Each function documents the types accepted as optional request options. These parameters can be specified in any order. Specifying a request option that is not applicable to a member function results in a compile-time error.

All operations support the following common request options:

• Fields: return a partial response, which includes only the desired fields.
• QuotaUser: attribute the request to this specific label for quota purposes.
• UserProject: change the request costs (if applicable) to this GCP project.
• CustomHeader: include a custom header with the request. These are typically used for testing, though they are sometimes helpful if environments where HTTPS traffic is mediated by a proxy.
• UserIp: attribute the request to this specific IP address for quota purpose. Not recommended, prefer QuotaUser instead.

Per-operation Overrides

In addition to the request options, which are passed on to the service to modify the request, you can specify options that override the local behavior of the library. For example, you can override the local retry policy:

auto pending = gcs.DeleteObject(
    "my-bucket", "my-object",
     google::cloud::Options{}
         .set<gcs::RetryPolicyOption>(
             gcs::LimitedErrorCountRetryPolicy(5).clone()));

Retry, Backoff, and Idempotency Policies

The library automatically retries requests that fail with transient errors, and follows the recommended practice to backoff between retries.

The default policies are to continue retrying for up to 15 minutes, and to use truncated (at 5 minutes) exponential backoff, doubling the maximum backoff period between retries. Likewise, the idempotency policy is configured to retry all operations.

The application can override these policies when constructing objects of this class. The documentation for the constructors shows examples of this in action.

Constructor & Destructor Documentation

~AsyncClient()

google::cloud::storage_experimental::AsyncClient::~AsyncClient ( )

default

Member Function Documentation

ComposeObject()

template<typename... Options>

future< StatusOr< storage::ObjectMetadata > > google::cloud::storage_experimental::AsyncClient::ComposeObject ( std::string  bucket_name, std::vector< storage::ComposeSourceObject >  source_objects, std::string  destination_object_name, Options &&...  options  )

inline

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

Parameters

bucket_name	the name of the bucket used for source object and destination object.
source_objects	objects used to compose destination_object_name.
destination_object_name	the composed object name.
options	a list of optional query parameters and/or request headers. Valid types for this operation include DestinationPredefinedAcl, EncryptionKey, IfGenerationMatch, IfMetagenerationMatch, KmsKeyName, UserProject, and WithObjectMetadata.

Idempotency

This operation is only idempotent if restricted by pre-conditions, in this case, IfGenerationMatch.

DeleteObject()

template<typename... RequestOptions>

future< Status > google::cloud::storage_experimental::AsyncClient::DeleteObject ( std::string const &  bucket_name, std::string const &  object_name, RequestOptions &&...  options  )

inline

Deletes an object.

Parameters

bucket_name	the name of the bucket that contains the object.
object_name	the name of the object to be deleted.
options	a list of optional query parameters and/or request headers. Valid types for this operation include Generation, IfGenerationMatch, IfGenerationNotMatch, IfMetagenerationMatch, IfMetagenerationNotMatch, and UserProject. See the class description for common request options.

Idempotency

This operation is only idempotent if:

• restricted by pre-conditions, in this case, IfGenerationMatch
• or, if it applies to only one object version via Generation.

ReadObject()

template<typename... RequestOptions>

future< AsyncReadObjectRangeResponse > google::cloud::storage_experimental::AsyncClient::ReadObject ( std::string const &  bucket_name, std::string const &  object_name, std::int64_t  offset, std::int64_t  limit, RequestOptions &&...  options  )

inline

Reads the contents of an object.

When satisfied, the returned future has the contents of the given object between offset and offset + limit (exclusive).

Be aware that this will accumulate all the bytes in memory, you need to consider whether limit is too large for your deployment environment.

Parameters

bucket_name	the name of the bucket that contains the object.
object_name	the name of the object to be read.
offset	where to begin reading from the object, results in an error if the offset is larger than the object
limit	how much data to read starting at offset
options	a list of optional query parameters and/or request headers. Valid types for this operation include DisableCrc32cChecksum, DisableMD5Hash, EncryptionKey, Generation, IfGenerationMatch, IfGenerationNotMatch, IfMetagenerationMatch, IfMetagenerationNotMatch, UserProject, and AcceptEncoding.

Idempotency

This is a read-only operation and is always idempotent.

StartResumableUpload()

template<typename... RequestOptions>

future< StatusOr< std::string > > google::cloud::storage_experimental::AsyncClient::StartResumableUpload ( std::string const &  bucket_name, std::string const &  object_name, RequestOptions &&...  options  )

inline

Starts a resumable upload.

This creates an upload id, which later can be used to upload an object. Resumable uploads can continue, even if the program performing the upload needs to restart.

Note

When resuming uploads it is the application's responsibility to save the upload id to restart the upload later.

For small uploads we recommend using InsertObject, consult the documentation for details.

Parameters

bucket_name	the name of the bucket that contains the object.
object_name	the name of the object to be read.
options	a list of optional query parameters and/or request headers. Valid types for this operation include ContentEncoding, ContentType, Crc32cChecksumValue, DisableCrc32cChecksum, DisableMD5Hash, EncryptionKey, IfGenerationMatch, IfGenerationNotMatch, IfMetagenerationMatch, IfMetagenerationNotMatch, KmsKeyName, MD5HashValue, PredefinedAcl, Projection, UserProject, WithObjectMetadata, UploadContentLength, AutoFinalize, and UploadBufferSize.

Idempotency

This operation is always idempotent. The only side-effect is the creation of a resumable upload id, which are automatically garbage collected after 7 days, and have no additional costs. Furthermore, this side-effect is not observable, as there is no way to list the current upload ids.

See also

Resumable Uploads for more information about resumable uploads.

Friends And Related Function Documentation

MakeAsyncClient

AsyncClient MakeAsyncClient ( Options  opts )

friend

Creates a new GCS client exposing asynchronous APIs.