google-cloud-storage 1.18.1 → 1.44.0

data/lib/google/cloud/storage/project.rb

@@ -21,6 +21,7 @@ require "google/cloud/storage/bucket"
 require "google/cloud/storage/bucket/cors"
 require "google/cloud/storage/bucket/lifecycle"
 require "google/cloud/storage/file"
+require "google/cloud/storage/hmac_key"
 
 module Google
   module Cloud
@@ -164,6 +165,11 @@ module Google
         #   without verifying the bucket resource exists on the Storage service.
         #   Calls made on this object will raise errors if the bucket resource
         #   does not exist. Default is `false`.
+        # @param [Integer] if_metageneration_match Makes the operation conditional
+        #   on whether the bucket's current metageneration matches the given value.
+        # @param [Integer] if_metageneration_not_match Makes the operation
+        #   conditional on whether the bucket's current metageneration does not
+        #   match the given value.
         # @param [Boolean, String] user_project If this parameter is set to
         #   `true`, transit costs for operations on the requested bucket or a
         #   file it contains will be billed to the current project for this
@@ -207,12 +213,19 @@ module Google
         #                           user_project: "my-other-project"
         #   files = bucket.files # Billed to "my-other-project"
         #
-        def bucket bucket_name, skip_lookup: false, user_project: nil
+        def bucket bucket_name,
+                   skip_lookup: false,
+                   if_metageneration_match: nil,
+                   if_metageneration_not_match: nil,
+                   user_project: nil
           if skip_lookup
             return Bucket.new_lazy bucket_name, service,
                                    user_project: user_project
           end
-          gapi = service.get_bucket bucket_name, user_project: user_project
+          gapi = service.get_bucket bucket_name,
+                                    if_metageneration_match: if_metageneration_match,
+                                    if_metageneration_not_match: if_metageneration_not_match,
+                                    user_project: user_project
           Bucket.from_gapi gapi, service, user_project: user_project
         rescue Google::Cloud::NotFoundError
           nil
@@ -232,11 +245,9 @@ module Google
         # for the bucket, including a block that defines CORS rule. See
         # {Bucket::Cors} for details.
         #
-        # Before enabling Bucket Policy Only (see {Bucket#policy_only=}) please
-        # review [feature
-        # documentation](https://cloud.google.com/storage/docs/bucket-policy-only),
-        # as well as [Should you use Bucket Policy
-        # Only?](https://cloud.google.com/storage/docs/bucket-policy-only#should-you-use).
+        # Before enabling uniform bucket-level access (see
+        # {Bucket#uniform_bucket_level_access=}) please review [uniform bucket-level
+        # access](https://cloud.google.com/storage/docs/uniform-bucket-level-access).
         #
         # @see https://cloud.google.com/storage/docs/cross-origin Cross-Origin
         #   Resource Sharing (CORS)
@@ -277,12 +288,11 @@ module Google
         #     roles.
         #   * `public`, `public_read`, `publicRead` - File owner gets OWNER
         #     access, and allUsers get READER access.
-        # @param [String] location The location of the bucket. Object data for
-        #   objects in the bucket resides in physical storage within this
-        #   region. Possible values include `ASIA`, `EU`, and `US`. (See the
-        #   [developer's
-        #   guide](https://cloud.google.com/storage/docs/bucket-locations) for
-        #   the authoritative list. The default value is `US`.
+        # @param [String] location The location of the bucket. Optional.
+        #   If not passed, the default location, 'US', will be used.
+        #   If specifying a dual-region location, the `customPlacementConfig`
+        #   property should be set in conjunction. See:
+        #   [Storage Locations](https://cloud.google.com/storage/docs/locations).
         # @param [String] logging_bucket The destination bucket for the bucket's
         #   logs. For more information, see [Access
         #   Logs](https://cloud.google.com/storage/docs/access-logs).
@@ -295,13 +305,11 @@ module Google
         #   Logs](https://cloud.google.com/storage/docs/access-logs).
         # @param [Symbol, String] storage_class Defines how objects in the
         #   bucket are stored and determines the SLA and the cost of storage.
-        #   Accepted values include `:multi_regional`, `:regional`, `:nearline`,
-        #   and `:coldline`, as well as the equivalent strings returned by
+        #   Accepted values include `:standard`, `:nearline`, `:coldline`, and
+        #   `:archive`, as well as the equivalent strings returned by
         #   {Bucket#storage_class}. For more information, see [Storage
         #   Classes](https://cloud.google.com/storage/docs/storage-classes). The
-        #   default value is the Standard storage class, which is equivalent to
-        #   `:multi_regional` or `:regional` depending on the bucket's location
-        #   settings.
+        #   default value is the `:standard` storage class.
         # @param [Boolean] versioning Whether [Object
         #   Versioning](https://cloud.google.com/storage/docs/object-versioning)
         #   is to be enabled for the bucket. The default value is `false`.
