Class StorageClient (3.7.0) 

public abstract class StorageClient : IDisposable

Abstract class providing operations for Google Cloud Storage.

Inheritance

Object > StorageClient

Implements

IDisposable

Derived Types

Namespace

Google.Cloud.Storage.V1

Assembly

Google.Cloud.Storage.V1.dll

Remarks

This abstract class is provided to enable testability while permitting additional operations to be added in the future. See Create(GoogleCredential, EncryptionKey) and CreateAsync(GoogleCredential, EncryptionKey) to construct instances; alternatively, you can construct a StorageClientImpl directly from a StorageService.

All instance methods declared in this class are virtual, with an implementation which simply throws NotImplementedException. All these methods are overridden in StorageClientImpl.

This class implements IDisposable; however, the Dispose() method only requires calling if many short-lived instances of StorageClient are being created. Most code would be expected to create a single StorageClient instance, and use this instance throughout the lifetime of the application. In this case, Dispose need not be called.

Properties

EncryptionKey

public virtual EncryptionKey EncryptionKey { get; }

The customer-supplied encryption key used by default for all relevant object-based operations. This can be overridden in call-specific options. This will never return null in the built-in implementation; if no encryption key is specified, None is returned.

Property Value
Type Description
EncryptionKey

Service

public virtual StorageService Service { get; }

The underlying storage service object used by this client.

Property Value
Type Description
StorageService
Remarks

The StorageClient class only provides convenience operations built on top of an existing service object. Any more complex operations which are not supported by this wrapper may wish to use the same service object as the wrapper, in order to take advantage of its configuration (for authentication, application naming etc).

Methods

ClearBucketLabels(String, ModifyBucketLabelsOptions)

public virtual IDictionary<string, string> ClearBucketLabels(string bucket, ModifyBucketLabelsOptions options = null)

Clears all labels on a bucket.

Parameters
Name Description
bucket String

The name of the bucket. Must not be null.
options ModifyBucketLabelsOptions

The options for the operation. May be null, in which case defaults will be supplied.
Returns
Type Description
IDictionary<String, String>

A dictionary with the labels on the bucket before they were cleared.
Example 
StorageClient client = StorageClient.Create();

IDictionary<string, string> oldLabels = client.ClearBucketLabels(bucketName);
Console.WriteLine($"Number of labels before clearing: {oldLabels.Count}");

ClearBucketLabelsAsync(String, ModifyBucketLabelsOptions, CancellationToken)

public virtual Task<IDictionary<string, string>> ClearBucketLabelsAsync(string bucket, ModifyBucketLabelsOptions options = null, CancellationToken cancellationToken = default(CancellationToken))

Clears all labels on a bucket asynchronously.

Parameters
Name Description
bucket String

The name of the bucket. Must not be null.
options ModifyBucketLabelsOptions

The options for the operation. May be null, in which case defaults will be supplied.
cancellationToken CancellationToken

The token to monitor for cancellation requests.
Returns
Type Description
Task<IDictionary<String, String>>

A dictionary with the labels on the bucket before they were cleared.
Example

See ClearBucketLabels for a synchronous example.

CopyObject(String, String, String, String, CopyObjectOptions)

public virtual Object CopyObject(string sourceBucket, string sourceObjectName, string destinationBucket, string destinationObjectName, CopyObjectOptions options = null)

Creates a copy of an object synchronously, potentially to a different bucket. This method uses the rewriteObject underlying API operation for more flexibility and reliability.

Parameters
Name Description
sourceBucket String

The name of the bucket containing the object to copy. Must not be null.
sourceObjectName String

The name of the object to copy within the bucket. Must not be null.
destinationBucket String

The name of the bucket to copy the object to. Must not be null.
destinationObjectName String

The name of the object within the destination bucket. Must not be null.
options CopyObjectOptions

Additional options for the copy operation. May be null, in which case appropriate defaults will be used.
Returns
Type Description
Object

The Object representation of the new storage object resulting from the copy.
Example 
StorageClient client = StorageClient.Create();
string sourceName = "greetings/hello.txt";
string destinationName = "copy.txt";

// This method actually uses the "rewrite" API operation, for added reliability
// when copying large objects across locations, storage classes or encryption keys.
client.CopyObject(sourceBucket, sourceName, destinationBucket, destinationName);

CopyObjectAsync(String, String, String, String, CopyObjectOptions, CancellationToken)

public virtual Task<Object> CopyObjectAsync(string sourceBucket, string sourceObjectName, string destinationBucket = null, string destinationObjectName = null, CopyObjectOptions options = null, CancellationToken cancellationToken = default(CancellationToken))

