A client for Google Cloud Storage offering asynchronous operations.
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:```cpp 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:
```cpp
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, preferQuotaUserinstead.
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.
Constructors
AsyncClient(Options)
Create a new client configured with options.
| Parameter | |
|---|---|
| Name | Description |
options |
Options
|
AsyncClient(std::shared_ptr< AsyncConnection >)
Create a new client using connection. This is often used for mocking.
| Parameter | |
|---|---|
| Name | Description |
connection |
std::shared_ptr< AsyncConnection >
|
Functions
InsertObject(std::string, std::string, Collection &&, Args &&...)
Creates an object given its name and contents.
Idempotency
This operation is only idempotent if restricted by pre-conditions, in this case, IfGenerationMatch.
Example
namespace gcs_ex = google::cloud::storage_experimental;
[](gcs_ex::AsyncClient& client, std::string bucket_name,
std::string object_name) {
auto object =
client.InsertObject(std::move(bucket_name), std::move(object_name),
std::string("Hello World!\n"));
// Attach a callback, this is called when the upload completes.
auto done = object.then([](auto f) {
auto metadata = f.get();
if (!metadata) throw std::move(metadata).status();
std::cerr << "Object successfully inserted " << *metadata << "\n";
});
// To simplify example, block until the operation completes.
done.get();
}
| Parameters | |
|---|---|
| Name | Description |
bucket_name |
std::string
the name of the bucket that will contain the object. |
object_name |
std::string
the name of the object to be created. |
contents |
Collection &&
the contents (media) for the new object. |
args |
Args &&...
a list of optional query parameters and/or request headers. Valid types for this operation include |
typename Collection |
the type for the payload. This must be convertible to |
typename... |
|
| Returns | |
|---|---|
| Type | Description |
future< StatusOr< storage::ObjectMetadata > > | |
ReadObject(std::string, std::string, Args &&...)
Reads the contents of an object.
When satisfied, the returned future has a reader to asynchronously download the contents of the given object.
Idempotency
This is a read-only operation and is always idempotent.
Example
namespace gcs_ex = google::cloud::storage_experimental;
auto coro =
[](gcs_ex::AsyncClient& client, std::string bucket_name,
std::string object_name) -> google::cloud::future<std::uint64_t> {
auto [reader, token] = (co_await client.ReadObject(std::move(bucket_name),
std::move(object_name)))
.value();
std::uint64_t count = 0;
while (token.valid()) {
auto [payload, t] = (co_await reader.Read(std::move(token))).value();
token = std::move(t);
for (auto const& buffer : payload.contents()) {
count += std::count(buffer.begin(), buffer.end(), '\n');
}
}
co_return count;
};
| Parameters | |
|---|---|
| Name | Description |
bucket_name |
std::string
the name of the bucket that contains the object. |
object_name |
std::string
the name of the object to be read. |
args |
Args &&...
a list of optional query parameters and/or request headers. Valid types for this operation include |
typename... |
|
| Returns | |
|---|---|
| Type | Description |
future< StatusOr< std::pair< AsyncReader, AsyncToken > > > | |
ReadObjectRange(std::string, std::string, std::int64_t, std::int64_t, Args &&...)
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.
Idempotency
This is a read-only operation and is always idempotent.
| Parameters | |
|---|---|
| Name | Description |
bucket_name |
std::string
the name of the bucket that contains the object. |
object_name |
std::string
the name of the object to be read. |
offset |
std::int64_t
where to begin reading from the object, results in an error if the offset is larger than the object |
limit |
std::int64_t
how much data to read starting at |
args |
Args &&...
a list of optional query parameters and/or request headers. Valid types for this operation include |
typename... |
|
| Returns | |
|---|---|
| Type | Description |
future< AsyncReadObjectRangeResponse > | |
WriteObject(std::string, std::string, Args &&...)
| Parameters | |
|---|---|
| Name | Description |
bucket_name |
std::string
|
object_name |
std::string
|
args |
Args &&...
|
typename... |
|
| Returns | |
|---|---|
| Type | Description |
future< StatusOr< std::pair< AsyncWriter, AsyncToken > > > | |
ComposeObject(std::string, std::vector< storage::ComposeSourceObject >, std::string, Args &&...)
Composes existing objects into a new object in the same bucket.
Idempotency
This operation is only idempotent if restricted by pre-conditions, in this case, IfGenerationMatch.
| Parameters | |
|---|---|
| Name | Description |
bucket_name |
std::string
the name of the bucket used for source object and destination object. |
source_objects |
std::vector< storage::ComposeSourceObject >
objects used to compose |
destination_object_name |
std::string
the composed object name. |
args |
Args &&...
a list of optional query parameters and/or request headers. Valid types for this operation include |
typename... |
|
| Returns | |
|---|---|
| Type | Description |
future< StatusOr< storage::ObjectMetadata > > | |
DeleteObject(std::string, std::string, Args &&...)
Deletes an object.
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.
Example
namespace g = google::cloud;
namespace gcs_ex = google::cloud::storage_experimental;
[](gcs_ex::AsyncClient& client, std::string bucket_name,
std::string object_name) {
client.DeleteObject(std::move(bucket_name), std::move(object_name))
.then([](auto f) {
auto status = f.get();
if (!status.ok()) throw g::Status(std::move(status));
std::cout << "Object successfully deleted\n";
})
.get();
}
| Parameters | |
|---|---|
| Name | Description |
bucket_name |
std::string
the name of the bucket that contains the object. |
object_name |
std::string
the name of the object to be deleted. |
args |
Args &&...
a list of optional query parameters and/or request headers. Valid types for this operation include |
typename... |
|
| Returns | |
|---|---|
| Type | Description |
future< Status > | |