A client for Cloud Storage - Unified object storage.
Here's a simple usage example the Java Storage client. This example shows how to create a Storage object.
Storage storage = StorageOptions.getDefaultInstance().getService();
BlobId blobId = BlobId.of("bucket", "blob_name");
BlobInfo blobInfo = BlobInfo.newBuilder(blobId).setContentType("text/plain").build();
Blob blob = storage.create(blobInfo, "Hello, Cloud Storage!".getBytes(UTF_8));
This second example shows how to update an object's content if the object exists.
Storage storage = StorageOptions.getDefaultInstance().getService();
BlobId blobId = BlobId.of("bucket", "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();
}
For more detailed code examples, see the sample library.
When using google-cloud from outside of App/Compute Engine, you have to specify a project ID and provide credentials.
Operations in this library are generally thread safe, except for the use of BlobReadChannel and BlobWriteChannel. See Also: Google Cloud Storage
Classes
Acl
Access Control List for buckets or blobs. See Also: About Access Control Lists
Acl.Builder
Builder for Acl
objects.
Acl.Domain
Class for ACL Domain entities.
Acl.Entity
Base class for Access Control List entities.
Acl.Group
Class for ACL Group entities.
Acl.Project
Class for ACL Project entities.
Acl.Project.ProjectRole
Acl.RawEntity
Acl.Role
Acl.User
Class for ACL User entities.
Blob
An object in Google Cloud Storage. A Blob
object includes the BlobId
instance,
the set of properties inherited from the BlobInfo class and the Storage
instance.
The class provides methods to perform operations on the object. Reading a property value does not
issue any RPC calls. The object content is not stored within the Blob
instance.
Operations that access the content issue one or multiple RPC calls, depending on the content
size.
Objects of this class are immutable. Operations that modify the blob like #update and
#copyTo return a new object. Any changes to the object in Google Cloud Storage made after
creation of the Blob
are not visible in the Blob
. To get a Blob
object
with the most recent information use #reload.
Example of getting the content of the object in Google Cloud Storage:
BlobId blobId = BlobId.of(bucketName, blobName);
Blob blob = storage.get(blobId);
long size = blob.getSize(); // no RPC call is required
byte[] content = blob.getContent(); // one or multiple RPC calls will be issued
Blob.BlobSourceOption
Class for specifying blob source options when Blob
methods are used.
Blob.Builder
Builder for Blob
.
BlobId
Google Storage Object identifier. A BlobId
object includes the name of the containing
bucket, the blob's name and possibly the blob's generation. If #getGeneration() is
null
the identifier refers to the latest blob's generation.
BlobInfo
Information about an object in Google Cloud Storage. A BlobInfo
object includes the
BlobId
instance and the set of properties, such as the blob's access control
configuration, user provided metadata, the CRC32C checksum, etc. Instances of this class are used
to create a new object in Google Cloud Storage or update the properties of an existing object. To
deal with existing Storage objects the API includes the Blob class which extends
BlobInfo
and declares methods to perform operations on the object. Neither BlobInfo
nor
Blob
instances keep the object content, just the object properties.
Example of usage BlobInfo
to create an object in Google Cloud Storage:
BlobId blobId = BlobId.of(bucketName, blobName);
BlobInfo blobInfo = BlobInfo.newBuilder(blobId).setContentType("text/plain").build();
Blob blob = storage.create(blobInfo, "Hello, world".getBytes(StandardCharsets.UTF_8));
See Also: Concepts and Terminology
BlobInfo.Builder
Builder for BlobInfo
.
BlobInfo.CustomerEncryption
Objects of this class hold information on the customer-supplied encryption key, if the blob is encrypted using such a key.
BlobInfo.ImmutableEmptyMap<K,V>
This class is meant for internal use only. Users are discouraged from using this class.
Bucket
A Google cloud storage bucket.
Objects of this class are immutable. Operations that modify the bucket like #update
return a new object. To get a Bucket
object with the most recent information use #reload. Bucket
adds a layer of service-related functionality over BucketInfo.
Bucket.BlobTargetOption
Class for specifying blob target options when Bucket
methods are used.
Bucket.BlobWriteOption
Class for specifying blob write options when Bucket
methods are used.
Bucket.BucketSourceOption
Class for specifying bucket source options when Bucket
methods are used.
Bucket.Builder
Builder for Bucket
.
BucketInfo
Google Storage bucket metadata; See Also: Concepts and Terminology
BucketInfo.AgeDeleteRule (deprecated)
Deprecated. Use a LifecycleRule
with a DeleteLifecycleAction
and use
LifecycleCondition.Builder.setAge
instead.
For example, new DeleteLifecycleAction(1)
is equivalent to new
LifecycleRule( LifecycleAction.newDeleteAction(),
LifecycleCondition.newBuilder().setAge(1).build()))
Delete rule class that sets a Time To Live for blobs in the bucket. See Also: Object Lifecycle Management
BucketInfo.Autoclass
BucketInfo.Autoclass.Builder
BucketInfo.Builder
Builder for BucketInfo
.
BucketInfo.CreatedBeforeDeleteRule (deprecated)
Deprecated. Use a LifecycleRule
with an action DeleteLifecycleAction
and a
condition LifecycleCondition.Builder.setCreatedBefore
instead.
Delete rule class for blobs in the bucket that have been created before a certain date. See Also: Object Lifecycle Management
BucketInfo.CustomPlacementConfig
The bucket's custom placement configuration for Custom Dual Regions. If using location
is
also required.
BucketInfo.CustomPlacementConfig.Builder
BucketInfo.DeleteRule (deprecated)
Deprecated. Use a LifecycleRule
with a DeleteLifecycleAction
and a
LifecycleCondition
which is equivalent to a subclass of DeleteRule instead.
Base class for bucket's delete rules. Allows to configure automatic deletion of blobs and blobs versions. See Also: Object Lifecycle Management
BucketInfo.IamConfiguration
The Bucket's IAM Configuration. See Also: public-access-prevention, uniform bucket-level access
BucketInfo.IamConfiguration.Builder
Builder for IamConfiguration
BucketInfo.IsLiveDeleteRule (deprecated)
Deprecated. Use a LifecycleRule
with a DeleteLifecycleAction
and a condition
LifecycleCondition.Builder.setIsLive
instead.
Delete rule class to distinguish between live and archived blobs. See Also: Object Lifecycle Management
BucketInfo.LifecycleRule
Lifecycle rule for a bucket. Allows supported Actions, such as deleting and changing storage class, to be executed when certain Conditions are met.
Versions 1.50.0-1.111.2 of this library don’t support the CustomTimeBefore, DaysSinceCustomTime, DaysSinceNoncurrentTime and NoncurrentTimeBefore lifecycle conditions. To read GCS objects with those lifecycle conditions, update your Java client library to the latest version. See Also: Object Lifecycle Management
BucketInfo.LifecycleRule.AbortIncompleteMPUAction
BucketInfo.LifecycleRule.DeleteLifecycleAction
BucketInfo.LifecycleRule.LifecycleAction
Base class for the Action to take when a Lifecycle Condition is met. Supported Actions are expressed as subclasses of this class, accessed by static factory methods.
BucketInfo.LifecycleRule.LifecycleCondition
Condition for a Lifecycle rule, specifies under what criteria an Action should be executed. See Also: Object Lifecycle Management
BucketInfo.LifecycleRule.LifecycleCondition.Builder
Builder for LifecycleCondition
.
BucketInfo.LifecycleRule.SetStorageClassLifecycleAction
BucketInfo.Logging
The bucket's logging configuration, which defines the destination bucket and optional name prefix for the current bucket's logs.
BucketInfo.Logging.Builder
BucketInfo.NumNewerVersionsDeleteRule (deprecated)
Deprecated. Use a LifecycleRule
with a DeleteLifecycleAction
and a condition
LifecycleCondition.Builder.setNumberOfNewerVersions
instead.
Delete rule class for versioned blobs. Specifies when to delete a blob's version according to the number of available newer versions for that blob. See Also: Object Lifecycle Management
CanonicalExtensionHeadersSerializer
Canonical extension header serializer. See Also: Canonical Extension Headers
CopyWriter
Google Storage blob copy writer. A CopyWriter
object allows to copy both blob's data and
information. To override source blob's information supply a BlobInfo
to the
CopyRequest
using either Storage.CopyRequest.Builder#setTarget(BlobInfo,
Storage.BlobTargetOption...) or Storage.CopyRequest.Builder#setTarget(BlobInfo,
Iterable).
This class holds the result of a copy request. If source and destination blobs share the same location and storage class the copy is completed in one RPC call otherwise one or more #copyChunk calls are necessary to complete the copy. In addition, CopyWriter#getResult() can be used to automatically complete the copy and return information on the newly created blob. See Also: Rewrite
Cors
Cross-Origin Resource Sharing (CORS) configuration for a bucket. See Also: Cross-Origin Resource Sharing (CORS)
Cors.Builder
CORS configuration builder.
Cors.Origin
Class for a CORS origin.
GrpcStorageOptions
GrpcStorageOptions.Builder
GrpcStorageOptions.GrpcStorageDefaults
GrpcStorageOptions.GrpcStorageFactory
Internal implementation detail, only public to allow for java.io.Serializable compatibility in com.google.cloud.ServiceOptions.
To access an instance of this class instead use GrpcStorageOptions.defaults().getDefaultServiceFactory(). See Also: GrpcStorageOptions.GrpcStorageDefaults#getDefaultServiceFactory(), GrpcStorageOptions#defaults()
GrpcStorageOptions.GrpcStorageRpcFactory
Internal implementation detail, only public to allow for java.io.Serializable compatibility in com.google.cloud.ServiceOptions.
To access an instance of this class instead use GrpcStorageOptions.defaults().getDefaultRpcFactory(). See Also: GrpcStorageOptions.GrpcStorageDefaults#getDefaultRpcFactory(), GrpcStorageOptions#defaults()
HmacKey
HMAC key for a service account.
HmacKey.Builder
Builder for HmacKey
objects. *
HmacKey.HmacKeyMetadata
The metadata for a service account HMAC key. This class holds all data associated with an HMAC key other than the secret key.
HmacKey.HmacKeyMetadata.Builder
Builder for HmacKeyMetadata
objects. *
HttpCopyWriter
HttpMethod
Http method supported by Storage service.
HttpStorageOptions
HttpStorageOptions.Builder
HttpStorageOptions.HttpStorageDefaults
HttpStorageOptions.HttpStorageFactory
Internal implementation detail, only public to allow for java.io.Serializable.
To access an instance of this class instead use HttpStorageOptions.defaults().getDefaultServiceFactory(). See Also: HttpStorageOptions#defaults(), HttpStorageDefaults#getDefaultServiceFactory()
HttpStorageOptions.HttpStorageRpcFactory
Internal implementation detail, only public to allow for java.io.Serializable.
To access an instance of this class instead use HttpStorageOptions.defaults().getDefaultRpcFactory(). See Also: HttpStorageDefaults#getDefaultRpcFactory(), HttpStorageOptions#defaults()
Notification
The class representing Pub/Sub notifications for the Storage. See pubsub-notifications for details.
Notification.Builder
Builder for Notification
.
NotificationInfo
The class representing Pub/Sub Notification metadata for the Storage.
NotificationInfo.Builder
Builder for NotificationInfo
.
NotificationInfo.BuilderImpl
Builder for NotificationInfo
.
Option<O>
Base class for Storage operation option.
PostPolicyV4
Presigned V4 post policy. Instances of PostPolicyV4
include a URL and a map of fields
that can be specified in an HTML form to submit a POST request to upload an object.
See POST Object for details of upload by using HTML forms.
See Storage#generateSignedPostPolicyV4(BlobInfo, long, TimeUnit, PostPolicyV4.PostFieldsV4, PostPolicyV4.PostConditionsV4, Storage.PostPolicyV4Option...) for example of usage.
PostPolicyV4.ConditionV4
Class for a specific POST policy document condition. See Also: Policy document
PostPolicyV4.PostConditionsV4
A helper class for specifying conditions in a V4 POST Policy document. Used in: Storage#generateSignedPostPolicyV4(BlobInfo, long, TimeUnit, PostPolicyV4.PostFieldsV4, PostPolicyV4.PostConditionsV4, Storage.PostPolicyV4Option...). See Also: Policy document
PostPolicyV4.PostConditionsV4.Builder
PostPolicyV4.PostFieldsV4
A helper class to define fields to be specified in a V4 POST request. Instance of this class
helps to construct PostPolicyV4
objects. Used in: Storage#generateSignedPostPolicyV4(BlobInfo, long, TimeUnit, PostPolicyV4.PostFieldsV4,
PostPolicyV4.PostConditionsV4, Storage.PostPolicyV4Option...).
See Also: POST Object Form fields
PostPolicyV4.PostFieldsV4.Builder
PostPolicyV4.PostPolicyV4Document
Class for a V4 POST Policy document. Used by Storage to construct PostPolicyV4
objects.
See Also: Policy document
Rpo
Enums for the Recovery Point Objective (RPO) of dual-region buckets, which determines how fast data is replicated between regions. See Also: https://cloud.google.com/storage/docs/turbo-replication
ServiceAccount
A service account, with its specified scopes, authorized for this instance. See Also: Authenticating from Google Cloud Storage
SignatureInfo
Signature Info holds payload components of the string that requires signing. See Also: Components
SignatureInfo.Builder
Storage.BlobGetOption
Class for specifying blob get options.
Storage.BlobListOption
Class for specifying blob list options.
Storage.BlobSourceOption
Class for specifying blob source options.
Storage.BlobTargetOption
Class for specifying blob target options.
Storage.BlobWriteOption
Class for specifying blob write options.
Storage.BucketGetOption
Class for specifying bucket get options.
Storage.BucketListOption
Class for specifying bucket list options.
Storage.BucketSourceOption
Class for specifying bucket source options.
Storage.BucketTargetOption
Class for specifying bucket target options.
Storage.ComposeRequest
A class to contain all information needed for a Google Cloud Storage Compose operation. See Also: Compose Operation
Storage.ComposeRequest.Builder
Storage.ComposeRequest.SourceBlob
Class for Compose source blobs.
Storage.CopyRequest
A class to contain all information needed for a Google Cloud Storage Copy operation.
Storage.CopyRequest.Builder
Storage.CreateHmacKeyOption
Class for specifying createHmacKey options
Storage.DeleteHmacKeyOption
Class for specifying deleteHmacKey options
Storage.GetHmacKeyOption
Class for specifying getHmacKey options
Storage.ListHmacKeysOption
Class for specifying listHmacKeys options
Storage.PostPolicyV4Option
Class for specifying Post Policy V4 options. *
Storage.SignUrlOption
Class for specifying signed URL options.
Storage.UpdateHmacKeyOption
Class for specifying updateHmacKey options
StorageBatch
A batch of operations to be submitted to Google Cloud Storage using a single RPC request.
Example of using a batch request to delete, update and get a blob:
StorageBatch batch = storage.batch();
BlobId firstBlob = BlobId.of("bucket", "blob1"));
BlobId secondBlob = BlobId.of("bucket", "blob2"));
batch.delete(firstBlob).notify(new BatchResult.Callback<Boolean, StorageException>() {
public void success(Boolean result) {
// deleted successfully
}
public void error(StorageException exception) {
// delete failed
}
});
batch.update(BlobInfo.builder(secondBlob).contentType("text/plain").build());
StorageBatchResult<Blob> result = batch.get(secondBlob);
batch.submit();
Blob blob = result.get(); // returns get result or throws StorageException
StorageClass
Enums for the storage classes. See https://cloud.google.com/storage/docs/storage-classes for details.
StorageOptions
StorageOptions.Builder
StorageOptions.DefaultStorageFactory (deprecated)
Deprecated. Use HttpStorageFactory
StorageOptions.DefaultStorageRpcFactory (deprecated)
Deprecated. Use HttpStorageRpcFactory
StorageRoles
IAM roles specific to Storage. An overview of the permissions available to Storage and the capabilities they grant can be found in the Google Cloud Storage IAM documentation.
Interfaces
Storage
An interface for Google Cloud Storage. See Also: Google Cloud Storage
StorageFactory
An interface for Storage factories.
StorageRetryStrategy
A factory class which is used to provide access to ResultRetryAlgorithm for idempotent and non-idempotent calls made via Storage. Before Storage performs an operation it will determine if the operation is idempotent and select the appropriate ResultRetryAlgorithm to use for that invocation. See Also: #getDefaultStorageRetryStrategy(), #getUniformStorageRetryStrategy()
Enums
Acl.Entity.Type
BucketInfo.DeleteRule.Type
BucketInfo.PublicAccessPrevention
Public Access Prevention enum with expected values. See Also: public-access-prevention
HmacKey.HmacKeyState
NotificationInfo.EventType
NotificationInfo.PayloadFormat
PostPolicyV4.ConditionV4Type
Storage.BlobField
Storage.BucketField
Storage.PredefinedAcl
Storage.UriScheme
TransportCompatibility.Transport
Enum representing the transports com.google.cloud.storage
classes have implementations
for.
Exceptions
StorageBatchResult<T>
This class holds a single result of a batch call to Cloud Storage.
StorageException
Storage service exception. See Also: Google Cloud Storage error codes
Annotation Types
TransportCompatibility
Annotation which is used to convey which Cloud Storage API a class or method has compatibility with.
Not all operations are compatible with all transports.