Creates a copy of an object synchronously, potentially to a different bucket. This method uses the rewriteObject underlying API operation for more flexibility and reliability.

Parameters
Name Description
sourceBucket String

The name of the bucket containing the object to copy. Must not be null.
sourceObjectName String

The name of the object to copy within the bucket. Must not be null.
destinationBucket String

The name of the bucket to copy the object to. Must not be null.
destinationObjectName String

The name of the object within the destination bucket. Must not be null.
options CopyObjectOptions

Additional options for the copy operation. May be null, in which case appropriate defaults will be used.
cancellationToken CancellationToken

The token to monitor for cancellation requests.
Returns
Type Description
Task<Object>

A task representing the asynchronous operation, with a result returning the Object representation of the new storage object resulting from the copy.
Example

See CopyObject for a synchronous example.

Create(GoogleCredential, EncryptionKey)

public static StorageClient Create(GoogleCredential credential = null, EncryptionKey encryptionKey = null)

Synchronously creates a StorageClient, using application default credentials if no credentials are specified.

Parameters
Name Description
credential GoogleCredential

Optional GoogleCredential.
encryptionKey EncryptionKey

Optional EncryptionKey to use for all relevant object-based operations by default. May be null.
Returns
Type Description
StorageClient

The created StorageClient.
Remarks

The credentials are scoped as necessary.

CreateAsync(GoogleCredential, EncryptionKey)

public static Task<StorageClient> CreateAsync(GoogleCredential credential = null, EncryptionKey encryptionKey = null)

Asynchronously creates a StorageClient, using application default credentials if no credentials are specified.

Parameters
Name Description
credential GoogleCredential

Optional GoogleCredential.
encryptionKey EncryptionKey

Optional EncryptionKey to use for all relevant object-based operations by default. May be null.
Returns
Type Description
Task<StorageClient>

The task representing the created StorageClient.
Remarks

The credentials are scoped as necessary.

CreateBucket(String, Bucket, CreateBucketOptions)

public virtual Bucket CreateBucket(string projectId, Bucket bucket, CreateBucketOptions options = null)

Creates a storage bucket synchronously.

Parameters
Name Description
projectId String

The ID of the project to create the buckets in. Must not be null.
bucket Bucket

The resource representation of the bucket to create. Must not be null, and must have a name.
options CreateBucketOptions

Additional options for the operation. May be null, in which case appropriate defaults will be used.
Returns
Type Description
Bucket

The resource representation of the newly-created bucket.
Example

See CreateBucket for an example using an alternative overload.

CreateBucket(String, String, CreateBucketOptions)

public virtual Bucket CreateBucket(string projectId, string bucket, CreateBucketOptions options = null)

Creates a storage bucket synchronously.

Parameters
Name Description
projectId String

The ID of the project to create the buckets in. Must not be null.
bucket String

The name of the bucket to create. Must not be null.
options CreateBucketOptions

Additional options for the operation. May be null, in which case appropriate defaults will be used.
Returns
Type Description
Bucket

The resource representation of the newly-created bucket.
Example 
var client = StorageClient.Create();

// GCS bucket names must be globally unique
var bucketName = Guid.NewGuid().ToString();

// Bucket defined in Google.Apis.Storage.v1.Data namespace
var bucket = client.CreateBucket(projectId, bucketName);

CreateBucketAsync(String, Bucket, CreateBucketOptions, CancellationToken)

public virtual Task<Bucket> CreateBucketAsync(string projectId, Bucket bucket, CreateBucketOptions options = null, CancellationToken cancellationToken = default(CancellationToken))

Creates a storage bucket asynchronously.

Parameters
Name Description
projectId String

The ID of the project to create the buckets in. Must not be null.
bucket Bucket

The resource representation of the bucket to create. Must not be null, and must have a name.
options CreateBucketOptions

Additional options for the operation. May be null, in which case appropriate defaults will be used.
cancellationToken CancellationToken

The token to monitor for cancellation requests.
Returns
Type Description
Task<Bucket>

A task representing the asynchronous operation, with a result returning the resource representation of the newly-created bucket.
Example

See CreateBucket for a synchronous example.

CreateBucketAsync(String, String, CreateBucketOptions, CancellationToken)

public virtual Task<Bucket> CreateBucketAsync(string projectId, string bucket, CreateBucketOptions options = null, CancellationToken cancellationToken = default(CancellationToken))

Creates a storage bucket asynchronously.

Parameters
Name Description
projectId String

The ID of the project to create the buckets in. Must not be null.
bucket String

The name of the bucket to create. Must not be null.
options CreateBucketOptions