@@ -319,6 +327,11 @@ module Google
         #   other than the current project, and that project is authorized for
         #   the currently authenticated service account, transit costs will be
         #   billed to the given project. The default is `nil`.
+        # @param [Boolean] autoclass_enabled The bucket's autoclass configuration.
+        #   Buckets can have either StorageClass OLM rules or Autoclass, but
+        #   not both. When Autoclass is enabled on a bucket, adding StorageClass
+        #   OLM rules will result in failure. For more information, see
+        #   [Autoclass](https://cloud.google.com/storage/docs/autoclass).
         #
         #   The value provided will be applied to all operations on the returned
         #   bucket instance and its files.
@@ -355,19 +368,31 @@ module Google
         #     b.lifecycle.add_set_storage_class_rule "COLDLINE", age: 10
         #   end
         #
-        def create_bucket bucket_name, acl: nil, default_acl: nil,
-                          location: nil, storage_class: nil,
-                          logging_bucket: nil, logging_prefix: nil,
-                          website_main: nil, website_404: nil, versioning: nil,
-                          requester_pays: nil, user_project: nil
-          new_bucket = Google::Apis::StorageV1::Bucket.new({
+        def create_bucket bucket_name,
+                          acl: nil,
+                          default_acl: nil,
+                          location: nil,
+                          custom_placement_config: nil,
+                          storage_class: nil,
+                          logging_bucket: nil,
+                          logging_prefix: nil,
+                          website_main: nil,
+                          website_404: nil,
+                          versioning: nil,
+                          requester_pays: nil,
+                          user_project: nil,
+                          autoclass_enabled: false
+          params = {
             name: bucket_name,
-            location: location
-          }.delete_if { |_, v| v.nil? })
+            location: location,
+            custom_placement_config: custom_placement_config
+          }.delete_if { |_, v| v.nil? }
+          new_bucket = Google::Apis::StorageV1::Bucket.new(**params)
           storage_class = storage_class_for storage_class
           updater = Bucket::Updater.new(new_bucket).tap do |b|
             b.logging_bucket = logging_bucket unless logging_bucket.nil?
             b.logging_prefix = logging_prefix unless logging_prefix.nil?
+            b.autoclass_enabled = autoclass_enabled
             b.storage_class = storage_class unless storage_class.nil?
             b.website_main = website_main unless website_main.nil?
             b.website_404 = website_404 unless website_404.nil?
@@ -384,6 +409,91 @@ module Google
           Bucket.from_gapi gapi, service, user_project: user_project
         end
 
+        ##
+        # Creates a new HMAC key.
+        #
+        # @param [String] service_account_email The email address of the service
+        #   account. Used to create the HMAC key.
+        # @param [String] project_id The project ID associated with
+        #   `service_account_email`, if `service_account_email` belongs to a
+        #   project other than the currently authenticated project. Optional. If
+        #   not provided, the project ID for the current project will be used.
+        # @param [String] user_project If this parameter is set to a project ID
+        #   other than the current project, and that project is authorized for
+        #   the currently authenticated service account, transit costs will be
+        #   billed to the given project. The default is `nil`.
+        #
+        # @return [Google::Cloud::Storage::HmacKey]
+        #
+        def create_hmac_key service_account_email, project_id: nil,
+                            user_project: nil
+          gapi = service.create_hmac_key service_account_email,
+                                         project_id: project_id,
+                                         user_project: user_project
+          HmacKey.from_gapi gapi, service, user_project: user_project
+        end
+
+        ##
+        # Retrieves an HMAC key's metadata; the key's secret is not included in
+        # the representation.
+        #
+        # @param [String] project_id The project ID associated with the
+        #   `service_account_email` used to create the HMAC key, if the
+        #   service account email belongs to a project other than the
+        #   currently authenticated project. Optional. If not provided, the
+        #   project ID for current project will be used.
+        # @param [String] user_project If this parameter is set to a project ID
+        #   other than the current project, and that project is authorized for
+        #   the currently authenticated service account, transit costs will be
+        #   billed to the given project. The default is `nil`.
+        #
+        # @return [Google::Cloud::Storage::HmacKey]
+        #
+        def hmac_key access_id, project_id: nil, user_project: nil
+          gapi = service.get_hmac_key \
+            access_id, project_id: project_id, user_project: user_project
+          HmacKey.from_gapi_metadata gapi, service, user_project: user_project
+        end
+
+        ##
+        # Retrieves a list of HMAC key metadata matching the criteria; the keys'
+        # secrets are not included.
+        #
+        # @param [String] service_account_email
+        #   If present, only keys for the given service account are returned.
+        # @param [String] project_id The project ID associated with the
+        #   `service_account_email` used to create the HMAC keys, if the
+        #   service account email belongs to a project other than the
+        #   currently authenticated project. Optional. If not provided, the
+        #   project ID for current project will be used.
+        # @param [Boolean] show_deleted_keys
+        #   Whether to include keys in the `DELETED` state. The default value is
+        #   false.
+        # @param [String] token A previously-returned page token representing
+        #   part of the larger set of results to view.
+        # @param [Integer] max Maximum number of keys to return.
+        # @param [String] user_project If this parameter is set to a project ID
+        #   other than the current project, and that project is authorized for
+        #   the currently authenticated service account, transit costs will be
+        #   billed to the given project. The default is `nil`.
+        #
+        # @return [Google::Cloud::Storage::HmacKey]
+        #
+        def hmac_keys service_account_email: nil, project_id: nil,
+                      show_deleted_keys: nil, token: nil, max: nil,
+                      user_project: nil
+          gapi = service.list_hmac_keys \
+            max: max, token: token,
+            service_account_email: service_account_email,
+            project_id: project_id, show_deleted_keys: show_deleted_keys,
+            user_project: user_project
+
+          HmacKey::List.from_gapi \
+            gapi, service,
+            service_account_email: nil, show_deleted_keys: nil,
+            max: max, user_project: user_project
+        end
+
         ##
         # Generates a signed URL. See [Signed
         # URLs](https://cloud.google.com/storage/docs/access-control/signed-urls)
