Google Cloud Storage

Upload, download, and manage files in Google Cloud Storage

Overview

Manages Google Cloud Storage buckets and objects through the Cloud Storage JSON API v1. Bucket operations cover create, delete, get and list; object operations cover create (upload), delete, get, list and update. Getting an object can return either its metadata or the file itself as binary data, and creating an object can upload binary data from an upstream node or plain text. Authentication is available via OAuth2 or a service account.

Category: Data & Storage
Tool Name: google_cloud_storage
Version: 1

Appearance: Icon: si-googlecloud | Color: #4285F4

Node Type

Action (Binary) — handles file/binary data operations

Input / Output

Direction	Port(s)
Input	Input
Output	Output, Error

Credentials

This tool requires Google Cloud Storage OAuth2 credentials. See the Credentials Guide for setup instructions.

Resources

Resource	Value
Bucket	bucket
Object	object

Operations

Both resources offer the same five operation values; the Resource selector decides what they act on.

Operation	Value	Description
Create	create	Create a new bucket
Delete	delete	Delete an empty bucket
Get	get	Get metadata for a specific bucket
Get Many	getAll	List buckets for a project
Update	update	Update a bucket’s metadata
Create	create	Upload an object to a bucket
Delete	delete	Delete an object from a bucket
Get	get	Get object data or metadata
Get Many	getAll	List objects in a bucket
Update	update	Update an object’s metadata

Parameters

Bucket: Create

Parameter	Type	Required	Default	Description
Project ID	string	Yes	—	Google Cloud project ID. Supports expressions.
Bucket Name	string	Yes	—	Name of the GCS bucket. Supports expressions.
Projection (projection)	options	No	noAcl	Controls the detail level of the response. “No ACL” omits ACL data and allows larger page sizes.
				Options: full (all properties), noAcl
Predefined Access Control	collection	No	{}	Predefined access control settings.
— Predefined ACL	options	No	authenticatedRead	Predefined access control list applied to the bucket.
				Options: authenticatedRead, private, projectPrivate, publicRead, publicReadWrite
— Predefined Default Object ACL	options	No	authenticatedRead	Predefined access control list applied to objects added to the bucket.
				Options: authenticatedRead, bucketOwnerFullControl, bucketOwnerRead, private, projectPrivate, publicRead
Additional Parameters (createBody)	collection	No	{}	Additional bucket metadata parameters.
— Access Control	json	No	[]	Access controls on the bucket (JSON array).
— Billing	json	No	{}	The bucket’s billing configuration (JSON object).
— CORS	json	No	[]	The bucket’s CORS configuration (JSON array).
— Custom Placement Config	json	No	{}	Region placement configuration (JSON object).
— Data Locations	json	No	[]	Dual-region data locations (JSON array).
— Default Event Based Hold	boolean	No	true	Auto-apply event-based hold to new objects.
— Default Object ACL	json	No	[]	Default ACL for new objects (JSON array).
— Encryption	json	No	{}	Encryption configuration (JSON object).
— IAM Configuration	json	No	{}	The bucket’s IAM configuration (JSON object).
— Labels	json	No	{}	Key-value labels (JSON object).
— Lifecycle	json	No	{}	The bucket’s lifecycle configuration (JSON object).
— Location	string	No	US	Geographic location of the bucket.
— Logging	json	No	{}	The bucket’s logging configuration (JSON object).
— Retention Policy	json	No	{}	The bucket’s retention policy (JSON object).
— Recovery Point Objective	string	No	DEFAULT	Recovery point objective.
— Storage Class	string	No	STANDARD	The bucket’s default storage class.
— Versioning	json	No	{}	The bucket’s versioning configuration (JSON object).
— Website	json	No	{}	The bucket’s website hosting configuration (JSON object).

Bucket: Delete

Parameter	Type	Required	Default	Description
Bucket Name	string	Yes	—	Name of the GCS bucket. Supports expressions.
Filters	collection	No	{}	Conditional filters for the operation.
— Metageneration Match	number	No	-1	Only return data if the metageneration value matches this value.
— Metageneration Exclude	number	No	-1	Only return data if the metageneration value does NOT match this value.

Bucket: Get

Parameter	Type	Required	Default	Description
Bucket Name	string	Yes	—	Name of the GCS bucket. Supports expressions.
Projection (projection)	options	No	noAcl	Controls the detail level of the response. “No ACL” omits ACL data and allows larger page sizes.
				Options: full (all properties), noAcl
