Skip to content

Commit ac1ba66

Browse files
mziccardmziccard
committed
Add more detailed javadoc to Blob and Storage signUrl
1 parent 0d38c67 commit ac1ba66

2 files changed

Lines changed: 56 additions & 7 deletions

File tree

‎gcloud-java-storage/src/main/java/com/google/gcloud/storage/Blob.java‎

Lines changed: 29 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@
2222

2323
import com.google.api.services.storage.model.StorageObject;
2424
import com.google.common.base.Function;
25+
import com.google.gcloud.AuthCredentials;
2526
import com.google.gcloud.ReadChannel;
2627
import com.google.gcloud.WriteChannel;
2728
import com.google.gcloud.storage.Storage.BlobTargetOption;
@@ -456,13 +457,40 @@ public WriteChannel writer(BlobWriteOption... options) {
456457
* Generates a signed URL for this blob. If you want to allow access to for a fixed amount of time
457458
* for this blob, you can use this method to generate a URL that is only valid within a certain
458459
* time period. This is particularly useful if you don't want publicly accessible blobs, but don't
459-
* want to require users to explicitly log in.
460+
* want to require users to explicitly log in. Signing a URL requires a service account
461+
* and its associated key. If a {@link AuthCredentials.ServiceAccountAuthCredentials} was passed
462+
* to {@link StorageOptions.Builder#authCredentials(AuthCredentials)} or the default credentials
463+
* are being used and the environment variable {@code GOOGLE_APPLICATION_CREDENTIALS} is set, then
464+
* {@code signUrl} will use that service account and associated key to sign the URL. If this
465+
* is not the case, a service account with associated key can be passed to {@code signUrl} using
466+
* the {@link SignUrlOption#serviceAccount(AuthCredentials.ServiceAccountAuthCredentials)} option.
467+
*
468+
* <p>Example usage of creating a signed URL that is valid for 2 weeks:
469+
* <pre> {@code
470+
* blob.signUrl(14, TimeUnit.DAYS);
471+
* }</pre>
472+
*
473+
* <p>Example usage of creating a signed URL passing the {@code SignUrlOption.serviceAccount()}
474+
* option:
475+
* <pre> {@code
476+
* blob.signUrl(14, TimeUnit.DAYS, SignUrlOption.serviceAccount(
477+
* AuthCredentials.createForJson(new FileInputStream("/path/to/key.json"))));
478+
* }</pre>
460479
*
461480
* @param duration time until the signed URL expires, expressed in {@code unit}. The finer
462481
* granularity supported is 1 second, finer granularities will be truncated
463482
* @param unit time unit of the {@code duration} parameter
464483
* @param options optional URL signing options
465484
* @return a signed URL for this bucket and the specified options
485+
* @throws IllegalArgumentException if
486+
* {@link SignUrlOption#serviceAccount(AuthCredentials.ServiceAccountAuthCredentials)} was not
487+
* used and no service account was provided to {@link StorageOptions}
488+
* @throws IllegalArgumentException if the key associated to the provided service account is
489+
* invalid
490+
* @throws IllegalArgumentException if {@link SignUrlOption#withMd5()} option is used and
491+
* {@link #md5()} is {@code null}
492+
* @throws IllegalArgumentException if {@link SignUrlOption#withContentType()} option is used and
493+
* {@link #contentType()} is {@code null}
466494
* @see <a href="https://cloud.google.com/storage/docs/access-control#Signed-URLs">Signed-URLs</a>
467495
*/
468496
public URL signUrl(long duration, TimeUnit unit, SignUrlOption... options) {

‎gcloud-java-storage/src/main/java/com/google/gcloud/storage/Storage.java‎

Lines changed: 27 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@
2424
import com.google.common.collect.Iterables;
2525
import com.google.common.collect.Lists;
2626
import com.google.common.collect.Sets;
27+
import com.google.gcloud.AuthCredentials;
2728
import com.google.gcloud.AuthCredentials.ServiceAccountAuthCredentials;
2829
import com.google.gcloud.Page;
2930
import com.google.gcloud.ReadChannel;
@@ -1476,23 +1477,43 @@ private static void checkContentType(BlobInfo blobInfo) throws IllegalArgumentEx
14761477
WriteChannel writer(BlobInfo blobInfo, BlobWriteOption... options);
14771478

14781479
/**
1479-
* Generates a signed URL for a blob.
1480-
* If you have a blob that you want to allow access to for a fixed
1481-
* amount of time, you can use this method to generate a URL that
1482-
* is only valid within a certain time period.
1483-
* This is particularly useful if you don't want publicly
1484-
* accessible blobs, but don't want to require users to explicitly log in.
1480+
* Generates a signed URL for a blob. If you have a blob that you want to allow access to for a
1481+
* fixed amount of time, you can use this method to generate a URL that is only valid within a
1482+
* certain time period. This is particularly useful if you don't want publicly accessible blobs,
1483+
* but don't want to require users to explicitly log in. Signing a URL requires a service account
1484+
* and its associated key. If a {@link ServiceAccountAuthCredentials} was passed to
1485+
* {@link StorageOptions.Builder#authCredentials(AuthCredentials)} or the default credentials are
1486+
* being used and the environment variable {@code GOOGLE_APPLICATION_CREDENTIALS} is set, then
1487+
* {@code signUrl} will use that service account and associated key to sign the URL. If this
1488+
* is not the case, a service account with associated key can be passed to {@code signUrl} using
1489+
* the {@code SignUrlOption.serviceAccount()} option.
14851490
*
14861491
* <p>Example usage of creating a signed URL that is valid for 2 weeks:
14871492
* <pre> {@code
14881493
* service.signUrl(BlobInfo.builder("bucket", "name").build(), 14, TimeUnit.DAYS);
14891494
* }</pre>
14901495
*
1496+
* <p>Example usage of creating a signed URL passing the {@code SignUrlOption.serviceAccount()}
1497+
* option:
1498+
* <pre> {@code
1499+
* service.signUrl(BlobInfo.builder("bucket", "name").build(), 14, TimeUnit.DAYS,
1500+
* SignUrlOption.serviceAccount(
1501+
* AuthCredentials.createForJson(new FileInputStream("/path/to/key.json"))));
1502+
* }</pre>
1503+
*
14911504
* @param blobInfo the blob associated with the signed URL
14921505
* @param duration time until the signed URL expires, expressed in {@code unit}. The finest
14931506
* granularity supported is 1 second, finer granularities will be truncated
14941507
* @param unit time unit of the {@code duration} parameter
14951508
* @param options optional URL signing options
1509+
* @throws IllegalArgumentException if {@code SignUrlOption.serviceAccount()} was not used and no
1510+
* service account was provided to {@link StorageOptions}
1511+
* @throws IllegalArgumentException if the key associated to the provided service account is
1512+
* invalid
1513+
* @throws IllegalArgumentException if {@code SignUrlOption.withMd5()} option is used and
1514+
* {@code blobInfo.md5()} is {@code null}
1515+
* @throws IllegalArgumentException if {@code SignUrlOption.withContentType()} option is used and
1516+
* {@code blobInfo.contentType()} is {@code null}
14961517
* @see <a href="https://cloud.google.com/storage/docs/access-control#Signed-URLs">Signed-URLs</a>
14971518
*/
14981519
URL signUrl(BlobInfo blobInfo, long duration, TimeUnit unit, SignUrlOption... options);

0 commit comments

Comments
 (0)