public interface Storage extends Service<StorageOptions>
Modifier and Type | Interface and Description |
---|---|
static class |
Storage.BlobField |
static class |
Storage.BlobGetOption
Class for specifying blob get options.
|
static class |
Storage.BlobListOption
Class for specifying blob list options.
|
static class |
Storage.BlobSourceOption
Class for specifying blob source options.
|
static class |
Storage.BlobTargetOption
Class for specifying blob target options.
|
static class |
Storage.BlobWriteOption
Class for specifying blob write options.
|
static class |
Storage.BucketField |
static class |
Storage.BucketGetOption
Class for specifying bucket get options.
|
static class |
Storage.BucketListOption
Class for specifying bucket list options.
|
static class |
Storage.BucketSourceOption
Class for specifying bucket source options.
|
static class |
Storage.BucketTargetOption
Class for specifying bucket target options.
|
static class |
Storage.ComposeRequest
A class to contain all information needed for a Google Cloud Storage Compose operation.
|
static class |
Storage.CopyRequest
A class to contain all information needed for a Google Cloud Storage Copy operation.
|
static class |
Storage.PredefinedAcl |
static class |
Storage.SignUrlOption
Class for specifying signed URL options.
|
Modifier and Type | Method and Description |
---|---|
StorageBatch |
batch()
Creates a new empty batch for grouping multiple service calls in one underlying RPC call.
|
Blob |
compose(Storage.ComposeRequest composeRequest)
Sends a compose request.
|
CopyWriter |
copy(Storage.CopyRequest copyRequest)
Sends a copy request.
|
Blob |
create(BlobInfo blobInfo,
byte[] content,
int offset,
int length,
Storage.BlobTargetOption... options)
Creates a new blob with the sub array of the given byte array.
|
Blob |
create(BlobInfo blobInfo,
byte[] content,
Storage.BlobTargetOption... options)
Creates a new blob.
|
Blob |
create(BlobInfo blobInfo,
InputStream content,
Storage.BlobWriteOption... options)
Deprecated.
|
Blob |
create(BlobInfo blobInfo,
Storage.BlobTargetOption... options)
Creates a new blob with no content.
|
Bucket |
create(BucketInfo bucketInfo,
Storage.BucketTargetOption... options)
Creates a new bucket.
|
Acl |
createAcl(BlobId blob,
Acl acl)
Creates a new ACL entry on the specified blob.
|
Acl |
createAcl(String bucket,
Acl acl) |
Acl |
createAcl(String bucket,
Acl acl,
Storage.BucketSourceOption... options)
Creates a new ACL entry on the specified bucket.
|
Acl |
createDefaultAcl(String bucket,
Acl acl)
Creates a new default blob ACL entry on the specified bucket.
|
List<Boolean> |
delete(BlobId... blobIds)
Deletes the requested blobs.
|
boolean |
delete(BlobId blob)
Deletes the requested blob.
|
boolean |
delete(BlobId blob,
Storage.BlobSourceOption... options)
Deletes the requested blob.
|
List<Boolean> |
delete(Iterable<BlobId> blobIds)
Deletes the requested blobs.
|
boolean |
delete(String bucket,
Storage.BucketSourceOption... options)
Deletes the requested bucket.
|
boolean |
delete(String bucket,
String blob,
Storage.BlobSourceOption... options)
Deletes the requested blob.
|
boolean |
deleteAcl(BlobId blob,
Acl.Entity entity)
Deletes the ACL entry for the specified entity on the specified blob.
|
boolean |
deleteAcl(String bucket,
Acl.Entity entity) |
boolean |
deleteAcl(String bucket,
Acl.Entity entity,
Storage.BucketSourceOption... options)
Deletes the ACL entry for the specified entity on the specified bucket.
|
boolean |
deleteDefaultAcl(String bucket,
Acl.Entity entity)
Deletes the default object ACL entry for the specified entity on the specified bucket.
|
List<Blob> |
get(BlobId... blobIds)
Gets the requested blobs.
|
Blob |
get(BlobId blob)
Returns the requested blob or
null if not found. |
Blob |
get(BlobId blob,
Storage.BlobGetOption... options)
Returns the requested blob or
null if not found. |
List<Blob> |
get(Iterable<BlobId> blobIds)
Gets the requested blobs.
|
Bucket |
get(String bucket,
Storage.BucketGetOption... options)
Returns the requested bucket or
null if not found. |
Blob |
get(String bucket,
String blob,
Storage.BlobGetOption... options)
Returns the requested blob or
null if not found. |
Acl |
getAcl(BlobId blob,
Acl.Entity entity)
Returns the ACL entry for the specified entity on the specified blob or
null if not
found. |
Acl |
getAcl(String bucket,
Acl.Entity entity) |
Acl |
getAcl(String bucket,
Acl.Entity entity,
Storage.BucketSourceOption... options)
Returns the ACL entry for the specified entity on the specified bucket or
null if not
found. |
Acl |
getDefaultAcl(String bucket,
Acl.Entity entity)
Returns the default object ACL entry for the specified entity on the specified bucket or
null if not found. |
Policy |
getIamPolicy(String bucket,
Storage.BucketSourceOption... options)
Gets the IAM policy for the provided bucket.
|
ServiceAccount |
getServiceAccount(String projectId)
Returns the service account associated with the given project.
|
Page<Bucket> |
list(Storage.BucketListOption... options)
Lists the project's buckets.
|
Page<Blob> |
list(String bucket,
Storage.BlobListOption... options)
Lists the bucket's blobs.
|
List<Acl> |
listAcls(BlobId blob)
Lists the ACL entries for the provided blob.
|
List<Acl> |
listAcls(String bucket) |
List<Acl> |
listAcls(String bucket,
Storage.BucketSourceOption... options)
Lists the ACL entries for the provided bucket.
|
List<Acl> |
listDefaultAcls(String bucket)
Lists the default blob ACL entries for the provided bucket.
|
Bucket |
lockRetentionPolicy(BucketInfo bucket,
Storage.BucketTargetOption... options)
Locks bucket retention policy.
|
byte[] |
readAllBytes(BlobId blob,
Storage.BlobSourceOption... options)
Reads all the bytes from a blob.
|
byte[] |
readAllBytes(String bucket,
String blob,
Storage.BlobSourceOption... options)
Reads all the bytes from a blob.
|
ReadChannel |
reader(BlobId blob,
Storage.BlobSourceOption... options)
Returns a channel for reading the blob's content.
|
ReadChannel |
reader(String bucket,
String blob,
Storage.BlobSourceOption... options)
Returns a channel for reading the blob's content.
|
Policy |
setIamPolicy(String bucket,
Policy policy,
Storage.BucketSourceOption... options)
Updates the IAM policy on the specified bucket.
|
URL |
signUrl(BlobInfo blobInfo,
long duration,
TimeUnit unit,
Storage.SignUrlOption... options)
Generates a signed URL for a blob.
|
List<Boolean> |
testIamPermissions(String bucket,
List<String> permissions,
Storage.BucketSourceOption... options)
Tests whether the caller holds the permissions on the specified bucket.
|
List<Blob> |
update(BlobInfo... blobInfos)
Updates the requested blobs.
|
Blob |
update(BlobInfo blobInfo)
Updates blob information.
|
Blob |
update(BlobInfo blobInfo,
Storage.BlobTargetOption... options)
Updates blob information.
|
Bucket |
update(BucketInfo bucketInfo,
Storage.BucketTargetOption... options)
Updates bucket information.
|
List<Blob> |
update(Iterable<BlobInfo> blobInfos)
Updates the requested blobs.
|
Acl |
updateAcl(BlobId blob,
Acl acl)
Updates an ACL entry on the specified blob.
|
Acl |
updateAcl(String bucket,
Acl acl) |
Acl |
updateAcl(String bucket,
Acl acl,
Storage.BucketSourceOption... options)
Updates an ACL entry on the specified bucket.
|
Acl |
updateDefaultAcl(String bucket,
Acl acl)
Updates a default blob ACL entry on the specified bucket.
|
WriteChannel |
writer(BlobInfo blobInfo,
Storage.BlobWriteOption... options)
Creates a blob and return a channel for writing its content.
|
WriteChannel |
writer(URL signedURL)
Accepts signed URL and return a channel for writing content.
|
getOptions
Bucket create(BucketInfo bucketInfo, Storage.BucketTargetOption... options)
Accepts an optional userProject Storage.BucketTargetOption
option which defines the project
id to assign operational costs.
Example of creating a bucket.
String bucketName = "my_unique_bucket";
Bucket bucket = storage.create(BucketInfo.of(bucketName));
Example of creating a bucket with storage class and location.
String bucketName = "my_unique_bucket";
Bucket bucket = storage.create(BucketInfo.newBuilder(bucketName)
// See here for possible values: http://g.co/cloud/storage/docs/storage-classes
.setStorageClass(StorageClass.COLDLINE)
// Possible values: http://g.co/cloud/storage/docs/bucket-locations#location-mr
.setLocation("asia")
.build());
StorageException
- upon failureBlob create(BlobInfo blobInfo, Storage.BlobTargetOption... options)
Example of creating a blob with no content.
String bucketName = "my_unique_bucket";
String blobName = "my_blob_name";
BlobId blobId = BlobId.of(bucketName, blobName);
BlobInfo blobInfo = BlobInfo.newBuilder(blobId).setContentType("text/plain").build();
Blob blob = storage.create(blobInfo);
StorageException
- upon failureBlob create(BlobInfo blobInfo, byte[] content, Storage.BlobTargetOption... options)
content
. For large content, writer(com.google.cloud.storage.BlobInfo, com.google.cloud.storage.Storage.BlobWriteOption...)
is recommended as it uses resumable upload. MD5 and CRC32C hashes of content
are computed and used for validating transferred data. Accepts an optional userProject Storage.BlobGetOption
option which defines the project id to assign operational costs.
Example of creating a blob from a byte array.
String bucketName = "my_unique_bucket";
String blobName = "my_blob_name";
BlobId blobId = BlobId.of(bucketName, blobName);
BlobInfo blobInfo = BlobInfo.newBuilder(blobId).setContentType("text/plain").build();
Blob blob = storage.create(blobInfo, "Hello, World!".getBytes(UTF_8));
StorageException
- upon failureBlob create(BlobInfo blobInfo, byte[] content, int offset, int length, Storage.BlobTargetOption... options)
content
. For large content, writer(com.google.cloud.storage.BlobInfo, com.google.cloud.storage.Storage.BlobWriteOption...)
is recommended as it uses resumable upload.
MD5 and CRC32C hashes of content
are computed and used for validating transferred data.
Accepts a userProject Storage.BlobGetOption
option, which defines the project id to assign
operational costs.
Example of creating a blob from a byte array.
String bucketName = "my_unique_bucket";
String blobName = "my_blob_name";
BlobId blobId = BlobId.of(bucketName, blobName);
BlobInfo blobInfo = BlobInfo.newBuilder(blobId).setContentType("text/plain").build();
Blob blob = storage.create(blobInfo, "Hello, World!".getBytes(UTF_8), 7, 5);
StorageException
- upon failure@Deprecated Blob create(BlobInfo blobInfo, InputStream content, Storage.BlobWriteOption... options)
content
. For large content, writer(com.google.cloud.storage.BlobInfo, com.google.cloud.storage.Storage.BlobWriteOption...)
is recommended as it uses resumable upload. By default any md5 and crc32c values in
the given blobInfo
are ignored unless requested via the BlobWriteOption.md5Match
and BlobWriteOption.crc32cMatch
options. The given input
stream is closed upon success.
This method is marked as Deprecated
because it cannot safely retry, given that it
accepts an InputStream
which can only be consumed once.
Example of creating a blob from an input stream.
String bucketName = "my_unique_bucket";
String blobName = "my_blob_name";
InputStream content = new ByteArrayInputStream("Hello, World!".getBytes(UTF_8));
BlobId blobId = BlobId.of(bucketName, blobName);
BlobInfo blobInfo = BlobInfo.newBuilder(blobId).setContentType("text/plain").build();
Blob blob = storage.create(blobInfo, content);
Example of uploading an encrypted blob.
String bucketName = "my_unique_bucket";
String blobName = "my_blob_name";
String encryptionKey = "my_encryption_key";
InputStream content = new ByteArrayInputStream("Hello, World!".getBytes(UTF_8));
BlobId blobId = BlobId.of(bucketName, blobName);
BlobInfo blobInfo = BlobInfo.newBuilder(blobId)
.setContentType("text/plain")
.build();
Blob blob = storage.create(blobInfo, content, BlobWriteOption.encryptionKey(encryptionKey));
StorageException
- upon failureBucket get(String bucket, Storage.BucketGetOption... options)
null
if not found.
Accepts an optional userProject Storage.BucketGetOption
option which defines the project id
to assign operational costs.
Example of getting information on a bucket, only if its metageneration matches a value,
otherwise a StorageException
is thrown.
String bucketName = "my_unique_bucket";
long bucketMetageneration = 42;
Bucket bucket = storage.get(bucketName,
BucketGetOption.metagenerationMatch(bucketMetageneration));
StorageException
- upon failureBucket lockRetentionPolicy(BucketInfo bucket, Storage.BucketTargetOption... options)
Accepts an optional userProject Storage.BucketTargetOption
option which defines the project
id to assign operational costs.
Warning: Once a retention policy is locked, it can't be unlocked, removed, or shortened.
Example of locking a retention policy on a bucket, only if its local metageneration value
matches the bucket's service metageneration otherwise a StorageException
is thrown.
String bucketName = "my_unique_bucket";
Bucket bucket = storage.get(bucketName, BucketGetOption.fields(BucketField.METAGENERATION));
storage.lockRetentionPolicy(bucket, BucketTargetOption.metagenerationMatch());
Bucket
object of the locked bucketStorageException
- upon failureBlob get(String bucket, String blob, Storage.BlobGetOption... options)
null
if not found.
Accepts an optional userProject Storage.BlobGetOption
option which defines the project id to
assign operational costs.
Example of getting information on a blob, only if its metageneration matches a value,
otherwise a StorageException
is thrown.
String bucketName = "my_unique_bucket";
String blobName = "my_blob_name";
long blobMetageneration = 42;
Blob blob = storage.get(bucketName, blobName,
BlobGetOption.metagenerationMatch(blobMetageneration));
StorageException
- upon failureBlob get(BlobId blob, Storage.BlobGetOption... options)
null
if not found.
Accepts an optional userProject Storage.BlobGetOption
option which defines the project id to
assign operational costs.
Example of getting information on a blob, only if its metageneration matches a value,
otherwise a StorageException
is thrown.
String bucketName = "my_unique_bucket";
String blobName = "my_blob_name";
long blobMetageneration = 42;
BlobId blobId = BlobId.of(bucketName, blobName);
Blob blob = storage.get(blobId, BlobGetOption.metagenerationMatch(blobMetageneration));
StorageException
- upon failureBlob get(BlobId blob)
null
if not found.
Example of getting information on a blob.
String bucketName = "my_unique_bucket";
String blobName = "my_blob_name";
BlobId blobId = BlobId.of(bucketName, blobName);
Blob blob = storage.get(blobId);
StorageException
- upon failurePage<Bucket> list(Storage.BucketListOption... options)
Example of listing buckets, specifying the page size and a name prefix.
String prefix = "bucket_";
Page<Bucket> buckets = storage.list(BucketListOption.pageSize(100),
BucketListOption.prefix(prefix));
Iterator<Bucket> bucketIterator = buckets.iterateAll();
while (bucketIterator.hasNext()) {
Bucket bucket = bucketIterator.next();
// do something with the bucket
}
StorageException
- upon failurePage<Blob> list(String bucket, Storage.BlobListOption... options)
Storage.BlobListOption.currentDirectory()
option is provided,
results are returned in a directory-like mode.
Example of listing blobs in a provided directory.
String bucketName = "my_unique_bucket";
String directory = "my_directory/";
Page<Blob> blobs = storage.list(bucketName, BlobListOption.currentDirectory(),
BlobListOption.prefix(directory));
Iterator<Blob> blobIterator = blobs.iterateAll();
while (blobIterator.hasNext()) {
Blob blob = blobIterator.next();
// do something with the blob
}
StorageException
- upon failureBucket update(BucketInfo bucketInfo, Storage.BucketTargetOption... options)
Accepts an optional userProject Storage.BucketTargetOption
option which defines the project
id to assign operational costs.
Example of updating bucket information.
String bucketName = "my_unique_bucket";
BucketInfo bucketInfo = BucketInfo.newBuilder(bucketName).setVersioningEnabled(true).build();
Bucket bucket = storage.update(bucketInfo);
StorageException
- upon failureBlob update(BlobInfo blobInfo, Storage.BlobTargetOption... options)
blobInfo
. To replace metadata instead you first have to unset them. Unsetting metadata can be
done by setting the provided blobInfo
's metadata to null
. Accepts an optional
userProject Storage.BlobTargetOption
option which defines the project id to assign operational
costs.
Example of udating a blob, only if the blob's metageneration matches a value, otherwise a
StorageException
is thrown.
String bucketName = "my_unique_bucket";
String blobName = "my_blob_name";
Blob blob = storage.get(bucketName, blobName);
BlobInfo updatedInfo = blob.toBuilder().setContentType("text/plain").build();
storage.update(updatedInfo, BlobTargetOption.metagenerationMatch());
StorageException
- upon failureBlob update(BlobInfo blobInfo)
blobInfo
. To replace metadata instead you first have to unset them. Unsetting metadata can be
done by setting the provided blobInfo
's metadata to null
.
Example of replacing blob's metadata.
String bucketName = "my_unique_bucket";
String blobName = "my_blob_name";
Map<String, String> newMetadata = new HashMap<>();
newMetadata.put("key", "value");
storage.update(BlobInfo.newBuilder(bucketName, blobName).setMetadata(null).build());
Blob blob = storage.update(BlobInfo.newBuilder(bucketName, blobName)
.setMetadata(newMetadata)
.build());
StorageException
- upon failureboolean delete(String bucket, Storage.BucketSourceOption... options)
Accepts an optional userProject Storage.BucketSourceOption
option which defines the project
id to assign operational costs.
Example of deleting a bucket, only if its metageneration matches a value, otherwise a StorageException
is thrown.
String bucketName = "my_unique_bucket";
long bucketMetageneration = 42;
boolean deleted = storage.delete(bucketName,
BucketSourceOption.metagenerationMatch(bucketMetageneration));
if (deleted) {
// the bucket was deleted
} else {
// the bucket was not found
}
true
if bucket was deleted, false
if it was not foundStorageException
- upon failureboolean delete(String bucket, String blob, Storage.BlobSourceOption... options)
Example of deleting a blob, only if its generation matches a value, otherwise a StorageException
is thrown.
String bucketName = "my_unique_bucket";
String blobName = "my_blob_name";
long blobGeneration = 42;
boolean deleted = storage.delete(bucketName, blobName,
BlobSourceOption.generationMatch(blobGeneration));
if (deleted) {
// the blob was deleted
} else {
// the blob was not found
}
true
if blob was deleted, false
if it was not foundStorageException
- upon failureboolean delete(BlobId blob, Storage.BlobSourceOption... options)
Accepts an optional userProject Storage.BlobSourceOption
option which defines the project id
to assign operational costs.
Example of deleting a blob, only if its generation matches a value, otherwise a StorageException
is thrown.
String bucketName = "my_unique_bucket";
String blobName = "my_blob_name";
long blobGeneration = 42;
BlobId blobId = BlobId.of(bucketName, blobName);
boolean deleted = storage.delete(blobId, BlobSourceOption.generationMatch(blobGeneration));
if (deleted) {
// the blob was deleted
} else {
// the blob was not found
}
true
if blob was deleted, false
if it was not foundStorageException
- upon failureboolean delete(BlobId blob)
Example of deleting a blob.
String bucketName = "my_unique_bucket";
String blobName = "my_blob_name";
BlobId blobId = BlobId.of(bucketName, blobName);
boolean deleted = storage.delete(blobId);
if (deleted) {
// the blob was deleted
} else {
// the blob was not found
}
true
if blob was deleted, false
if it was not foundStorageException
- upon failureBlob compose(Storage.ComposeRequest composeRequest)
Accepts an optional userProject Storage.BlobTargetOption
option which defines the project id
to assign operational costs.
Example of composing two blobs.
String bucketName = "my_unique_bucket";
String blobName = "my_blob_name";
String sourceBlob1 = "source_blob_1";
String sourceBlob2 = "source_blob_2";
BlobId blobId = BlobId.of(bucketName, blobName);
BlobInfo blobInfo = BlobInfo.newBuilder(blobId).setContentType("text/plain").build();
ComposeRequest request = ComposeRequest.newBuilder()
.setTarget(blobInfo)
.addSource(sourceBlob1)
.addSource(sourceBlob2)
.build();
Blob blob = storage.compose(request);
StorageException
- upon failureCopyWriter copy(Storage.CopyRequest copyRequest)
BlobInfo
to the CopyRequest
using either Storage.CopyRequest.Builder.setTarget(BlobInfo, Storage.BlobTargetOption...)
or Storage.CopyRequest.Builder.setTarget(BlobInfo, Iterable)
.
This method returns a CopyWriter
object for the provided CopyRequest
. If
source and destination objects share the same location and storage class the source blob is
copied with one request and CopyWriter.getResult()
immediately returns, regardless of
the Storage.CopyRequest.megabytesCopiedPerChunk
parameter. If source and destination have
different location or storage class CopyWriter.getResult()
might issue multiple RPC
calls depending on blob's size.
Example of copying a blob.
String bucketName = "my_unique_bucket";
String blobName = "my_blob_name";
String copyBlobName = "copy_blob_name";
CopyRequest request = CopyRequest.newBuilder()
.setSource(BlobId.of(bucketName, blobName))
.setTarget(BlobId.of(bucketName, copyBlobName))
.build();
Blob blob = storage.copy(request).getResult();
Example of copying a blob in chunks.
String bucketName = "my_unique_bucket";
String blobName = "my_blob_name";
String copyBlobName = "copy_blob_name";
CopyRequest request = CopyRequest.newBuilder()
.setSource(BlobId.of(bucketName, blobName))
.setTarget(BlobId.of(bucketName, copyBlobName))
.build();
CopyWriter copyWriter = storage.copy(request);
while (!copyWriter.isDone()) {
copyWriter.copyChunk();
}
Blob blob = copyWriter.getResult();
Example of rotating the encryption key of a blob.
String bucketName = "my_unique_bucket";
String blobName = "my_blob_name";
String oldEncryptionKey = "old_encryption_key";
String newEncryptionKey = "new_encryption_key";
BlobId blobId = BlobId.of(bucketName, blobName);
CopyRequest request = CopyRequest.newBuilder()
.setSource(blobId)
.setSourceOptions(BlobSourceOption.decryptionKey(oldEncryptionKey))
.setTarget(blobId, BlobTargetOption.encryptionKey(newEncryptionKey))
.build();
Blob blob = storage.copy(request).getResult();
CopyWriter
object that can be used to get information on the newly created
blob or to complete the copy if more than one RPC request is neededStorageException
- upon failurebyte[] readAllBytes(String bucket, String blob, Storage.BlobSourceOption... options)
Example of reading all bytes of a blob, if generation matches a value, otherwise a StorageException
is thrown.
String bucketName = "my_unique_bucket";
String blobName = "my_blob_name";
long blobGeneration = 42";
byte[] content = storage.readAllBytes(bucketName, blobName,
BlobSourceOption.generationMatch(blobGeneration));
StorageException
- upon failurebyte[] readAllBytes(BlobId blob, Storage.BlobSourceOption... options)
Example of reading all bytes of a blob's specific generation, otherwise a StorageException
is thrown.
String bucketName = "my_unique_bucket";
String blobName = "my_blob_name";
long blobGeneration = 42;
BlobId blobId = BlobId.of(bucketName, blobName, blobGeneration);
byte[] content = storage.readAllBytes(blobId);
Example of reading all bytes of an encrypted blob.
String bucketName = "my_unique_bucket";
String blobName = "my_blob_name";
String decryptionKey = "my_encryption_key";
byte[] content = storage.readAllBytes(
bucketName, blobName, BlobSourceOption.decryptionKey(decryptionKey));
StorageException
- upon failureStorageBatch batch()
Example of using a batch request to delete, update and get a blob.
String bucketName = "my_unique_bucket";
String blobName1 = "my_blob_name1";
String blobName2 = "my_blob_name2";
StorageBatch batch = storage.batch();
BlobId firstBlob = BlobId.of(bucketName, blobName1);
BlobId secondBlob = BlobId.of(bucketName, blobName2);
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.newBuilder(secondBlob).setContentType("text/plain").build());
StorageBatchResult<Blob> result = batch.get(secondBlob);
batch.submit();
Blob blob = result.get(); // returns get result or throws StorageException
ReadChannel reader(String bucket, String blob, Storage.BlobSourceOption... options)
BlobInfo.getEtag()
changes), subsequent calls to
blobReadChannel.read(ByteBuffer)
may throw StorageException
.
Example of reading a blob's content through a reader.
String bucketName = "my_unique_bucket";
String blobName = "my_blob_name";
try (ReadChannel reader = storage.reader(bucketName, blobName)) {
ByteBuffer bytes = ByteBuffer.allocate(64 * 1024);
while (reader.read(bytes) > 0) {
bytes.flip();
// do something with bytes
bytes.clear();
}
}
StorageException
- upon failureReadChannel reader(BlobId blob, Storage.BlobSourceOption... options)
blob.generation()
is set data
corresponding to that generation is read. If blob.generation()
is null
the
blob's latest generation is read. If the blob changes while reading (i.e. BlobInfo.getEtag()
changes), subsequent calls to blobReadChannel.read(ByteBuffer)
may
throw StorageException
.
The Storage.BlobSourceOption.generationMatch()
and Storage.BlobSourceOption.generationMatch(long)
options can be used to ensure that blobReadChannel.read(ByteBuffer)
calls will throw StorageException
if the blob`s
generation differs from the expected one.
Example of reading a blob's content through a reader.
String bucketName = "my_unique_bucket";
String blobName = "my_blob_name";
BlobId blobId = BlobId.of(bucketName, blobName);
try (ReadChannel reader = storage.reader(blobId)) {
ByteBuffer bytes = ByteBuffer.allocate(64 * 1024);
while (reader.read(bytes) > 0) {
bytes.flip();
// do something with bytes
bytes.clear();
}
}
StorageException
- upon failureWriteChannel writer(BlobInfo blobInfo, Storage.BlobWriteOption... options)
blobInfo
are ignored unless requested via the BlobWriteOption.md5Match
and BlobWriteOption.crc32cMatch
options.
Example of writing a blob's content through a writer.
String bucketName = "my_unique_bucket";
String blobName = "my_blob_name";
BlobId blobId = BlobId.of(bucketName, blobName);
byte[] content = "Hello, World!".getBytes(UTF_8);
BlobInfo blobInfo = BlobInfo.newBuilder(blobId).setContentType("text/plain").build();
try (WriteChannel writer = storage.writer(blobInfo)) {
try {
writer.write(ByteBuffer.wrap(content, 0, content.length));
} catch (Exception ex) {
// handle exception
}
}
StorageException
- upon failureWriteChannel writer(URL signedURL)
Example of writing content through a writer using signed URL.
String bucketName = "my_unique_bucket";
String blobName = "my_blob_name";
BlobId blobId = BlobId.of(bucketName, blobName);
byte[] content = "Hello, World!".getBytes(UTF_8);
BlobInfo blobInfo = BlobInfo.newBuilder(blobId).setContentType("text/plain").build();
URL signedURL = storage.signUrl(blobInfo, 1, TimeUnit.HOURS, Storage.SignUrlOption.httpMethod(HttpMethod.POST));
try (WriteChannel writer = storage.writer(signedURL)) {
writer.write(ByteBuffer.wrap(content, 0, content.length));
}
StorageException
- upon failureURL signUrl(BlobInfo blobInfo, long duration, TimeUnit unit, Storage.SignUrlOption... options)
ServiceAccountSigner
was passed to
StorageOptions
' builder via setCredentials(Credentials)
or the default
credentials are being used and the environment variable GOOGLE_APPLICATION_CREDENTIALS
is set or your application is running in App Engine, then signUrl
will use that
credentials to sign the URL. If the credentials passed to StorageOptions
do not
implement ServiceAccountSigner
(this is the case, for instance, for Google Cloud SDK
credentials) then signUrl
will throw an IllegalStateException
unless an
implementation of ServiceAccountSigner
is passed using the Storage.SignUrlOption.signWith(ServiceAccountSigner)
option.
A service account signer is looked for in the following order:
Storage.SignUrlOption.signWith(ServiceAccountSigner)
StorageOptions
StorageOptions
Example of creating a signed URL that is valid for 2 weeks, using the default credentials for signing the URL.
String bucketName = "my_unique_bucket";
String blobName = "my_blob_name";
URL signedUrl = storage.signUrl(BlobInfo.newBuilder(bucketName, blobName).build(), 14,
TimeUnit.DAYS);
Example of creating a signed URL passing the Storage.SignUrlOption.withV4Signature()
option,
which enables V4 signing.
String bucketName = "my_unique_bucket";
String blobName = "my_blob_name";
URL signedUrl = storage.signUrl(BlobInfo.newBuilder(bucketName, blobName).build(),
7, TimeUnit.DAYS, Storage.SignUrlOption.withV4Signature());
Example of creating a signed URL passing the Storage.SignUrlOption.signWith(ServiceAccountSigner)
option, that will be used for signing the URL.
String bucketName = "my_unique_bucket";
String blobName = "my_blob_name";
String keyPath = "/path/to/key.json";
URL signedUrl = storage.signUrl(BlobInfo.newBuilder(bucketName, blobName).build(),
14, TimeUnit.DAYS, SignUrlOption.signWith(
ServiceAccountCredentials.fromStream(new FileInputStream(keyPath))));
Note that the ServiceAccountSigner
may require additional configuration to enable
URL signing. See the documentation for the implementation for more details.
blobInfo
- the blob associated with the signed URLduration
- time until the signed URL expires, expressed in unit
. The finest
granularity supported is 1 second, finer granularities will be truncatedunit
- time unit of the duration
parameteroptions
- optional URL signing options SignUrlOption.withHostName()
option to set
a custom host name instead of using https://storage.googleapis.com.IllegalStateException
- if Storage.SignUrlOption.signWith(ServiceAccountSigner)
was not
used and no implementation of ServiceAccountSigner
was provided to StorageOptions
IllegalArgumentException
- if SignUrlOption.withMd5()
option is used and blobInfo.md5()
is null
IllegalArgumentException
- if SignUrlOption.withContentType()
option is used and
blobInfo.contentType()
is null
ServiceAccountSigner.SigningException
- if the attempt to sign the URL failedList<Blob> get(BlobId... blobIds)
Example of getting information on several blobs using a single batch request.
String bucketName = "my_unique_bucket";
String blobName1 = "my_blob_name1";
String blobName2 = "my_blob_name2";
BlobId firstBlob = BlobId.of(bucketName, blobName1);
BlobId secondBlob = BlobId.of(bucketName, blobName2);
List<Blob> blobs = storage.get(firstBlob, secondBlob);
blobIds
- blobs to getBlob
objects. If a blob does not exist or access to it has
been denied the corresponding item in the list is null
.StorageException
- upon failureList<Blob> get(Iterable<BlobId> blobIds)
Example of getting information on several blobs using a single batch request.
String bucketName = "my_unique_bucket";
String blobName1 = "my_blob_name1";
String blobName2 = "my_blob_name2";
List<BlobId> blobIds = new LinkedList<>();
blobIds.add(BlobId.of(bucketName, blobName1));
blobIds.add(BlobId.of(bucketName, blobName2));
List<Blob> blobs = storage.get(blobIds);
blobIds
- blobs to getBlob
objects. If a blob does not exist or access to it has
been denied the corresponding item in the list is null
.StorageException
- upon failureList<Blob> update(BlobInfo... blobInfos)
BlobInfo
objects. To replace metadata instead
you first have to unset them. Unsetting metadata can be done by setting the provided BlobInfo
objects metadata to null
. See update(BlobInfo)
for a code example.
Example of updating information on several blobs using a single batch request.
String bucketName = "my_unique_bucket";
String blobName1 = "my_blob_name1";
String blobName2 = "my_blob_name2";
Blob firstBlob = storage.get(bucketName, blobName1);
Blob secondBlob = storage.get(bucketName, blobName2);
List<Blob> updatedBlobs = storage.update(
firstBlob.toBuilder().setContentType("text/plain").build(),
secondBlob.toBuilder().setContentType("text/plain").build());
blobInfos
- blobs to updateBlob
objects. If a blob does not exist or access to it has
been denied the corresponding item in the list is null
.StorageException
- upon failureList<Blob> update(Iterable<BlobInfo> blobInfos)
BlobInfo
objects. To replace metadata instead
you first have to unset them. Unsetting metadata can be done by setting the provided BlobInfo
objects metadata to null
. See update(BlobInfo)
for a code example.
Example of updating information on several blobs using a single batch request.
String bucketName = "my_unique_bucket";
String blobName1 = "my_blob_name1";
String blobName2 = "my_blob_name2";
Blob firstBlob = storage.get(bucketName, blobName1);
Blob secondBlob = storage.get(bucketName, blobName2);
List<BlobInfo> blobs = new LinkedList<>();
blobs.add(firstBlob.toBuilder().setContentType("text/plain").build());
blobs.add(secondBlob.toBuilder().setContentType("text/plain").build());
List<Blob> updatedBlobs = storage.update(blobs);
blobInfos
- blobs to updateBlob
objects. If a blob does not exist or access to it has
been denied the corresponding item in the list is null
.StorageException
- upon failureList<Boolean> delete(BlobId... blobIds)
Example of deleting several blobs using a single batch request.
String bucketName = "my_unique_bucket";
String blobName1 = "my_blob_name1";
String blobName2 = "my_blob_name2";
BlobId firstBlob = BlobId.of(bucketName, blobName1);
BlobId secondBlob = BlobId.of(bucketName, blobName2);
List<Boolean> deleted = storage.delete(firstBlob, secondBlob);
blobIds
- blobs to deletetrue
. If a blob was not found, deletion failed or access to the resource
was denied the corresponding item is false
.StorageException
- upon failureList<Boolean> delete(Iterable<BlobId> blobIds)
Example of deleting several blobs using a single batch request.
String bucketName = "my_unique_bucket";
String blobName1 = "my_blob_name1";
String blobName2 = "my_blob_name2";
List<BlobId> blobIds = new LinkedList<>();
blobIds.add(BlobId.of(bucketName, blobName1));
blobIds.add(BlobId.of(bucketName, blobName2));
List<Boolean> deleted = storage.delete(blobIds);
blobIds
- blobs to deletetrue
. If a blob was not found, deletion failed or access to the resource
was denied the corresponding item is false
.StorageException
- upon failureAcl getAcl(String bucket, Acl.Entity entity, Storage.BucketSourceOption... options)
null
if not
found.
Example of getting the ACL entry for an entity on a bucket.
String bucketName = "my_unique_bucket";
Acl acl = storage.getAcl(bucketName, User.ofAllAuthenticatedUsers());
Example of getting the ACL entry for a specific user on a requester_pays bucket with a user_project option.
String bucketName = "my_unique_bucket";
String userEmail = "google-cloud-java-tests@java-docs-samples-tests.iam.gserviceaccount.com";
BucketSourceOption userProjectOption = BucketSourceOption.userProject("myProject");
Acl acl = storage.getAcl(bucketName, new User(userEmail), userProjectOption);
bucket
- name of the bucket where the getAcl operation takes placeentity
- ACL entity to fetchoptions
- extra parameters to apply to this operationStorageException
- upon failureAcl getAcl(String bucket, Acl.Entity entity)
#getAcl(String, Entity, BucketSourceOption...)
boolean deleteAcl(String bucket, Acl.Entity entity, Storage.BucketSourceOption... options)
Example of deleting the ACL entry for an entity on a bucket.
String bucketName = "my_unique_bucket";
boolean deleted = storage.deleteAcl(bucketName, User.ofAllAuthenticatedUsers());
if (deleted) {
// the acl entry was deleted
} else {
// the acl entry was not found
}
Example of deleting the ACL entry for a specific user on a requester_pays bucket with a user_project option.
String bucketName = "my_unique_bucket";
BucketSourceOption userProject = BucketSourceOption.userProject("myProject");
boolean deleted = storage.deleteAcl(bucketName, User.ofAllAuthenticatedUsers(), userProject);
bucket
- name of the bucket to delete an ACL fromentity
- ACL entity to deleteoptions
- extra parameters to apply to this operationtrue
if the ACL was deleted, false
if it was not foundStorageException
- upon failureboolean deleteAcl(String bucket, Acl.Entity entity)
#deleteAcl(String, Entity, BucketSourceOption...)
Acl createAcl(String bucket, Acl acl, Storage.BucketSourceOption... options)
Example of creating a new ACL entry on a bucket.
String bucketName = "my_unique_bucket";
Acl acl = storage.createAcl(bucketName, Acl.of(User.ofAllAuthenticatedUsers(), Role.READER));
Example of creating a new ACL entry on a requester_pays bucket with a user_project option.
String bucketName = "my_unique_bucket";
Acl acl = storage.createAcl(bucketName, Acl.of(User.ofAllAuthenticatedUsers(), Role.READER),
BucketSourceOption.userProject("myProject"));
bucket
- name of the bucket for which an ACL should be createdacl
- ACL to createoptions
- extra parameters to apply to this operationStorageException
- upon failureAcl updateAcl(String bucket, Acl acl, Storage.BucketSourceOption... options)
Example of updating a new ACL entry on a bucket.
String bucketName = "my_unique_bucket";
Acl acl = storage.updateAcl(bucketName, Acl.of(User.ofAllAuthenticatedUsers(), Role.OWNER));
Example of updating a new ACL entry on a requester_pays bucket with a user_project option.
String bucketName = "my_unique_bucket";
Acl acl = storage.updateAcl(bucketName, Acl.of(User.ofAllAuthenticatedUsers(), Role.OWNER),
BucketSourceOption.userProject("myProject"));
bucket
- name of the bucket where the updateAcl operation takes placeacl
- ACL to updateoptions
- extra parameters to apply to this operationStorageException
- upon failureList<Acl> listAcls(String bucket, Storage.BucketSourceOption... options)
Example of listing the ACL entries for a blob.
String bucketName = "my_unique_bucket";
List<Acl> acls = storage.listAcls(bucketName);
for (Acl acl : acls) {
// do something with ACL entry
}
Example of listing the ACL entries for a blob in a requester_pays bucket with a user_project option.
String bucketName = "my_unique_bucket";
List<Acl> acls = storage.listAcls(bucketName, BucketSourceOption.userProject("myProject"));
for (Acl acl : acls) {
// do something with ACL entry
}
bucket
- the name of the bucket to list ACLs foroptions
- any number of BucketSourceOptions to apply to this operationStorageException
- upon failureList<Acl> listAcls(String bucket)
listAcls(String, BucketSourceOption...)
Acl getDefaultAcl(String bucket, Acl.Entity entity)
null
if not found.
Default ACLs are applied to a new blob within the bucket when no ACL was provided for that blob.
Example of getting the default ACL entry for an entity on a bucket.
String bucketName = "my_unique_bucket";
Acl acl = storage.getDefaultAcl(bucketName, User.ofAllAuthenticatedUsers());
StorageException
- upon failureboolean deleteDefaultAcl(String bucket, Acl.Entity entity)
Default ACLs are applied to a new blob within the bucket when no ACL was provided for that blob.
Example of deleting the default ACL entry for an entity on a bucket.
String bucketName = "my_unique_bucket";
boolean deleted = storage.deleteDefaultAcl(bucketName, User.ofAllAuthenticatedUsers());
if (deleted) {
// the acl entry was deleted
} else {
// the acl entry was not found
}
true
if the ACL was deleted, false
if it was not foundStorageException
- upon failureAcl createDefaultAcl(String bucket, Acl acl)
Default ACLs are applied to a new blob within the bucket when no ACL was provided for that blob.
Example of creating a new default ACL entry on a bucket.
String bucketName = "my_unique_bucket";
Acl acl =
storage.createDefaultAcl(bucketName, Acl.of(User.ofAllAuthenticatedUsers(), Role.READER));
StorageException
- upon failureAcl updateDefaultAcl(String bucket, Acl acl)
Default ACLs are applied to a new blob within the bucket when no ACL was provided for that blob.
Example of updating a new default ACL entry on a bucket.
String bucketName = "my_unique_bucket";
Acl acl =
storage.updateDefaultAcl(bucketName, Acl.of(User.ofAllAuthenticatedUsers(), Role.OWNER));
StorageException
- upon failureList<Acl> listDefaultAcls(String bucket)
Default ACLs are applied to a new blob within the bucket when no ACL was provided for that blob.
Example of listing the default ACL entries for a blob.
String bucketName = "my_unique_bucket";
List<Acl> acls = storage.listDefaultAcls(bucketName);
for (Acl acl : acls) {
// do something with ACL entry
}
StorageException
- upon failureAcl getAcl(BlobId blob, Acl.Entity entity)
null
if not
found.
Example of getting the ACL entry for an entity on a blob.
String bucketName = "my_unique_bucket";
String blobName = "my_blob_name";
long blobGeneration = 42;
BlobId blobId = BlobId.of(bucketName, blobName, blobGeneration);
Acl acl = storage.getAcl(blobId, User.ofAllAuthenticatedUsers());
Example of getting the ACL entry for a specific user on a blob.
String bucketName = "my_unique_bucket";
String blobName = "my_blob_name";
String userEmail = "google-cloud-java-tests@java-docs-samples-tests.iam.gserviceaccount.com";
BlobId blobId = BlobId.of(bucketName, blobName);
Acl acl = storage.getAcl(blobId, new User(userEmail));
StorageException
- upon failureboolean deleteAcl(BlobId blob, Acl.Entity entity)
Example of deleting the ACL entry for an entity on a blob.
String bucketName = "my_unique_bucket";
String blobName = "my_blob_name";
long blobGeneration = 42;
BlobId blobId = BlobId.of(bucketName, blobName, blobGeneration);
boolean deleted = storage.deleteAcl(blobId, User.ofAllAuthenticatedUsers());
if (deleted) {
// the acl entry was deleted
} else {
// the acl entry was not found
}
true
if the ACL was deleted, false
if it was not foundStorageException
- upon failureAcl createAcl(BlobId blob, Acl acl)
Example of creating a new ACL entry on a blob.
String bucketName = "my_unique_bucket";
String blobName = "my_blob_name";
long blobGeneration = 42;
BlobId blobId = BlobId.of(bucketName, blobName, blobGeneration);
Acl acl = storage.createAcl(blobId, Acl.of(User.ofAllAuthenticatedUsers(), Role.READER));
Example of updating a blob to be public-read.
String bucketName = "my_unique_bucket";
String blobName = "my_blob_name";
long blobGeneration = 42;
BlobId blobId = BlobId.of(bucketName, blobName, blobGeneration);
Acl acl = storage.createAcl(blobId, Acl.of(User.ofAllUsers(), Role.READER));
StorageException
- upon failureAcl updateAcl(BlobId blob, Acl acl)
Example of updating a new ACL entry on a blob.
String bucketName = "my_unique_bucket";
String blobName = "my_blob_name";
long blobGeneration = 42;
BlobId blobId = BlobId.of(bucketName, blobName, blobGeneration);
Acl acl = storage.updateAcl(blobId, Acl.of(User.ofAllAuthenticatedUsers(), Role.OWNER));
StorageException
- upon failureList<Acl> listAcls(BlobId blob)
Example of listing the ACL entries for a blob.
String bucketName = "my_unique_bucket";
String blobName = "my_blob_name";
long blobGeneration = 42;
BlobId blobId = BlobId.of(bucketName, blobName, blobGeneration);
List<Acl> acls = storage.listAcls(blobId);
for (Acl acl : acls) {
// do something with ACL entry
}
StorageException
- upon failurePolicy getIamPolicy(String bucket, Storage.BucketSourceOption... options)
Example of getting the IAM policy for a bucket.
String bucketName = "my_unique_bucket";
Policy policy = storage.getIamPolicy(bucketName);
bucket
- name of the bucket where the getIamPolicy operation takes placeoptions
- extra parameters to apply to this operationStorageException
- upon failurePolicy setIamPolicy(String bucket, Policy policy, Storage.BucketSourceOption... options)
Example of updating the IAM policy on a bucket.
// We want to make all objects in our bucket publicly readable.
String bucketName = "my_unique_bucket";
Policy currentPolicy = storage.getIamPolicy(bucketName);
Policy updatedPolicy =
storage.setIamPolicy(
bucketName,
currentPolicy.toBuilder()
.addIdentity(StorageRoles.objectViewer(), Identity.allUsers())
.build());
bucket
- name of the bucket where the setIamPolicy operation takes placepolicy
- policy to be set on the specified bucketoptions
- extra parameters to apply to this operationStorageException
- upon failureList<Boolean> testIamPermissions(String bucket, List<String> permissions, Storage.BucketSourceOption... options)
Example of testing permissions on a bucket.
String bucketName = "my_unique_bucket";
List<Boolean> response =
storage.testIamPermissions(
bucket,
ImmutableList.of("storage.buckets.get", "storage.buckets.getIamPolicy"));
for (boolean hasPermission : response) {
// Do something with permission test response
}
bucket
- name of the bucket where the testIamPermissions operation takes placepermissions
- list of permissions to test on the bucketoptions
- extra parameters to apply to this operationStorageException
- upon failureServiceAccount getServiceAccount(String projectId)
Example of getting a service account.
String projectId = "test@gmail.com";
ServiceAccount account = storage.getServiceAccount(projectId);
projectId
- the ID of the project for which the service account should be fetched.StorageException
- upon failureCopyright © 2019 Google LLC. All rights reserved.