Filters	collection	No	{}	Conditional filters for the operation.
— Metageneration Match	number	No	-1	Only return data if the metageneration value matches this value.
— Metageneration Exclude	number	No	-1	Only return data if the metageneration value does NOT match this value.

Bucket: Get Many

Parameter	Type	Required	Default	Description
Project ID	string	Yes	—	Google Cloud project ID. Supports expressions.
Prefix	string	No	—	Filter bucket names by prefix.
Projection (projection)	options	No	noAcl	Controls the detail level of the response. “No ACL” omits ACL data and allows larger page sizes.
				Options: full (all properties), noAcl
Return All	boolean	No	false	Whether to return all results or only the first page.

Bucket: Update

Parameter	Type	Required	Default	Description
Bucket Name	string	Yes	—	Name of the GCS bucket. Supports expressions.
Projection (projection)	options	No	noAcl	Controls the detail level of the response. “No ACL” omits ACL data and allows larger page sizes.
				Options: full (all properties), noAcl
Filters	collection	No	{}	Conditional filters for the operation.
— Metageneration Match	number	No	-1	Only return data if the metageneration value matches this value.
— Metageneration Exclude	number	No	-1	Only return data if the metageneration value does NOT match this value.
Predefined Access Control	collection	No	{}	Predefined access control settings.
— Predefined ACL	options	No	authenticatedRead	Predefined access control list applied to the bucket.
				Options: authenticatedRead, private, projectPrivate, publicRead, publicReadWrite
— Predefined Default Object ACL	options	No	authenticatedRead	Predefined access control list applied to objects added to the bucket.
				Options: authenticatedRead, bucketOwnerFullControl, bucketOwnerRead, private, projectPrivate, publicRead
Additional Parameters (createBody)	collection	No	{}	Additional bucket metadata parameters.
— Access Control	json	No	[]	Access controls on the bucket (JSON array).
— Billing	json	No	{}	The bucket’s billing configuration (JSON object).
— CORS	json	No	[]	The bucket’s CORS configuration (JSON array).
— Custom Placement Config	json	No	{}	Region placement configuration (JSON object).
— Data Locations	json	No	[]	Dual-region data locations (JSON array).
— Default Event Based Hold	boolean	No	true	Auto-apply event-based hold to new objects.
— Default Object ACL	json	No	[]	Default ACL for new objects (JSON array).
— Encryption	json	No	{}	Encryption configuration (JSON object).
— IAM Configuration	json	No	{}	The bucket’s IAM configuration (JSON object).
— Labels	json	No	{}	Key-value labels (JSON object).
— Lifecycle	json	No	{}	The bucket’s lifecycle configuration (JSON object).
— Location	string	No	US	Geographic location of the bucket.
— Logging	json	No	{}	The bucket’s logging configuration (JSON object).
— Retention Policy	json	No	{}	The bucket’s retention policy (JSON object).
— Recovery Point Objective	string	No	DEFAULT	Recovery point objective.
— Storage Class	string	No	STANDARD	The bucket’s default storage class.
— Versioning	json	No	{}	The bucket’s versioning configuration (JSON object).
— Website	json	No	{}	The bucket’s website hosting configuration (JSON object).

Object: Create

Parameter	Type	Required	Default	Description
Bucket Name	string	Yes	—	Name of the GCS bucket. Supports expressions.
Object Name	string	Yes	—	Name/path of the object in the bucket. Supports expressions.
Projection (updateProjection)	options	No	full	Controls the detail level of the response.
				Options: full (all properties), noAcl
Use Input Binary Field	boolean	No	true	Whether to upload data from a binary input field or from text content.
Input Binary Field	string	No	data	Name of the binary property containing the file to upload. (shown when Use Input Binary Field is true)
File Content	string	No	—	Text content to upload as the object. Supports expressions. (shown when Use Input Binary Field is false)
Create Fields	collection	No	{}	Metadata fields for the created object.
— Access Control List	json	No	[]	Sets the object’s acl metadata.
— Cache Control	string	No	—	Sets the object’s cacheControl metadata.
— Content Disposition	string	No	—	Sets the object’s contentDisposition metadata.
— Content Encoding	string	No	—	Sets the object’s contentEncoding metadata.
— Content Language	string	No	—	Sets the object’s contentLanguage metadata.
— Content Type	string	No	—	Sets the object’s contentType metadata.
— CRC32c Checksum	string	No	—	Sets the object’s crc32c checksum metadata.
— Custom Time	string	No	—	Sets the object’s customTime metadata.
— Event Based Hold	boolean	No	false	Sets the object’s eventBasedHold flag.
— MD5 Hash	string	No	—	Sets the object’s md5Hash metadata.
— Metadata	json	No	{}	Sets the object’s custom metadata key-value pairs.
— Storage Class	string	No	—	Sets the object’s storageClass.
— Temporary Hold	boolean	No	false	Sets the object’s temporaryHold flag.
Additional Parameters (createQuery)	collection	No	{}	Additional query parameters for object creation.
— Content Encoding	string	No	—	Content encoding sent with the upload request.
— Generation	number	No	-1	Select a specific revision.
— Generation Match	number	No	-1	Conditional on generation match.
— Generation Exclude	number	No	-1	Conditional on generation mismatch.
— Metageneration Match	number	No	-1	Conditional on metageneration match.
— Metageneration Exclude	number	No	-1	Conditional on metageneration mismatch.
— KMS Key Name	string	No	—	Cloud KMS key for encryption.
— Predefined ACL	options	No	authenticatedRead	Predefined access control list applied to the new object.
				Options: authenticatedRead, bucketOwnerFullControl, bucketOwnerRead, private, projectPrivate, publicRead