Additional options for the operation. May be null, in which case appropriate defaults will be used.
cancellationToken CancellationToken

The token to monitor for cancellation requests.
Returns
Type Description
Task<Bucket>

A task representing the asynchronous operation, with a result returning the resource representation of the newly-created bucket.
Example

See CreateBucket for a synchronous example.

CreateHmacKey(String, String, CreateHmacKeyOptions)

public virtual HmacKey CreateHmacKey(string projectId, string serviceAccountEmail, CreateHmacKeyOptions options = null)

Synchronously creates a new HMAC key associated with a service account.

Parameters
Name Description
projectId String

The project ID in which to create the HMAC key. Must not be null.
serviceAccountEmail String

The service account to associate with the HMAC key. Must not be null.
options CreateHmacKeyOptions

Additional options for the operation. May be null, in which case appropriate defaults will be used.
Returns
Type Description
HmacKey

The new HMAC key, including the secret information in Secret. This secret is only ever returned when creating a key.

CreateHmacKeyAsync(String, String, CreateHmacKeyOptions, CancellationToken)

public virtual Task<HmacKey> CreateHmacKeyAsync(string projectId, string serviceAccountEmail, CreateHmacKeyOptions options = null, CancellationToken cancellationToken = default(CancellationToken))

Asynchronously creates a new HMAC key associated with a service account.

Parameters
Name Description
projectId String

The project ID in which to create the HMAC key. Must not be null.
serviceAccountEmail String

The service account to associate with the HMAC key. Must not be null.
options CreateHmacKeyOptions

Additional options for the operation. May be null, in which case appropriate defaults will be used.
cancellationToken CancellationToken

The token to monitor for cancellation requests.
Returns
Type Description
Task<HmacKey>

A task representing the asynchronous operation, with a result returning the the new HMAC key, including the secret information in Secret. This secret is only ever returned when creating a key.

CreateNotification(String, Notification, CreateNotificationOptions)

public virtual Notification CreateNotification(string bucket, Notification notification, CreateNotificationOptions options = null)

Creates a notification configuration.

Parameters
Name Description
bucket String

The bucket for which to create the notification configuration. Must not be null.
notification Notification

The notification configuration to create. Must not be null.
options CreateNotificationOptions

The options for the operation. May be null, in which case defaults will be supplied.
Returns
Type Description
Notification

The Notification representation of the newly-created notification configuration.
Example 
TopicName topicName = new TopicName(projectId, topicId);
StorageClient client = StorageClient.Create();
Notification notification = new Notification
{
    Topic = $"//pubsub.googleapis.com/{topicName}",
    PayloadFormat = "JSON_API_V1"
};
notification = client.CreateNotification(bucket, notification);
Console.WriteLine($"Created notification ID: {notification.Id}");

CreateNotificationAsync(String, Notification, CreateNotificationOptions, CancellationToken)

public virtual Task<Notification> CreateNotificationAsync(string bucket, Notification notification, CreateNotificationOptions options = null, CancellationToken cancellationToken = default(CancellationToken))

Asynchronously creates a notification configuration.

Parameters
Name Description
bucket String

The bucket for which to create the notification configuration. Must not be null.
notification Notification

The notification configuration to create. Must not be null.
options CreateNotificationOptions

The options for the operation. May be null, in which case defaults will be supplied.
cancellationToken CancellationToken

The token to monitor for cancellation requests.
Returns
Type Description
Task<Notification>

A task representing the asynchronous operation, with a result returning the Notification representation of the newly-created notification configuration.
Example

See CreateNotification for a synchronous example.

CreateObjectUploader(Object, Stream, UploadObjectOptions)

public virtual ObjectsResource.InsertMediaUpload CreateObjectUploader(Object destination, Stream source, UploadObjectOptions options = null)

Creates an instance which is capable of starting a resumable upload for an object.

Parameters
Name Description
destination Object

Object to create or update. Must not be null, and must have the name, bucket and content type populated.
source Stream

The stream to read the data from. Must not be null.
options UploadObjectOptions

Additional options for the upload. May be null, in which case appropriate defaults will be used.
Returns
Type Description
ObjectsResource.InsertMediaUpload

The ObjectsResource.InsertMediaUpload which can be used to upload the object.
See Also

CreateObjectUploader(String, String, String, Stream, UploadObjectOptions)

public virtual ObjectsResource.InsertMediaUpload CreateObjectUploader(string bucket, string objectName, string contentType, Stream source, UploadObjectOptions options = null)

Creates an instance which is capable of starting a resumable upload for an object.

Parameters
Name Description
bucket String

The name of the bucket containing the object. Must not be null.
objectName String

