Java idiomatic client for Cloud Storage.

• Product Documentation
• Client Library Documentation

If you are using Maven with BOM, add this to your pom.xml file:

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.google.cloud</groupId>
      <artifactId>libraries-bom</artifactId>
      <version>26.62.0</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

<dependencies>
  <dependency>
    <groupId>com.google.cloud</groupId>
    <artifactId>google-cloud-storage</artifactId>
  </dependency>
  <dependency>
    <groupId>com.google.cloud</groupId>
    <artifactId>google-cloud-storage-control</artifactId>
  </dependency>
</dependencies>

If you are using Maven without the BOM, add this to your dependencies:

<dependency>
  <groupId>com.google.cloud</groupId>
  <artifactId>google-cloud-storage</artifactId>
  <version>2.53.1</version>
</dependency>
<dependency>
  <groupId>com.google.cloud</groupId>
  <artifactId>google-cloud-storage-control</artifactId>
  <version>2.53.1</version>
</dependency>

If you are using Gradle 5.x or later, add this to your dependencies:

implementation platform('com.google.cloud:libraries-bom:26.61.0')

implementation 'com.google.cloud:google-cloud-storage'

If you are using Gradle without BOM, add this to your dependencies:

implementation 'com.google.cloud:google-cloud-storage:2.53.2'

If you are using SBT, add this to your dependencies:

libraryDependencies += "com.google.cloud" % "google-cloud-storage" % "2.53.2"

See the Authentication section in the base directory's README.

The client application making API calls must be granted authorization scopes required for the desired Cloud Storage APIs, and the authenticated principal must have the IAM role(s) required to access GCP resources using the Cloud Storage API calls.

You will need a Google Cloud Platform Console project with the Cloud Storage API enabled. You will need to enable billing to use Google Cloud Storage. Follow these instructions to get your project set up. You will also need to set up the local development environment by installing the Google Cloud Command Line Interface and running the following commands in command line: gcloud auth login and gcloud config set project [YOUR PROJECT ID].

You'll need to obtain the google-cloud-storage library. See the Quickstart section to add google-cloud-storage as a dependency in your code.

Cloud Storage is a durable and highly available object storage service. Google Cloud Storage is almost infinitely scalable and guarantees consistency: when a write succeeds, the latest copy of the object will be returned to any GET, globally.

See the Cloud Storage client library docs to learn how to use this Cloud Storage Client Library.

The Storage Control API lets you perform metadata-specific, control plane, and long-running operations.

The Storage Control API creates one space to perform metadata-specific, control plane, and long-running operations apart from the Storage API. Separating these operations from the Storage API improves API standardization and lets you run faster releases.

If you are using Maven with BOM, add this to your pom.xml file:

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.google.cloud</groupId>
            <artifactId>libraries-bom</artifactId>
            <version>26.44.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<dependencies>
    <dependency>
        <groupId>com.google.cloud</groupId>
        <artifactId>google-cloud-storage-control</artifactId>
    </dependency>
</dependencies>

If you are using Maven without the BOM, add this to your dependencies:

<dependency>
    <groupId>com.google.cloud</groupId>
    <artifactId>google-cloud-storage-control</artifactId>
    <version>2.41.0</version>
</dependency>

If you are using Gradle 5.x or later, add this to your dependencies:

implementation platform('com.google.cloud:libraries-bom:26.44.0')
implementation 'com.google.cloud:google-cloud-storage-control'

If you are using Gradle without BOM, add this to your dependencies:

implementation 'com.google.cloud:google-cloud-storage-control:2.41.0'

To make authenticated requests to Google Cloud Storage, you must create a service object with credentials. You can then make API calls by calling methods on the Storage service object. The simplest way to authenticate is to use Application Default Credentials. These credentials are automatically inferred from your environment, so you only need the following code to create your service object:

import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;

Storage storage = StorageOptions.getDefaultInstance().getService();

For other authentication options, see the Authentication page in Google Cloud Java.

Stored objects are called "blobs" in google-cloud and are organized into containers called "buckets". Blob, a subclass of BlobInfo, adds a layer of service-related functionality over BlobInfo. Similarly, Bucket adds a layer of service-related functionality over BucketInfo. In this code snippet, we will create a new bucket and upload a blob to that bucket.

Add the following imports at the top of your file:

import static java.nio.charset.StandardCharsets.UTF_8;

import com.google.cloud.storage.Blob;
import com.google.cloud.storage.Bucket;
import com.google.cloud.storage.BucketInfo;

Then add the following code to create a bucket and upload a simple blob.

Important: Bucket names have to be globally unique (among all users of Cloud Storage). If you choose a bucket name that already exists, you'll get a helpful error message telling you to choose another name. In the code below, replace "my_unique_bucket" with a unique bucket name. See more about naming rules here.

// Create a bucket
String bucketName = "my_unique_bucket"; // Change this to something unique
Bucket bucket = storage.create(BucketInfo.of(bucketName));

// Upload a blob to the newly created bucket
BlobId blobId = BlobId.of(bucketName, "my_blob_name");
BlobInfo blobInfo = BlobInfo.newBuilder(blobId).setContentType("text/plain").build();
Blob blob = storage.create(blobInfo, "a simple blob".getBytes(UTF_8));