Encryption Headers	collection	No	{}	Customer-supplied encryption key headers.
— Encryption Algorithm	options	No	AES256	The customer-supplied encryption algorithm.
				Options: AES256
— Encryption Key	string	No	—	Base64-encoded AES256 encryption key.
— Encryption Key Hash	string	No	—	Base64-encoded SHA256 hash of the encryption key.

Object: Delete

Parameter	Type	Required	Default	Description
Bucket Name	string	Yes	—	Name of the GCS bucket. Supports expressions.
Object Name	string	Yes	—	Name/path of the object in the bucket. Supports expressions.
Additional Parameters (getParameters)	collection	No	{}	Additional parameters for get/delete operations.
— Generation	number	No	-1	Target a specific object revision.
— Generation Match	number	No	-1	Conditional on generation match.
— Generation Exclude	number	No	-1	Conditional on generation mismatch.
— Metageneration Match	number	No	-1	Conditional on metageneration match.
— Metageneration Exclude	number	No	-1	Conditional on metageneration mismatch.

Object: Get

Parameter	Type	Required	Default	Description
Bucket Name	string	Yes	—	Name of the GCS bucket. Supports expressions.
Object Name	string	Yes	—	Name/path of the object in the bucket. Supports expressions.
Projection (projection)	options	No	noAcl	Controls the detail level of the response.
				Options: full (all properties), noAcl
Return Data	options	No	json	Whether to return object metadata (JSON) or download the file (binary).
				Options: json (metadata), media (object data)
Put Output File in Field	string	No	data	Name of the binary property to write the downloaded file to. Names are case-sensitive — see the upstream node’s Binary Data panel for the exact names to use. (shown when Return Data is media)
Additional Parameters (getParameters)	collection	No	{}	Additional parameters for get/delete operations.
— Generation	number	No	-1	Target a specific object revision.
— Generation Match	number	No	-1	Conditional on generation match.
— Generation Exclude	number	No	-1	Conditional on generation mismatch.
— Metageneration Match	number	No	-1	Conditional on metageneration match.
— Metageneration Exclude	number	No	-1	Conditional on metageneration mismatch.
Encryption Headers	collection	No	{}	Customer-supplied encryption key headers.
— Encryption Algorithm	options	No	AES256	The customer-supplied encryption algorithm.
				Options: AES256
— Encryption Key	string	No	—	Base64-encoded AES256 encryption key.
— Encryption Key Hash	string	No	—	Base64-encoded SHA256 hash of the encryption key.

Object: Get Many

Parameter	Type	Required	Default	Description
Bucket Name	string	Yes	—	Name of the GCS bucket. Supports expressions.
Projection (projection)	options	No	noAcl	Controls the detail level of the response.
				Options: full (all properties), noAcl
Return All	boolean	No	false	Whether to return all results or only up to a given limit.
Limit	number	No	100	Maximum number of results to return. (shown when Return All is false)
Additional Parameters (listFilters)	collection	No	{}	Additional filters for listing objects.
— Delimiter	string	No	/	Directory-like delimiter for results.
— End Offset	string	No	—	Filter results to names lexicographically before this value.
— Include Trailing Delimiter	boolean	No	false	Include trailing delimiter in object names.
— Prefix	string	No	—	Filter results to names starting with this prefix.
— Start Offset	string	No	—	Filter results to names lexicographically equal to or after this value.
— Versions	boolean	No	false	List all object versions as distinct entries.

Object: Update