@@ -400,7 +510,7 @@ module Google
         # A {SignedUrlUnavailable} is raised if the service account credentials
         # are missing. Service account credentials are acquired by following the
         # steps in [Service Account Authentication](
-        # https://cloud.google.com/storage/docs/authentication#service_accounts).
+        # https://cloud.google.com/iam/docs/service-accounts).
         #
         # @see https://cloud.google.com/storage/docs/access-control/signed-urls
         #   Signed URLs guide
@@ -428,10 +538,22 @@ module Google
         #   use the signed URL.
         # @param [String] issuer Service Account's Client Email.
         # @param [String] client_email Service Account's Client Email.
-        # @param [OpenSSL::PKey::RSA, String] signing_key Service Account's
-        #   Private Key.
-        # @param [OpenSSL::PKey::RSA, String] private_key Service Account's
-        #   Private Key.
+        # @param [OpenSSL::PKey::RSA, String, Proc] signing_key Service Account's
+        #   Private Key or a Proc that accepts a single String parameter and returns a
+        #   RSA SHA256 signature using a valid Google Service Account Private Key.
+        # @param [OpenSSL::PKey::RSA, String, Proc] private_key Service Account's
+        #   Private Key or a Proc that accepts a single String parameter and returns a
+        #   RSA SHA256 signature using a valid Google Service Account Private Key.
+        # @param [OpenSSL::PKey::RSA, String, Proc] signer Service Account's
+        #   Private Key or a Proc that accepts a single String parameter and returns a
+        #   RSA SHA256 signature using a valid Google Service Account Private Key.
+        #
+        #   When using this method in environments such as GAE Flexible Environment,
+        #   GKE, or Cloud Functions where the private key is unavailable, it may be
+        #   necessary to provide a Proc (or lambda) via the signer parameter. This
+        #   Proc should return a signature created using a RPC call to the
+        #   [Service Account Credentials signBlob](https://cloud.google.com/iam/docs/reference/credentials/rest/v1/projects.serviceAccounts/signBlob)
+        #   method as shown in the example below.
         # @param [Hash] query Query string parameters to include in the signed
         #   URL. The given parameters are not verified by the signature.
         #
@@ -440,11 +562,29 @@ module Google
         #   using the URL, but only when the file resource is missing the
         #   corresponding values. (These values can be permanently set using
         #   {File#content_disposition=} and {File#content_type=}.)
+        # @param [String] scheme The URL scheme. The default value is `HTTPS`.
+        # @param [Boolean] virtual_hosted_style Whether to use a virtual hosted-style
+        #   hostname, which adds the bucket into the host portion of the URI rather
+        #   than the path, e.g. `https://mybucket.storage.googleapis.com/...`.
+        #   For V4 signing, this also sets the `host` header in the canonicalized
+        #   extension headers to the virtual hosted-style host, unless that header is
+        #   supplied via the `headers` param. The default value of `false` uses the
+        #   form of `https://storage.googleapis.com/mybucket`.
+        # @param [String] bucket_bound_hostname Use a bucket-bound hostname, which
+        #   replaces the `storage.googleapis.com` host with the name of a `CNAME`
+        #   bucket, e.g. a bucket named `gcs-subdomain.my.domain.tld`, or a Google
+        #   Cloud Load Balancer which routes to a bucket you own, e.g.
+        #   `my-load-balancer-domain.tld`.
         # @param [Symbol, String] version The version of the signed credential
         #   to create. Must be one of `:v2` or `:v4`. The default value is
         #   `:v2`.
         #
