Uploads object contents to Google Cloud Storage.
Two strategies:
- Simple (
put_object/4) — a single request for in-memory data. - Resumable (
upload_file/4,upload_stream/4) — initiates a resumable session then streams the body, using constant memory. Best for large objects and for data produced incrementally.
Low-level resumable primitives (start_resumable_upload/3, upload_chunk/3)
are provided for callers that need manual control over chunking and retries.
Successful uploads return the decoded Object resource.
Exposed through the top-level GcpGcs module.
Summary
Functions
Uploads in-memory data in a single request (simple upload).
Initiates a resumable upload session and returns its session URI.
Uploads from a source, choosing a strategy automatically
Uploads a single chunk to a resumable session_uri.
Uploads a local file using a resumable session, streaming it in one request with constant memory.
Uploads from an Enumerable of binaries using a resumable session.
Functions
@spec put_object(String.t(), String.t(), binary(), keyword()) :: {:ok, map()} | {:error, GcpGcs.Error.t()}
Uploads in-memory data in a single request (simple upload).
Options
:content_type— defaults to"application/octet-stream":predefined_acl— e.g."publicRead":timeout— request timeout in ms
@spec start_resumable_upload(String.t(), String.t(), keyword()) :: {:ok, String.t()} | {:error, GcpGcs.Error.t()}
Initiates a resumable upload session and returns its session URI.
Options
:content_type— value sent asX-Upload-Content-Type:attrs— Object resource metadata (sent as the JSON request body):timeout— request timeout in ms
@spec upload( String.t(), String.t(), binary() | {:file, Path.t()} | Enumerable.t(), keyword() ) :: {:ok, map()} | {:error, GcpGcs.Error.t()}
Uploads from a source, choosing a strategy automatically:
- a binary → simple upload (
put_object/4) {:file, path}→ resumable streamed upload (upload_file/4)- an
Enumerableof binaries → resumable streamed upload (upload_stream/4)
@spec upload_chunk(String.t(), binary(), keyword()) :: {:ok, map()} | {:resume, non_neg_integer()} | {:error, GcpGcs.Error.t()}
Uploads a single chunk to a resumable session_uri.
Options (required: :offset)
:offset— byte offset of this chunk within the object:total— total object size if known, ornil/omitted for the streaming case (intermediate chunks send/*):timeout— request timeout in ms
Returns
{:resume, next_offset}— chunk stored, more expected (HTTP 308){:ok, object}— upload complete (HTTP 200/201){:error, %GcpGcs.Error{}}
@spec upload_file(String.t(), String.t(), Path.t(), keyword()) :: {:ok, map()} | {:error, GcpGcs.Error.t()}
Uploads a local file using a resumable session, streaming it in one request with constant memory.
Content type defaults to a guess from the object's extension.
Options
:content_type— overrides the guessed content type:chunk_size— read size in bytes (rounded to a 256 KiB multiple):attrs— Object resource metadata to set on the new object:timeout— request timeout in ms
@spec upload_stream(String.t(), String.t(), Enumerable.t(), keyword()) :: {:ok, map()} | {:error, GcpGcs.Error.t()}
Uploads from an Enumerable of binaries using a resumable session.
The data is rebuffered into 256 KiB-aligned chunks and sent incrementally, so the total size need not be known up front and memory stays bounded.
Options
:content_type— defaults to"application/octet-stream":chunk_size— chunk size in bytes (rounded to a 256 KiB multiple):attrs— Object resource metadata to set on the new object:timeout— per-request timeout in ms