Parameter	Type	Required	Default	Description
Bucket Name	string	Yes	—	Name of the GCS bucket. Supports expressions.
Object Name	string	Yes	—	Name/path of the object in the bucket. Supports expressions.
Projection (updateProjection)	options	No	full	Controls the detail level of the response.
				Options: full (all properties), noAcl
Update Fields	collection	No	{}	Metadata fields to update on the object.
— Access Control	json	No	[]	Sets the object’s acl metadata.
— Cache Control	string	No	—	Sets the object’s cacheControl metadata.
— Content Disposition	string	No	—	Sets the object’s contentDisposition metadata.
— Content Encoding	string	No	—	Sets the object’s contentEncoding metadata.
— Content Language	string	No	—	Sets the object’s contentLanguage metadata.
— Content Type	string	No	—	Sets the object’s contentType metadata.
— Custom Time	string	No	—	Sets the object’s customTime metadata.
— Event Based Hold	boolean	No	false	Sets the object’s eventBasedHold flag.
— Metadata	json	No	{}	Sets the object’s custom metadata key-value pairs.
— Temporary Hold	boolean	No	false	Sets the object’s temporaryHold flag.
Additional Parameters (metagenAndAclQuery)	collection	No	{}	Additional query parameters for object update.
— Generation	number	No	-1	Target a specific object revision.
— Generation Match	number	No	-1	Conditional on generation match.
— Generation Exclude	number	No	-1	Conditional on generation mismatch.
— Metageneration Match	number	No	-1	Conditional on metageneration match.
— Metageneration Exclude	number	No	-1	Conditional on metageneration mismatch.
— Predefined ACL	options	No	authenticatedRead	Predefined access control list applied to the object.
				Options: authenticatedRead, bucketOwnerFullControl, bucketOwnerRead, private, projectPrivate, publicRead
Encryption Headers	collection	No	{}	Customer-supplied encryption key headers.
— Encryption Algorithm	options	No	AES256	The customer-supplied encryption algorithm.
				Options: AES256
— Encryption Key	string	No	—	Base64-encoded AES256 encryption key.
— Encryption Key Hash	string	No	—	Base64-encoded SHA256 hash of the encryption key.

All Operations

Parameter	Type	Required	Default	Description
Authentication	options	No	oAuth2	Authentication method to use.
				Options: oAuth2, serviceAccount
Google Account	credential	No	—	Connect or select your Google account. (shown when Authentication is oAuth2)
Service Account Email	string	Yes	—	The email address of the Google service account. (shown when Authentication is serviceAccount)
Private Key	string	Yes	—	The private key from the service account JSON key file. (shown when Authentication is serviceAccount)
Max Concurrency	number	No	10	Maximum number of items to process concurrently.

Output Data

Results are merged into the input item’s JSON, so the incoming fields stay available downstream, and binary data on the input item is forwarded. The one exception is a binary download, which replaces the JSON entirely.

Operation	Output
bucket / create, get, update	One item carrying the bucket resource (kind, id, name, location, storageClass, timeCreated, updated …).
bucket / delete	One item carrying success: true and deleted — the bucket name.
bucket / getAll	One item per bucket. When none match, one item carrying an empty items array.
object / create, update	One item carrying the object resource (kind, id, name, bucket, size, contentType, generation, md5Hash …).
object / delete	One item carrying success: true, deleted — the object name — and bucket.
object / get with Return Data json	One item carrying the object’s metadata.
object / get with Return Data media	One item whose JSON is empty; the file is written to the binary property you named, alongside any binary already on the item.
object / getAll	One item per object. When none match, one item carrying an empty items array.

An object metadata result looks like this:

{
  "kind": "storage#object",
  "id": "my-bucket/documents/file.txt/1712345678901234",
  "name": "documents/file.txt",
  "bucket": "my-bucket",
  "generation": "1712345678901234",
  "contentType": "text/plain",
  "size": "13",
  "updated": "2024-04-05T18:14:38.901Z"
}

Chain operations by expression — for example feed {{ $json.name }} from a list into a download.

Usage Examples

• Download a file from a GCS bucket as binary data
• Upload a binary file to Google Cloud Storage
• List all objects in a GCS bucket
• Create a new GCS bucket for a project
• Delete an object from Google Cloud Storage
• Get metadata for a specific GCS object
• Update object metadata in a GCS bucket

Example Configuration

Create a versioned bucket:

