Attention: v4.7 of the API has released! See change log. Posts related to COVID-19 are still temporarily permitted for chains.

Package google.bytestream

Index

ByteStream

The Byte Stream API enables a client to read and write a stream of bytes to and from a resource. Resources have names, and these names are supplied in the API calls below to identify the resource that is being read from or written to.

All implementations of the Byte Stream API export the interface defined here:

  • Read(): Reads the contents of a resource.

  • Write(): Writes the contents of a resource. The client can call Write() multiple times with the same resource and can check the status of the write by calling QueryWriteStatus().

The ByteStream API provides no direct way to access/modify any metadata associated with the resource.

The errors returned by the service are in the Google canonical error space.

Write

rpc Write(WriteRequest) returns (WriteResponse)

Write() is used to send the contents of a resource as a sequence of bytes. The bytes are sent in a sequence of request protos of a client-side streaming RPC.

A Write() action is resumable. If there is an error or the connection is broken during the Write(), the client should check the status of the Write() by calling QueryWriteStatus() and continue writing from the returned committed_size. This may be less than the amount of data the client previously sent.

Calling Write() on a resource name that was previously written and finalized could cause an error, depending on whether the underlying service allows over-writing of previously written resources.

When the client closes the request channel, the service will respond with a WriteResponse. The service will not view the resource as complete until the client has sent a WriteRequest with finish_write set to true. Sending any requests on a stream after sending a request with finish_write set to true will cause an error. The client should check the WriteResponse it receives to determine how much data the service was able to commit and whether the service views the resource as complete or not.

Authorization Scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/plus.business.manage
  • https://www.googleapis.com/auth/business.manage

For more information, see the OAuth 2.0 Overview.

RestByteStream

UpdateMedia

rpc UpdateMedia(UpdateMediaRequest) returns (Media)

Uploads media. Upload is supported on the URI /upload/v1/media/{+name}.

Authorization Scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/plus.business.manage
  • https://www.googleapis.com/auth/business.manage

For more information, see the OAuth 2.0 Overview.

Media

Media resource.

Fields
resource_name

string

Name of the media resource.

UpdateMediaRequest

Request message for uploading media.

Fields
resource_name

string

Name of the media that is being downloaded. See ReadRequest.resource_name.

media

Media

Representation of the media that is being uploaded.

WriteRequest

Request object for ByteStream.Write.

Fields
resource_name

string

The name of the resource to write. This must be set on the first WriteRequest of each Write() action. If it is set on subsequent calls, it must match the value of the first request.

write_offset

int64

The offset from the beginning of the resource at which the data should be written. It is required on all WriteRequests.

In the first WriteRequest of a Write() action, it indicates the initial offset for the Write() call. The value must be equal to the committed_size that a call to QueryWriteStatus() would return.

On subsequent calls, this value must be set and must be equal to the sum of the first write_offset and the sizes of all data bundles sent previously on this stream.

An incorrect value will cause an error.

finish_write

bool

If true, this indicates that the write is complete. Sending any WriteRequests subsequent to one in which finish_write is true will cause an error.

data

bytes

A portion of the data for the resource. The client may leave data empty for any given WriteRequest. This enables the client to inform the service that the request is still live while it is running an operation to generate more data.

WriteResponse

Response object for ByteStream.Write.

Fields
committed_size

int64

The number of bytes that have been processed for the given resource.