-        # @return [String]
+        # @return [String] The signed URL.
+        #
+        # @raise [SignedUrlUnavailable] If the service account credentials
+        #   are missing. Service account credentials are acquired by following the
+        #   steps in [Service Account Authentication](
+        #   https://cloud.google.com/iam/docs/service-accounts).
         #
         # @example
         #   require "google/cloud/storage"
@@ -479,6 +619,41 @@ module Google
         #                                   issuer: issuer_email,
         #                                   signing_key: key
         #
+        # @example Using Cloud IAMCredentials signBlob to create the signature:
+        #   require "google/cloud/storage"
+        #   require "google/apis/iamcredentials_v1"
+        #   require "googleauth"
+        #
+        #   # Issuer is the service account email that the Signed URL will be signed with
+        #   # and any permission granted in the Signed URL must be granted to the
+        #   # Google Service Account.
+        #   issuer = "service-account@project-id.iam.gserviceaccount.com"
+        #
+        #   # Create a lambda that accepts the string_to_sign
+        #   signer = lambda do |string_to_sign|
+        #     IAMCredentials = Google::Apis::IamcredentialsV1
+        #     iam_client = IAMCredentials::IAMCredentialsService.new
+        #
+        #     # Get the environment configured authorization
+        #     scopes = ["https://www.googleapis.com/auth/iam"]
+        #     iam_client.authorization = Google::Auth.get_application_default scopes
+        #
+        #     request = Google::Apis::IamcredentialsV1::SignBlobRequest.new(
+        #       payload: string_to_sign
+        #     )
+        #     resource = "projects/-/serviceAccounts/#{issuer}"
+        #     response = iam_client.sign_service_account_blob resource, request
+        #     response.signed_blob
+        #   end
+        #
+        #   storage = Google::Cloud::Storage.new
+        #
+        #   bucket_name = "my-todo-app"
+        #   file_path = "avatars/heidi/400x400.png"
+        #   url = storage.signed_url bucket_name, file_path,
+        #                            method: "GET", issuer: issuer,
+        #                            signer: signer
+        #
         # @example Using the `headers` option:
         #   require "google/cloud/storage"
         #
@@ -509,28 +684,52 @@ module Google
         #   # Send the `x-goog-resumable:start` header and the content type
         #   # with the resumable upload POST request.
         #
-        def signed_url bucket, path, method: nil, expires: nil,
-                       content_type: nil, content_md5: nil, headers: nil,
-                       issuer: nil, client_email: nil, signing_key: nil,
-                       private_key: nil, query: nil, version: nil
+        def signed_url bucket,
+                       path,
+                       method: "GET",
+                       expires: nil,
+                       content_type: nil,
+                       content_md5: nil,
+                       headers: nil,
+                       issuer: nil,
+                       client_email: nil,
+                       signing_key: nil,
+                       private_key: nil,
+                       signer: nil,
+                       query: nil,
+                       scheme: "HTTPS",
+                       virtual_hosted_style: nil,
+                       bucket_bound_hostname: nil,
+                       version: nil
           version ||= :v2
           case version.to_sym
           when :v2
-            signer = File::SignerV2.new bucket, path, service
-
-            signer.signed_url method: method, expires: expires,
-                              headers: headers, content_type: content_type,
-                              content_md5: content_md5, issuer: issuer,
-                              client_email: client_email,
-                              signing_key: signing_key,
-                              private_key: private_key, query: query
+            sign = File::SignerV2.new bucket, path, service
+            sign.signed_url method: method,
+                            expires: expires,
+                            headers: headers,
+                            content_type: content_type,
+                            content_md5: content_md5,
+                            issuer: issuer,
+                            client_email: client_email,
+                            signing_key: signing_key,
+                            private_key: private_key,
+                            signer: signer,
+                            query: query
           when :v4
-            signer = File::SignerV4.new bucket, path, service
-            signer.signed_url method: method, expires: expires,
-                              headers: headers, issuer: issuer,
-                              client_email: client_email,
-                              signing_key: signing_key,
-                              private_key: private_key, query: query
+            sign = File::SignerV4.new bucket, path, service
+            sign.signed_url method: method,
+                            expires: expires,
+                            headers: headers,
+                            issuer: issuer,
+                            client_email: client_email,
+                            signing_key: signing_key,
+                            private_key: private_key,
+                            signer: signer,
+                            query: query,
+                            scheme: scheme,
+                            virtual_hosted_style: virtual_hosted_style,
+                            bucket_bound_hostname: bucket_bound_hostname
           else
             raise ArgumentError, "version '#{version}' not supported"
           end