public sealed class UrlSigner
Reference documentation and code samples for the Google Cloud Storage v1 API class UrlSigner.
Class which helps create signed URLs which can be used to provide limited access to specific buckets and objects to anyone in possession of the URL, regardless of whether they have a Google account.
Namespace
GoogleGoogle.CloudGoogle.Cloud.StorageV1Assembly
Google.Cloud.Storage.V1.dll
Remarks
See https://cloud.google.com/storage/docs/access-control/signed-urls for more information on signed URLs.
Properties
ResumableHttpMethod
public static HttpMethod ResumableHttpMethod { get; }
Gets a special HTTP method which can be used to create a signed URL for initiating a resumable upload. See https://cloud.google.com/storage/docs/access-control/signed-urls#signing-resumable for more information.
Property Value | |
---|---|
Type | Description |
HttpMethod |
Note: When using the RESUMABLE method to create a signed URL, a URL will actually be signed for the POST method with a header of 'x-goog-resumable:start'. The caller must perform a POST request with this URL and specify the 'x-goog-resumable:start' header as well or signature validation will fail.
Methods
FromBlobSigner(IBlobSigner)
public static UrlSigner FromBlobSigner(UrlSigner.IBlobSigner signer)
Creates a new UrlSigner instance for a custom blob signer.
Parameter | |
---|---|
Name | Description |
signer | UrlSignerIBlobSigner The blob signer to use. Must not be null. |
Returns | |
---|---|
Type | Description |
UrlSigner | A new UrlSigner using the specified blob signer. |
FromCredential(ComputeCredential)
public static UrlSigner FromCredential(ComputeCredential credential)
Creates a new UrlSigner instance for a compute credential.
Parameter | |
---|---|
Name | Description |
credential | ComputeCredential The compute credential. Must not be null. |
Returns | |
---|---|
Type | Description |
UrlSigner |
A request to the IAM API is executed for signing which increases latency as compared with FromCredential(ServiceAccountCredential) and that counts towards IAM API quoata consumption.
The first time a compute credential is used for signing, a request to the metadata server is executed, to obtain the associated service account ID, which may increase latency of the overall signing request.
FromCredential(GoogleCredential)
public static UrlSigner FromCredential(GoogleCredential credential)
Creates a new UrlSigner instance for a Google credential if the wrapped credential type is supported for signing. In that case, this method relies on the appropiate UrlSigner.FromCredential overload.
Parameter | |
---|---|
Name | Description |
credential | GoogleCredential The Google credential. Must not be null. Must wrap a credential currently supported for signing. |
Returns | |
---|---|
Type | Description |
UrlSigner |
Please see the specific UrlSigner.FromCredential overloads for more information.
Exceptions | |
---|---|
Type | Description |
InvalidOperationException | The credential wrapped by the Google credential is not currently supported for signing. |
FromCredential(ImpersonatedCredential)
public static UrlSigner FromCredential(ImpersonatedCredential credential)
Creates a new UrlSigner instance for an impersonated credential. Signing is done by the impersonated service account.
Parameter | |
---|---|
Name | Description |
credential | ImpersonatedCredential The impersonated credential. Must not be null. |
Returns | |
---|---|
Type | Description |
UrlSigner |
A request to the IAM API is executed for signing which increases latency as compared with FromCredential(ServiceAccountCredential) and that counts towards IAM API quoata consumption.
FromCredential(ServiceAccountCredential)
public static UrlSigner FromCredential(ServiceAccountCredential credential)
Creates a new UrlSigner instance for a service account.
Parameter | |
---|---|
Name | Description |
credential | ServiceAccountCredential The credential for the a service account. Must not be null. |
Returns | |
---|---|
Type | Description |
UrlSigner |
Signing happens locally using the private key included on the service account credential.
FromCredentialFile(string)
public static UrlSigner FromCredentialFile(string credentialFilePath)
Creates a new UrlSigner instance from the JSON configuration file of a Google credential. See FromCredential(GoogleCredential) for more information about supported credential types.
Parameter | |
---|---|
Name | Description |
credentialFilePath | string |
Returns | |
---|---|
Type | Description |
UrlSigner |
FromCredentialFileAsync(string, CancellationToken)
public static Task<UrlSigner> FromCredentialFileAsync(string credentialFilePath, CancellationToken cancellationToken = default)
Creates a new UrlSigner instance from the JSON configuration file of a Google credential, which is read asyncrhonously. See FromCredential(GoogleCredential) for more information about supported credential types.
Parameters | |
---|---|
Name | Description |
credentialFilePath | string |
cancellationToken | CancellationToken |
Returns | |
---|---|
Type | Description |
TaskUrlSigner |
FromCredentialStream(Stream)
public static UrlSigner FromCredentialStream(Stream credentialData)
Creates a new UrlSigner instance from a Stream containing the JSON configuration file of a Google Credential. See FromCredential(GoogleCredential) for more information about supported credential types.
Parameter | |
---|---|
Name | Description |
credentialData | Stream |
Returns | |
---|---|
Type | Description |
UrlSigner |
FromCredentialStreamAsync(Stream, CancellationToken)
public static Task<UrlSigner> FromCredentialStreamAsync(Stream credentialData, CancellationToken cancellationToken = default)
Creates a new UrlSigner instance from a Stream containing the JSON configuration file of a Google Credential. The data is read asynchronously. See FromCredential(GoogleCredential) for more information about supported credential types.
Parameters | |
---|---|
Name | Description |
credentialData | Stream |
cancellationToken | CancellationToken |
Returns | |
---|---|
Type | Description |
TaskUrlSigner |
FromServiceAccountCredential(ServiceAccountCredential)
[Obsolete("Use FromCredential(ServiceAccountCredential) which is equivalent.")]
public static UrlSigner FromServiceAccountCredential(ServiceAccountCredential credential)
Creates a new UrlSigner instance for a service account.
Parameter | |
---|---|
Name | Description |
credential | ServiceAccountCredential The credential for the a service account. Must not be null. |
Returns | |
---|---|
Type | Description |
UrlSigner |
FromServiceAccountData(Stream)
[Obsolete("Use FromCredentialStream(Stream) which is equivalent.")]
public static UrlSigner FromServiceAccountData(Stream credentialData)
Creates a new UrlSigner instance for a service account.
Parameter | |
---|---|
Name | Description |
credentialData | Stream The stream from which to read the JSON key data for a service account. Must not be null. |
Returns | |
---|---|
Type | Description |
UrlSigner |
Exceptions | |
---|---|
Type | Description |
InvalidOperationException | The |
FromServiceAccountPath(string)
[Obsolete("Use FromCredentialFile(string) which is equivalent.")]
public static UrlSigner FromServiceAccountPath(string credentialFilePath)
Creates a new UrlSigner instance for a service account.
Parameter | |
---|---|
Name | Description |
credentialFilePath | string The path to the JSON key file for a service account. Must not be null. |
Returns | |
---|---|
Type | Description |
UrlSigner |
Exceptions | |
---|---|
Type | Description |
InvalidOperationException | The |
Sign(PostPolicy, Options)
public UrlSigner.SignedPostPolicy Sign(UrlSigner.PostPolicy postPolicy, UrlSigner.Options options)
Signs the given post policy. The result can be used to make form posting requests matching the conditions set in the post policy.
Parameters | |
---|---|
Name | Description |
postPolicy | UrlSignerPostPolicy The post policy to signed and that will be enforced when making the post request. Must not be null. |
options | UrlSignerOptions The options used to generate the signed post policy. Must not be null. |
Returns | |
---|---|
Type | Description |
UrlSignerSignedPostPolicy | The signed post policy, which contains all the fields that should be including in the form to post. |
Signing post policies is not supported by V2. A NotSupportedException will be thrown if an attempt is made to sign a post policy using V2.
When a UrlSigner is created with a service account credential, the signing can be performed with no network access. When it is created with an implementation of UrlSigner.IBlobSigner, that may require network access or other IO. In that case, one of the asynchronous methods should be used when the caller is in a context that should not block.
See https://cloud.google.com/storage/docs/xml-api/post-object for more information on signed post policies.
Sign(RequestTemplate, Options)
public string Sign(UrlSigner.RequestTemplate requestTemplate, UrlSigner.Options options)
Creates a signed URL which can be used to provide limited access to specific buckets and objects to anyone in possession of the URL, regardless of whether they have a Google account.
Parameters | |
---|---|
Name | Description |
requestTemplate | UrlSignerRequestTemplate The request template that will be used to generate the signed URL for. Must not be null. |
options | UrlSignerOptions The options used to generate the signed URL. Must not be null. |
Returns | |
---|---|
Type | Description |
string | The signed URL which can be used to provide access to a bucket or object for a limited amount of time. |
When a UrlSigner is created with a service account credential, the signing can be performed with no network access. When it is created with an implementation of UrlSigner.IBlobSigner, that may require network access or other IO. In that case, one of the asynchronous methods should be used when the caller is in a context that should not block.
See https://cloud.google.com/storage/docs/access-control/signed-urls for more information on signed URLs.
See Sign for an example using an alternative overload.
Sign(string, string, TimeSpan, HttpMethod, SigningVersion?)
public string Sign(string bucket, string objectName, TimeSpan duration, HttpMethod httpMethod = null, SigningVersion? signingVersion = null)
Creates a signed URL which can be used to provide limited access to specific buckets and objects to anyone in possession of the URL, regardless of whether they have a Google account.
Parameters | |
---|---|
Name | Description |
bucket | string The name of the bucket. Must not be null. |
objectName | string The name of the object within the bucket. May be null, in which case the signed URL will refer to the bucket instead of an object. |
duration | TimeSpan The length of time for which the signed URL should remain usable. |
httpMethod | HttpMethod The HTTP request method for which the signed URL is allowed to be used. May be null, in which case GET will be used. |
signingVersion | SigningVersion The signing version to use to generate the signed URL. May be null, in which case Default will be used. |
Returns | |
---|---|
Type | Description |
string | The signed URL which can be used to provide access to a bucket or object for a limited amount of time. |
When a UrlSigner is created with a service account credential, the signing can be performed with no network access. When it is created with an implementation of UrlSigner.IBlobSigner, that may require network access or other IO. In that case, one of the asynchronous methods should be used when the caller is in a context that should not block.
See https://cloud.google.com/storage/docs/access-control/signed-urls for more information on signed URLs.
Note that when GET is specified as the httpMethod
(or it is null, in which case GET is
used), both GET and HEAD requests can be made with the created signed URL.
// Create a signed URL which can be used to get a specific object for one hour.
UrlSigner urlSigner = UrlSigner.FromCredential(credential);
string url = await urlSigner.SignAsync(bucketName, objectName, TimeSpan.FromHours(1));
// Get the content at the created URL.
HttpResponseMessage response = await httpClient.GetAsync(url);
string content = await response.Content.ReadAsStringAsync();
SignAsync(PostPolicy, Options, CancellationToken)
public Task<UrlSigner.SignedPostPolicy> SignAsync(UrlSigner.PostPolicy postPolicy, UrlSigner.Options options, CancellationToken cancellationToken = default)
Signs the given post policy. The result can be used to make form posting requests matching the conditions set in the post policy.
Parameters | |
---|---|
Name | Description |
postPolicy | UrlSignerPostPolicy The post policy to signed and that will be enforced when making the post request. Most not be null. |
options | UrlSignerOptions The options used to generate the signed post policy. Must not be null. |
cancellationToken | CancellationToken The token to monitor for cancellation requests. |
Returns | |
---|---|
Type | Description |
TaskUrlSignerSignedPostPolicy | The signed post policy, which contains all the fields that should be including in the form to post. |
Signing post policies is not supported by V2. A NotSupportedException will be thrown if an attempt is made to sign a post policy using V2.
When a UrlSigner is created with a service account credential, the signing can be performed with no network access. When it is created with an implementation of UrlSigner.IBlobSigner, that may require network access or other IO. In that case, one of the asynchronous methods should be used when the caller is in a context that should not block.
See https://cloud.google.com/storage/docs/xml-api/post-object for more information on signed post policies.
SignAsync(RequestTemplate, Options, CancellationToken)
public Task<string> SignAsync(UrlSigner.RequestTemplate requestTemplate, UrlSigner.Options options, CancellationToken cancellationToken = default)
Asynchronously creates a signed URL which can be used to provide limited access to specific buckets and objects to anyone in possession of the URL, regardless of whether they have a Google account.
Parameters | |
---|---|
Name | Description |
requestTemplate | UrlSignerRequestTemplate The request template that will be used to generate the signed URL for. Must not be null. |
options | UrlSignerOptions The options used to generate the signed URL. Must not be null. |
cancellationToken | CancellationToken The token to monitor for cancellation requests. |
Returns | |
---|---|
Type | Description |
Taskstring | A task representing the asynchronous operation, with a result returning the signed URL which can be used to provide access to a bucket or object for a limited amount of time. |
When a UrlSigner is created with a service account credential, the signing can be performed with no network access. When it is created with an implementation of UrlSigner.IBlobSigner, that may require network access or other IO. In that case, one of the asynchronous methods should be used when the caller is in a context that should not block.
See https://cloud.google.com/storage/docs/access-control/signed-urls for more information on signed URLs.
SignAsync(string, string, TimeSpan, HttpMethod, SigningVersion?, CancellationToken)
public Task<string> SignAsync(string bucket, string objectName, TimeSpan duration, HttpMethod httpMethod = null, SigningVersion? signingVersion = null, CancellationToken cancellationToken = default)
Creates a signed URL which can be used to provide limited access to specific buckets and objects to anyone in possession of the URL, regardless of whether they have a Google account.
Parameters | |
---|---|
Name | Description |
bucket | string The name of the bucket. Must not be null. |
objectName | string The name of the object within the bucket. May be null, in which case the signed URL will refer to the bucket instead of an object. |
duration | TimeSpan The length of time for which the signed URL should remain usable. |
httpMethod | HttpMethod The HTTP request method for which the signed URL is allowed to be used. May be null, in which case GET will be used. |
signingVersion | SigningVersion The signing version to use to generate the signed URL. May be null, in which case Default will be used. |
cancellationToken | CancellationToken The token to monitor for cancellation requests. |
Returns | |
---|---|
Type | Description |
Taskstring | A task representing the asynchronous operation, with a result returning the signed URL which can be used to provide access to a bucket or object for a limited amount of time. |
When a UrlSigner is created with a service account credential, the signing can be performed with no network access. When it is created with an implementation of UrlSigner.IBlobSigner, that may require network access or other IO. In that case, one of the asynchronous methods should be used when the caller is in a context that should not block.
See https://cloud.google.com/storage/docs/access-control/signed-urls for more information on signed URLs.
Note that when GET is specified as the httpMethod
(or it is null, in which case GET is
used), both GET and HEAD requests can be made with the created signed URL.