An interface to asynchronously perform resumable uploads.
The client library uses the google.storage.v2.StorageService.BidiWriteObject
RPC to perform asynchronous resumable uploads to Google Cloud Storage. As the name implies, this is a bi-directional RPC. The messages sent via this RPC are google.storage.v2.BidiWriteObjectRequest
and google.storage.v2.BidiWriteObjectResponse
.
- The
BidiWriteObjectRequest
messages upload the object data. - The last
BidiWriteObjectRequest
message in an upload must include afinalize
attribute. These messages result in aBidiWriteObjectResponse
message, which includes the metadata of the GCS object created by the upload. BidiWriteObjectRequest
messages may include aflush
attribute. Such messages result in aBidiReadObjectResponse
message, which includes how much of the uploaded data has been persisted.BidiWriteObjectRequest
messages may not include more thangoogle.storage.v2.ServiceConstants.MAX_WRITE_CHUNK_BYTES
bytes of payload.
In this interface different member functions write messages with different attributes.
The Write()
member function uploads some data, without setting any finalize
or flush
attributes. If necessary, the data is broken into multiple BidiWriteObjectRequest
messages.
The Finalize()
member function uploads some data and sets the finalize
attribute. If needed, the data is broken into multiple messages to satisfy the MAX_WRITE_CHUNK_BYTES
limit. Only the last message has the finalize
attribute. This function also waits for the response message and returns the object metadata (or an error).
The Flush()
member function uploads some data and sets the flush
attribute. As with the other functions the data may need to be broken into multiple messages. Only the last message will have the flush
attribute set.
This interface can be used to mock the behavior of these bidirectional streaming RPCs. Applications may use these mocks in their own tests.
Functions
Cancel()
Cancels the streaming RPC, terminating any pending operations.
Returns | |
---|---|
Type | Description |
void |
UploadId() const
Returns the upload id. Used to checkpoint the state and resume uploads.
Returns | |
---|---|
Type | Description |
std::string |
PersistedState() const
Returns the last known state of the upload.
Updated during initialization and by successful Query()
or Finalize()
requests.
Returns | |
---|---|
Type | Description |
absl::variant< std::int64_t, google::storage::v2::Object > |
Write(WritePayload)
Uploads some data to the service.
Parameter | |
---|---|
Name | Description |
payload |
WritePayload
|
Returns | |
---|---|
Type | Description |
future< Status > |
Finalize(WritePayload)
Finalizes an upload.
Parameter | |
---|---|
Name | Description |
|
WritePayload
|
Returns | |
---|---|
Type | Description |
future< StatusOr< google::storage::v2::Object > > |
Flush(WritePayload)
Uploads some data to the service and flushes the value.
Parameter | |
---|---|
Name | Description |
payload |
WritePayload
|
Returns | |
---|---|
Type | Description |
future< Status > |
Query()
Wait for the result of a Flush()
call.
Returns | |
---|---|
Type | Description |
future< StatusOr< std::int64_t > > |
GetRequestMetadata()
Return the request metadata.
Returns | |
---|---|
Type | Description |
RpcMetadata |