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.
Functions
ReadObject(std::string const &, std::string const &, std::int64_t, std::int64_t, RequestOptions &&...)
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 const &
the name of the bucket that contains the object. |
object_name |
std::string const &
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 |
options |
RequestOptions &&...
a list of optional query parameters and/or request headers. Valid types for this operation include |
typename... |
|
| Returns | |
|---|---|
| Type | Description |
future< AsyncReadObjectRangeResponse > |
|
ComposeObject(std::string, std::vector< storage::ComposeSourceObject >, std::string, Options &&...)
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. |
options |
Options &&...
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 const &, std::string const &, RequestOptions &&...)
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.
| Parameters | |
|---|---|
| Name | Description |
bucket_name |
std::string const &
the name of the bucket that contains the object. |
object_name |
std::string const &
the name of the object to be deleted. |
options |
RequestOptions &&...
a list of optional query parameters and/or request headers. Valid types for this operation include |
typename... |
|
| Returns | |
|---|---|
| Type | Description |
future< Status > |
|
StartResumableUpload(std::string const &, std::string const &, RequestOptions &&...)
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.
For small uploads we recommend usingInsertObject, consult the documentation for details.
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.
| Parameters | |
|---|---|
| Name | Description |
bucket_name |
std::string const &
the name of the bucket that contains the object. |
object_name |
std::string const &
the name of the object to be read. |
options |
RequestOptions &&...
a list of optional query parameters and/or request headers. Valid types for this operation include |
typename... |
|
| Returns | |
|---|---|
| Type | Description |
future< StatusOr< std::string > > |
|