A complete example for creating a blob can be found at UploadObject.java.

At this point, you will be able to see your newly created bucket and blob on the Google Developers Console.

Now that we have content uploaded to the server, we can see how to read data from the server. Add the following line to your program to get back the blob we uploaded.

BlobId blobId = BlobId.of(bucketName, "my_blob_name");
byte[] content = storage.readAllBytes(blobId);
String contentString = new String(content, UTF_8);

A complete example for accessing blobs can be found at DownloadObject.java.

Another thing we may want to do is update a blob. The following snippet shows how to update a Storage blob if it exists.

BlobId blobId = BlobId.of(bucketName, "my_blob_name");
Blob blob = storage.get(blobId);
if (blob != null) {
  byte[] prevContent = blob.getContent();
  System.out.println(new String(prevContent, UTF_8));
  WritableByteChannel channel = blob.writer();
  channel.write(ByteBuffer.wrap("Updated content".getBytes(UTF_8)));
  channel.close();
}

Suppose that you've added more buckets and blobs, and now you want to see the names of your buckets and the contents of each one. Add the following code to list all your buckets and all the blobs inside each bucket.

// List all your buckets
System.out.println("My buckets:");
for (Bucket bucket : storage.list().iterateAll()) {
  System.out.println(bucket);

  // List all blobs in the bucket
  System.out.println("Blobs in the bucket:");
  for (Blob blob : bucket.list().iterateAll()) {
    System.out.println(blob);
  }
}

See ListObjects.java for a complete example.

• Bookshelf - An App Engine application that manages a virtual bookshelf.
  • This app uses google-cloud to interface with Cloud Datastore and Cloud Storage. It also uses Cloud SQL, another Google Cloud Platform service.
• Flexible Environment/Storage example - An app that uploads files to a public Cloud Storage bucket on the App Engine Flexible Environment runtime.

Samples are in the samples/ directory.

Sample	Source Code	Try it
Configure Retries	source code
Generate Signed Post Policy V4	source code
Get Service Account	source code
Quickstart Grpc Dp Sample	source code
Quickstart Grpc Sample	source code
Quickstart Open Telemetry Sample	source code
Quickstart Sample	source code
Quickstart Storage Control Sample	source code
Add Bucket Default Owner	source code
Add Bucket Iam Conditional Binding	source code
Add Bucket Iam Member	source code
Add Bucket Label	source code
Add Bucket Owner	source code
Change Default Storage Class	source code
Configure Bucket Cors	source code
Create Bucket	source code
Create Bucket Dual Region	source code
Create Bucket Pub Sub Notification	source code
Create Bucket With Object Retention	source code
Create Bucket With Storage Class And Location	source code
Create Bucket With Turbo Replication	source code
Delete Bucket	source code
Delete Bucket Pub Sub Notification	source code
Disable Bucket Versioning	source code
Disable Default Event Based Hold	source code
Disable Lifecycle Management	source code
Disable Requester Pays	source code
Disable Soft Delete	source code
Disable Uniform Bucket Level Access	source code
Enable Bucket Versioning	source code
Enable Default Event Based Hold	source code
Enable Lifecycle Management	source code
Enable Requester Pays	source code
Enable Uniform Bucket Level Access	source code
Get Bucket Autoclass	source code
Get Bucket Metadata	source code
Get Bucket Rpo	source code
Get Default Event Based Hold	source code
Get Public Access Prevention	source code
Get Requester Pays Status	source code
Get Retention Policy	source code
Get Soft Delete Policy	source code
Get Uniform Bucket Level Access	source code
List Bucket Iam Members	source code
List Buckets	source code
List Pub Sub Notifications	source code
Lock Retention Policy	source code
Make Bucket Public	source code
Print Bucket Acl	source code
Print Bucket Acl Filter By User	source code
Print Pub Sub Notification	source code
Remove Bucket Cors	source code
Remove Bucket Default Kms Key	source code
Remove Bucket Default Owner	source code
Remove Bucket Iam Conditional Binding	source code
Remove Bucket Iam Member	source code
Remove Bucket Label	source code
Remove Bucket Owner	source code
Remove Retention Policy	source code
Set Async Turbo Rpo	source code
Set Bucket Autoclass	source code
Set Bucket Default Kms Key	source code
Set Bucket Website Info	source code
Set Client Endpoint	source code
Set Default Rpo	source code
Set Public Access Prevention Enforced	source code
Set Public Access Prevention Inherited	source code
Set Retention Policy	source code
Set Soft Delete Policy	source code
Anywhere Cache Create	source code
Anywhere Cache Disable	source code
Anywhere Cache Get	source code
Anywhere Cache List	source code
Anywhere Cache Pause	source code
Anywhere Cache Resume	source code
Anywhere Cache Update	source code
Create Folder	source code
Create Hierarchical Namespace Bucket	source code
Delete Folder	source code
Get Folder	source code
List Folders	source code
Rename Folder	source code
Activate Hmac Key	source code
Create Hmac Key	source code
Deactivate Hmac Key	source code
Delete Hmac Key	source code
Get Hmac Key	source code
List Hmac Keys	source code