{
  "type": "google_cloud_storage",
  "parameters": {
    "resource": "bucket",
    "operation": "create",
    "projectId": "my-gcp-project",
    "bucketName": "my-new-bucket",
    "projection": "full",
    "createBody": {
      "location": "US",
      "storageClass": "STANDARD",
      "versioning": "{\"enabled\": true}"
    },
    "createAcl": {
      "predefinedAcl": "private"
    }
  }
}

List every bucket in a project whose name starts with a prefix:

{
  "type": "google_cloud_storage",
  "parameters": {
    "resource": "bucket",
    "operation": "getAll",
    "projectId": "my-gcp-project",
    "prefix": "prod-",
    "returnAll": true,
    "projection": "noAcl"
  }
}

Upload text as an object:

{
  "type": "google_cloud_storage",
  "parameters": {
    "resource": "object",
    "operation": "create",
    "bucketName": "my-bucket",
    "objectName": "documents/{{ $json.slug }}.txt",
    "createFromBinary": false,
    "createContent": "{{ $json.body }}",
    "updateProjection": "full",
    "createData": {
      "contentType": "text/plain",
      "cacheControl": "max-age=3600",
      "metadata": "{\"source\": \"workflow\"}"
    },
    "createQuery": {
      "predefinedAcl": "publicRead"
    }
  }
}

Upload binary data coming from an upstream node:

{
  "type": "google_cloud_storage",
  "parameters": {
    "resource": "object",
    "operation": "create",
    "bucketName": "my-bucket",
    "objectName": "images/{{ $json.fileName }}",
    "createFromBinary": true,
    "createBinaryPropertyName": "data",
    "updateProjection": "noAcl",
    "createData": {
      "contentType": "image/jpeg",
      "storageClass": "STANDARD"
    }
  }
}

Download an object into a binary property:

{
  "type": "google_cloud_storage",
  "parameters": {
    "resource": "object",
    "operation": "get",
    "bucketName": "my-bucket",
    "objectName": "{{ $json.name }}",
    "alt": "media",
    "binaryPropertyName": "downloadedFile"
  }
}

Read an object’s metadata without downloading it:

{
  "type": "google_cloud_storage",
  "parameters": {
    "resource": "object",
    "operation": "get",
    "bucketName": "my-bucket",
    "objectName": "documents/file.txt",
    "alt": "json",
    "projection": "full"
  }
}

List objects under a prefix:

{
  "type": "google_cloud_storage",
  "parameters": {
    "resource": "object",
    "operation": "getAll",
    "bucketName": "my-bucket",
    "projection": "noAcl",
    "returnAll": false,
    "maxResults": 100,
    "listFilters": {
      "prefix": "documents/",
      "delimiter": "/",
      "versions": false
    }
  }
}

Update an object’s metadata:

{
  "type": "google_cloud_storage",
  "parameters": {
    "resource": "object",
    "operation": "update",
    "bucketName": "my-bucket",
    "objectName": "documents/file.txt",
    "updateProjection": "full",
    "updateData": {
      "contentType": "text/markdown",
      "cacheControl": "no-cache",
      "metadata": "{\"version\": \"2.0\"}"
    },
    "metagenAndAclQuery": {
      "ifMetagenerationMatch": 2,
      "predefinedAcl": "bucketOwnerRead"
    }
  }
}

Delete a specific object revision:

{
  "type": "google_cloud_storage",
  "parameters": {
    "resource": "object",
    "operation": "delete",
    "bucketName": "my-bucket",
    "objectName": "documents/old-file.txt",
    "getParameters": {
      "generation": 9876543210
    }
  }
}

Error Handling

Mode	Behavior
stop	Halts workflow on first error
continue	Skips failed items, passes successful ones through
errorPort	Routes failed items to Error output port

Tips

Manage Google Cloud Storage buckets and objects — upload, download, list, and delete files in GCS.

• Project ID is only needed for bucket Create and Get Many. Every other operation addresses the bucket by name.
• Return Data decides what a Get produces. json gives you metadata on the item’s JSON; media downloads the file into a binary property and leaves the JSON empty, so capture anything you need from the item before this node.
• Object names carry their path. documents/2024/report.pdf is a single object name, not a folder structure — the Delimiter and Prefix filters on Get Many are what make listings look folder-like.
• Delete only works on empty buckets. Remove the objects first.
• Numeric conditional filters default to -1, meaning “unset”. Leave Generation and the metageneration filters alone unless you are guarding against concurrent writes.
• Customer-supplied encryption keys must be repeated on read. An object uploaded with Encryption Headers can only be downloaded or updated by supplying the same key and hash.
• Get Many fans out — each bucket or object becomes its own item, so downstream nodes process them individually.