The name of the object within the bucket. Must not be null.
contentType String

The content type of the object. This should be a MIME type such as "text/html" or "application/octet-stream". May be null.
source Stream

The stream to read the data from. Must not be null.
options UploadObjectOptions

Additional options for the upload. May be null, in which case appropriate defaults will be used.
Returns
Type Description
ObjectsResource.InsertMediaUpload

The ObjectsResource.InsertMediaUpload which can be used to upload the object.
See Also

CreateUnauthenticated()

public static StorageClient CreateUnauthenticated()

Creates a StorageClient with no credentials. This can only be used in limited situations (where authentication isn't required), primarily downloading public data.

Returns
Type Description
StorageClient

The created StorageClient.

DeleteBucket(Bucket, DeleteBucketOptions)

public virtual void DeleteBucket(Bucket bucket, DeleteBucketOptions options = null)

Deletes a bucket synchronously.

Parameters
Name Description
bucket Bucket

Bucket to delete. Must not be null, and must have the name populated.
options DeleteBucketOptions

Additional options for the operation. May be null, in which case appropriate defaults will be used.
Example

See DeleteBucket for an example using an alternative overload.

DeleteBucket(String, DeleteBucketOptions)

public virtual void DeleteBucket(string bucket, DeleteBucketOptions options = null)

Deletes a bucket synchronously.

Parameters
Name Description
bucket String

The name of the bucket to delete. Must not be null.
options DeleteBucketOptions

Additional options for the operation. May be null, in which case appropriate defaults will be used.
Example 
var client = StorageClient.Create();

client.DeleteBucket(bucketName);

DeleteBucketAsync(Bucket, DeleteBucketOptions, CancellationToken)

public virtual Task DeleteBucketAsync(Bucket bucket, DeleteBucketOptions options = null, CancellationToken cancellationToken = default(CancellationToken))

Deletes bucket asynchronously.

Parameters
Name Description
bucket Bucket

Bucket to delete. Must not be null, and must have the name populated.
options DeleteBucketOptions

Additional options for the operation. May be null, in which case appropriate defaults will be used.
cancellationToken CancellationToken

The token to monitor for cancellation requests.
Returns
Type Description
Task

A task representing the asynchronous operation.
Example

See DeleteBucket for a synchronous example.

DeleteBucketAsync(String, DeleteBucketOptions, CancellationToken)

public virtual Task DeleteBucketAsync(string bucket, DeleteBucketOptions options = null, CancellationToken cancellationToken = default(CancellationToken))

Deletes a bucket asynchronously.

Parameters
Name Description
bucket String

The name of the bucket to delete. Must not be null.
options DeleteBucketOptions

Additional options for the operation. May be null, in which case appropriate defaults will be used.
cancellationToken CancellationToken

The token to monitor for cancellation requests.
Returns
Type Description
Task

A task representing the asynchronous operation.
Example

See DeleteBucket for a synchronous example.

DeleteHmacKey(String, String, DeleteHmacKeyOptions)

public virtual void DeleteHmacKey(string projectId, string accessId, DeleteHmacKeyOptions options = null)

Synchronously deletes an HMAC key, which must already have been deactivated.

Parameters
Name Description
projectId String

The ID of the project containing the HMAC key to delete.

accessId String

The ID of the HMAC key to delete. Must not be null.
options DeleteHmacKeyOptions

Additional options for the operation. May be null, in which case appropriate defaults will be used.

DeleteHmacKeyAsync(String, String, DeleteHmacKeyOptions, CancellationToken)

public virtual Task DeleteHmacKeyAsync(string projectId, string accessId, DeleteHmacKeyOptions options = null, CancellationToken cancellationToken = default(CancellationToken))

Asynchronously deletes an HMAC key, which must already have been deactivated.

Parameters
Name Description
projectId String

The ID of the project containing the HMAC key to delete.

accessId String

The ID of the HMAC key to delete. Must not be null.
options DeleteHmacKeyOptions

Additional options for the operation. May be null, in which case appropriate defaults will be used.
cancellationToken CancellationToken

The token to monitor for cancellation requests.
Returns
Type Description
Task

A task representing the asynchronous operation.

DeleteNotification(String, String, DeleteNotificationOptions)

public virtual void DeleteNotification(string bucket, string notificationId, DeleteNotificationOptions options = null)

Deletes a notification configuration.

Parameters
Name Description
bucket String

The bucket associated with the notification configuration. Must not be null.
notificationId String

ID of the notification configuration to delete. Must not be null.
options DeleteNotificationOptions

The options for the operation. May be null, in which case defaults will be supplied.
Example 
StorageClient client = StorageClient.Create();
client.DeleteNotification(bucket, notificationId);

DeleteNotificationAsync(String, String, DeleteNotificationOptions, CancellationToken)

public virtual Task DeleteNotificationAsync(string bucket, string notificationId, DeleteNotificationOptions options = null, CancellationToken cancellationToken = default(CancellationToken))

Asynchronously deletes a notification configuration.

Parameters
Name Description
bucket String

The bucket associated with the notification configuration. Must not be null.
notificationId String

ID of the notification configuration to delete. Must not be null.
options DeleteNotificationOptions

The options for the operation. May be null, in which case defaults will be supplied.
cancellationToken CancellationToken

The token to monitor for cancellation requests.
Returns
Type Description
Task

A task representing the asynchronous operation.
Example

See DeleteNotification for a synchronous example.

DeleteObject(Object, DeleteObjectOptions)

public virtual void DeleteObject(Object obj, DeleteObjectOptions options = null)

Deletes a version of the specified object synchronously.

Parameters
Name Description
obj Object

Object to delete. Must not be null, and must have the name and bucket populated.
options DeleteObjectOptions

Additional options for the operation. May be null, in which case appropriate defaults will be used.
Remarks

By default this will delete the latest version of the object, but this can be controlled using Generation. Note that any generation information contained within obj is ignored; the generation to delete is only controlled via options. For buckets that support multiple versions, implicitly deleting the latest version only archives it so the object is still available and can be listed by specifying Versions. If the version is explicitly specified, the object is permanently deleted.

If the bucket containing the object supports versioning, after this operation completes successfully there may still be another version of the same object. In buckets which do not support versioning, this operation will permanently delete the object.

If the request attempts to delete an object that does not exist or a specific version that does not exist, this counts as a failure with an HTTP status code of 404.

Example

See DeleteObject for an example using an alternative overload.

DeleteObject(String, String, DeleteObjectOptions)

public virtual void DeleteObject(string bucket, string objectName, DeleteObjectOptions options = null)

Deletes a version of the specified object synchronously.

Parameters
Name Description
bucket String

The name of the bucket containing the object. Must not be null.
objectName String

The name of the object within the bucket. Must not be null.
options DeleteObjectOptions

Additional options for the operation. May be null, in which case appropriate defaults will be used.
Remarks

By default this will delete the latest version of the object, but this can be controlled using Generation. For buckets that support multiple versions, implicitly deleting the latest version only archives it so the object is still available and can be listed by specifying Versions. If the version is explicitly specified, the object is permanently deleted.

If the bucket containing the object supports versioning, after this operation completes successfully there may still be another version of the same object. In buckets which do not support versioning, this operation will permanently delete the object.

If the request attempts to delete an object that does not exist or a specific version that does not exist, this counts as a failure with an HTTP status code of 404.

Example 
var client = StorageClient.Create();
var objectName = "places/deleteme.txt";

client.DeleteObject(bucketName, objectName);

DeleteObjectAsync(Object, DeleteObjectOptions, CancellationToken)

public virtual Task DeleteObjectAsync(Object obj, DeleteObjectOptions options = null, CancellationToken cancellationToken = default(CancellationToken))

Deletes a version of the specified object asynchronously.

Parameters
Name Description
obj Object

Object to delete. Must not be null, and must have the name and bucket populated.
options DeleteObjectOptions

Additional options for the operation. May be null, in which case appropriate defaults will be used.
cancellationToken CancellationToken

The token to monitor for cancellation requests.
Returns
Type Description
Task

A task representing the asynchronous operation.
Remarks

By default this will delete the latest version of the object, but this can be controlled using Generation. Note that any generation information contained within obj is ignored; the generation to delete is only controlled via options. For buckets that support multiple versions, implicitly deleting the latest version only archives it so the object is still available and can be listed by specifying Versions. If the version is explicitly specified, the object is permanently deleted.

If the bucket containing the object supports versioning, after this operation completes successfully there may still be another version of the same object. In buckets which do not support versioning, this operation will permanently delete the object.

If the request attempts to delete an object that does not exist or a specific version that does not exist, this counts as a failure with an HTTP status code of 404.

Example

See DeleteObject for a synchronous example.

DeleteObjectAsync(String, String, DeleteObjectOptions, CancellationToken)

public virtual Task DeleteObjectAsync(string bucket, string objectName, DeleteObjectOptions options = null, CancellationToken cancellationToken = default(CancellationToken))

Deletes a version of the specified object asynchronously.

Parameters
Name Description
bucket String

The name of the bucket containing the object. Must not be null.
objectName String

The name of the object within the bucket. Must not be null.
options