google-cloud-storage 1.4.0 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 68663d7f63e76435070cbcd4748022693d2561a5
-  data.tar.gz: cb6ecfdfaadeb41ed569d08ca9c069edf67c0ea4
+  metadata.gz: 5b7f1798224baa310d43cdd64174d46389b6c66c
+  data.tar.gz: 5cd8d77373e98f5858c430aa07592ec316bf0ab1
 SHA512:
-  metadata.gz: 1382c121c18b2cc7fa8a916895bec8c0a2b7c40a99b4fea1a54edc3562ba53b8e9f9538ea3e613f20c39572bdcc21cb2190d7a26da82240fe966901b24bf8ebb
-  data.tar.gz: 78b666563914f310968e53d4701c78781ebedae1977e1f51f6f3874ee69d23e9dfcf0b235178d0e13a0437c22fd41a12e9210577e1aa23d0ca2937b4babb0500
+  metadata.gz: 6e8caa5b4112ae3f8d8aad56157f612006eb6bb3944668c9e2f491449cf46d9fe834703863c8e372b237ad800aaa67cc60fbb92bc11662650814693127b08945
+  data.tar.gz: 8b5272dfad3534f26db99f153bae01e2a25c5931eefe7897a4a8344bda30669a3f6525f4d85581d4277c0197a3f35fa3ff096d54e6f922c180c1a77508304d7f

data/lib/google/cloud/storage.rb

@@ -488,6 +488,38 @@ module Google
     # files = bucket.files # Billed to "my-other-project"
     # ```
     #
+    # ## Configuring Pub/Sub notification subscriptions
+    #
+    # You can configure notifications to send Google Cloud Pub/Sub messages
+    # about changes to files in your buckets. For example, you can track files
+    # that are created and deleted in your bucket. Each notification contains
+    # information describing both the event that triggered it and the file that
+    # changed.
+    #
+    # You can send notifications to any Cloud Pub/Sub topic in any project for
+    # which your service account has sufficient permissions. As shown below, you
+    # need to explicitly grant permission to your service account to enable
+    # Google Cloud Storage to publish on behalf of your account. (Even if your
+    # current project created and owns the topic.)
+    #
+    # ```ruby
+    # require "google/cloud/pubsub"
+    # require "google/cloud/storage"
+    #
+    # pubsub = Google::Cloud::Pubsub.new
+    # topic = pubsub.create_topic "my-topic"
+    # topic.policy do |p|
+    #   p.add "roles/pubsub.publisher",
+    #         "serviceAccount:my-project" \
+    #         "@gs-project-accounts.iam.gserviceaccount.com"
+    # end
+    #
+    # storage = Google::Cloud::Storage.new
+    # bucket = storage.bucket "my-bucket"
+    #
+    # notification = bucket.create_notification topic.name
+    # ```
+    #
     # ## Configuring retries and timeout
     #
     # You can configure how many times API requests may be automatically

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

@@ -19,6 +19,7 @@ require "google/cloud/storage/bucket/cors"
 require "google/cloud/storage/policy"
 require "google/cloud/storage/post_object"
 require "google/cloud/storage/file"
+require "google/cloud/storage/notification"
 require "pathname"
 
 module Google
@@ -1137,6 +1138,147 @@ module Google
           gapi.permissions
         end
 
+        ##
+        # Retrieves the entire list of Pub/Sub notification subscriptions for
+        # the bucket.
+        #
+        # @see https://cloud.google.com/storage/docs/pubsub-notifications Cloud
+        #   Pub/Sub Notifications for Google Cloud
+        #
+        # @return [Array<Google::Cloud::Storage::Notification>]
+        #
+        # @example
+        #   require "google/cloud/storage"
+        #
+        #   storage = Google::Cloud::Storage.new
+        #
+        #   bucket = storage.bucket "my-bucket"
+        #   notifications = bucket.notifications
+        #   notifications.each do |notification|
+        #     puts notification.id
+        #   end
+        #
+        def notifications
+          ensure_service!
+          gapi = service.list_notifications name, user_project: user_project
+          Array(gapi.items).map do |gapi_object|
+            Notification.from_gapi name, gapi_object, service,
+                                   user_project: user_project
+          end
+        end
+        alias_method :find_notifications, :notifications
+
+        ##
+        # Retrieves a Pub/Sub notification subscription for the bucket.
+        #
+        # @see https://cloud.google.com/storage/docs/pubsub-notifications Cloud
+        #   Pub/Sub Notifications for Google Cloud
+        #
+        # @param [String] id The Notification ID.
+        #
+        # @return [Google::Cloud::Storage::Notification, nil] Returns nil if the
+        #   notification does not exist
+        #
+        # @example
+        #   require "google/cloud/storage"
+        #
+        #   storage = Google::Cloud::Storage.new
+        #
+        #   bucket = storage.bucket "my-bucket"
+        #
+        #   notification = bucket.notification "1"
+        #   puts notification.id
+        #
+        def notification id
+          ensure_service!
+          gapi = service.get_notification name, id, user_project: user_project
+          Notification.from_gapi name, gapi, service, user_project: user_project
+        rescue Google::Cloud::NotFoundError
+          nil
+        end
+        alias_method :find_notification, :notification
+
+
+        ##
+        # Creates a new Pub/Sub notification subscription for the bucket.
+        #
+        # @see https://cloud.google.com/storage/docs/pubsub-notifications Cloud
+        #   Pub/Sub Notifications for Google Cloud
+        #
+        # @param [String] topic The name of the Cloud PubSub topic to which the
+        #   notification subscription will publish.
+        # @param [Hash(String => String)] custom_attrs The custom attributes for
+        #   the notification. An optional list of additional attributes to
+        #   attach to each Cloud Pub/Sub message published for the notification
+        #   subscription.
+        # @param [Symbol, String] event_types The event types for the
+        #   notification subscription. If provided, messages will only be sent
+        #   for the listed event types. If empty, messages will be sent for all
+        #   event types.
+        #
+        #   Acceptable values are:
+        #
+        #   * `:finalize` - Sent when a new object (or a new generation of
+        #     an existing object) is successfully created in the bucket. This
+        #     includes copying or rewriting an existing object. A failed upload
+        #     does not trigger this event.
+        #   * `:update` - Sent when the metadata of an existing object changes.
+        #   * `:delete` - Sent when an object has been permanently deleted. This
+        #     includes objects that are overwritten or are deleted as part of
+        #     the bucket's lifecycle configuration. For buckets with object
+        #     versioning enabled, this is not sent when an object is archived
+        #     (see `OBJECT_ARCHIVE`), even if archival occurs via the
+        #     {File#delete} method.
+        #   * `:archive` - Only sent when the bucket has enabled object
+        #     versioning. This event indicates that the live version of an
+        #     object has become an archived version, either because it was
+        #     archived or because it was overwritten by the upload of an object
+        #     of the same name.
+        # @param [String] prefix The file name prefix for the notification
+        #   subscription. If provided, the notification will only be applied to
+        #   file names that begin with this prefix.
+        # @param [Symbol, String, Boolean] payload The desired content of the
+        #   Pub/Sub message payload. Acceptable values are:
+        #
+        #   * `true` or `:json` - The Pub/Sub message payload will be a UTF-8
+        #     string containing the [resource
+        #     representation](https://cloud.google.com/storage/docs/json_api/v1/objects#resource-representations)
+        #     of the file's metadata.
+        #   * `false` or `:none` - No payload is included with the notification.
+        #
+        #   The default value is `:json`.
+        #
+        # @return [Array<String>] The permissions held by the caller.
+        #
+        # @example
+        #   require "google/cloud/pubsub"
+        #   require "google/cloud/storage"
+        #
+        #   pubsub = Google::Cloud::Pubsub.new
+        #   topic = pubsub.create_topic "my-topic"
+        #   topic.policy do |p|
+        #     p.add "roles/pubsub.publisher",
+        #           "serviceAccount:my-project" \
+        #           "@gs-project-accounts.iam.gserviceaccount.com"
+        #   end
+        #
+        #   storage = Google::Cloud::Storage.new
+        #   bucket = storage.bucket "my-bucket"
+        #
+        #   notification = bucket.create_notification topic.name
+        #
+        def create_notification topic, custom_attrs: nil, event_types: nil,
+                                prefix: nil, payload: nil
+          ensure_service!
+          options = { custom_attrs: custom_attrs, event_types: event_types,
+                      prefix: prefix, payload: payload,
+                      user_project: user_project }
+
+          gapi = service.insert_notification name, topic, options
+          Notification.from_gapi name, gapi, service, user_project: user_project
+        end
+        alias_method :new_notification, :create_notification
+
         ##
         # Reloads the bucket with current data from the Storage service.
         def reload!

data/lib/google/cloud/storage/file/signer.rb

@@ -121,13 +121,13 @@ module Google
           end
 
           def generate_signed_url issuer, signed_string, expires, query
-            url = "#{ext_url}?GoogleAccessId=#{CGI.escape issuer}" \
+            url = "#{ext_url}?GoogleAccessId=#{url_escape issuer}" \
               "&Expires=#{expires}" \
-              "&Signature=#{CGI.escape signed_string}"
+              "&Signature=#{url_escape signed_string}"
 
             if query
               query.each do |name, value|
-                url << "&#{CGI.escape name}=#{CGI.escape value}"
+                url << "&#{url_escape name}=#{url_escape value}"
               end
             end
 
@@ -143,6 +143,10 @@ module Google
             flatten.reject! { |h| h.start_with? "x-goog-encryption-key" }
             flatten.sort.join
           end
+
+          def url_escape str
+            CGI.escape String str
+          end
         end
       end
     end

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

@@ -0,0 +1,212 @@
+# Copyright 2017 Google Inc. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require "google/cloud/errors"
+require "google/apis/storage_v1"
+
+module Google
+  module Cloud
+    module Storage
+      ##
+      # # Notification
+      #
+      # Represents a Pub/Sub notification subscription for a Cloud Storage
+      # bucket.
+      #
+      # @see https://cloud.google.com/storage/docs/pubsub-notifications Cloud
+      #   Pub/Sub Notifications for Google Cloud
+      #
+      # @attr [String] bucket The name of the {Bucket} to which this
+      #   notification belongs.
+      #
+      # @example
+      #   require "google/cloud/pubsub"
+      #   require "google/cloud/storage"
+      #
+      #   pubsub = Google::Cloud::Pubsub.new
+      #   topic = pubsub.create_topic "my-topic"
+      #   topic.policy do |p|
+      #     p.add "roles/pubsub.publisher",
+      #           "serviceAccount:my-project" \
+      #           "@gs-project-accounts.iam.gserviceaccount.com"
+      #   end
+      #
+      #   storage = Google::Cloud::Storage.new
+      #   bucket = storage.bucket "my-bucket"
+      #
+      #   notification = bucket.create_notification topic.name
+      #
+      class Notification
+        ##
+        # @private The Connection object.
+        attr_accessor :service
+
+        ##
+        # @private The Google API Client object.
+        attr_accessor :gapi
+
+        ##
+        # @private The project ID string for a requester pays bucket.
+        attr_accessor :user_project
+
+        attr_reader :bucket
+
+        ##
+        # @private Creates a Notification object.
+        def initialize
+          @bucket = nil
+          @service = nil
+          @gapi = nil
+          @user_project = nil
+        end
+
+        ##
+        # The kind of item this is.
+        # For notifications, this is always storage#notification.
+        def kind
+          @gapi.kind
+        end
+
+        ##
+        # The ID of the notification.
+        def id
+          @gapi.id
+        end
+
+        ##
+        # A URL that can be used to access the notification using the REST API.
+        def api_url
+          @gapi.self_link
+        end
+
+        ##
+        # The custom attributes of this notification. An optional list of
+        # additional attributes to attach to each Cloud Pub/Sub message
+        # published for this notification subscription.
+        def custom_attrs
+          @gapi.custom_attributes
+        end
+
+        ##
+        # The event types of this notification. If present, only send
+        # notifications about listed event types. If empty, sent notifications
+        # for all event types.
+        #
+        # The following is a list of event types currently supported by Cloud
+        # Storage:
+        #
+        # * `OBJECT_FINALIZE` - Sent when a new object (or a new generation of
+        #   an existing object) is successfully created in the bucket. This
+        #   includes copying or rewriting an existing object. A failed upload
+        #   does not trigger this event.
+        # * `OBJECT_METADATA_UPDATE` - Sent when the metadata of an existing
+        #   object changes.
+        # * `OBJECT_DELETE` - Sent when an object has been permanently deleted.
+        #   This includes objects that are overwritten or are deleted as part of
+        #   the bucket's lifecycle configuration. For buckets with object
+        #   versioning enabled, this is not sent when an object is archived (see
+        #   `OBJECT_ARCHIVE`), even if archival occurs via the {File#delete}
+        #   method.
+        # * `OBJECT_ARCHIVE` - Only sent when a bucket has enabled object
+        #   versioning. This event indicates that the live version of an object
+        #   has become an archived version, either because it was archived or
+        #   because it was overwritten by the upload of an object of the same
+        #   name.
+        #
+        # Important: Additional event types may be released later. Client code
+        # should either safely ignore unrecognized event types, or else
+        # explicitly specify in their notification configuration which event
+        # types they are prepared to accept.
+        #
+        def event_types
+          @gapi.event_types
+        end
+
+        ##
+        # The file name prefix of this notification. If present, only apply
+        # this notification configuration to file names that begin with this
+        # prefix.
+        #
+        def prefix
+          @gapi.object_name_prefix
+        end
+
+        ##
+        # The desired content of the Pub/Sub message payload. Acceptable values
+        # are:
+        #
+        # * `JSON_API_V1` - The payload will be a UTF-8 string containing the
+        #   [resource
+        #   representation](https://cloud.google.com/storage/docs/json_api/v1/objects#resource-representations)
+        #   of the file's metadata.
+        # * `NONE` - No payload is included with the notification.
+        #
+        def payload
+          @gapi.payload_format
+        end
+
+        ##
+        # The Cloud Pub/Sub topic to which this subscription publishes.
+        # Formatted as:
+        # `//pubsub.googleapis.com/projects/{project-id}/topics/{my-topic}`
+        def topic
+          @gapi.topic
+        end
+
+        ##
+        # Permanently deletes the notification.
+        #
+        # The API call to delete the notification may be retried under certain
+        # conditions. See {Google::Cloud#storage} to control this behavior.
+        #
+        # @return [Boolean] Returns `true` if the notification was deleted.
+        #
+        # @example
+        #   require "google/cloud/storage"
+        #
+        #   storage = Google::Cloud::Storage.new
+        #
+        #   bucket = storage.bucket "my-bucket"
+        #   notification = bucket.notification "1"
+        #   notification.delete
+        #
+        def delete
+          ensure_service!
+          @service.delete_notification bucket, id, user_project: @user_project
+          true
+        end
+
+        ##
+        # @private New Notification from a
+        # Google::Apis::StorageV1::Notification object.
+        def self.from_gapi bucket_name, gapi, service, user_project: nil
+          new.tap do |f|
+            f.instance_variable_set :@bucket, bucket_name
+            f.gapi = gapi
+            f.service = service
+            f.user_project = user_project
+          end
+        end
+
+        protected
+
+        ##
+        # Raise an error unless an active service is available.
+        def ensure_service!
+          fail "Must have active connection" unless service
+        end
+      end
+    end
+  end
+end

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

@@ -206,6 +206,52 @@ module Google
           end
         end
 
+        ##
+        # Retrieves a list of Pub/Sub notification subscriptions for a bucket.
+        def list_notifications bucket_name, user_project: nil
+          execute do
+            service.list_notifications bucket_name,
+                                       user_project: user_project(user_project)
+          end
+        end
+
+        ##
+        # Creates a new Pub/Sub notification subscription for a bucket.
+        def insert_notification bucket_name, topic_name, custom_attrs: nil,
+                                event_types: nil, prefix: nil, payload: nil,
+                                user_project: nil
+          new_notification = Google::Apis::StorageV1::Notification.new({
+            custom_attributes: custom_attrs,
+            event_types: event_types(event_types),
+            object_name_prefix: prefix,
+            payload_format: payload_format(payload),
+            topic: topic_path(topic_name) }.delete_if { |_k, v| v.nil? })
+
+          execute do
+            service.insert_notification \
+              bucket_name, new_notification,
+              user_project: user_project(user_project)
+          end
+        end
+
+        ##
+        # Retrieves a Pub/Sub notification subscription for a bucket.
+        def get_notification bucket_name, notification_id, user_project: nil
+          execute do
+            service.get_notification bucket_name, notification_id,
+                                     user_project: user_project(user_project)
+          end
+        end
+
+        ##
+        # Deletes a new Pub/Sub notification subscription for a bucket.
+        def delete_notification bucket_name, notification_id, user_project: nil
+          execute do
+            service.delete_notification bucket_name, notification_id,
+                                        user_project: user_project(user_project)
+          end
+        end
+
         ##
         # Retrieves a list of files matching the criteria.
         def list_files bucket_name, delimiter: nil, max: nil, token: nil,
@@ -419,6 +465,42 @@ module Google
           options
         end
 
+        def topic_path topic_name
+          return topic_name if topic_name.to_s.include? "/"
+          "//pubsub.googleapis.com/projects/#{project}/topics/#{topic_name}"
+        end
+
+        # Pub/Sub notification subscription event_types
+        def event_types arr
+          arr.map { |x| event_type x } if arr
+        end
+
+        # Pub/Sub notification subscription event_types
+        def event_type str
+          { "object_finalize" => "OBJECT_FINALIZE",
+            "finalize" => "OBJECT_FINALIZE",
+            "create" => "OBJECT_FINALIZE",
+            "object_metadata_update" => "OBJECT_METADATA_UPDATE",
+            "object_update" => "OBJECT_METADATA_UPDATE",
+            "metadata_update" => "OBJECT_METADATA_UPDATE",
+            "update" => "OBJECT_METADATA_UPDATE",
+            "object_delete" => "OBJECT_DELETE",
+            "delete" => "OBJECT_DELETE",
+            "object_archive" => "OBJECT_ARCHIVE",
+            "archive" => "OBJECT_ARCHIVE" }[str.to_s.downcase]
+        end
+
+        # Pub/Sub notification subscription payload_format
+        # Defaults to "JSON_API_V1"
+        def payload_format str_or_bool
+          return "JSON_API_V1" if str_or_bool.nil?
+          { "json_api_v1" => "JSON_API_V1",
+            "json" => "JSON_API_V1",
+            "true" => "JSON_API_V1",
+            "none" => "NONE",
+            "false" => "NONE" }[str_or_bool.to_s.downcase]
+        end
+
         def execute
           yield
         rescue Google::Apis::Error => e

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

@@ -16,7 +16,7 @@
 module Google
   module Cloud
     module Storage
-      VERSION = "1.4.0"
+      VERSION = "1.5.0"
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: google-cloud-storage
 version: !ruby/object:Gem::Version
-  version: 1.4.0
+  version: 1.5.0
 platform: ruby
 authors:
 - Mike Moore
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-08-02 00:00:00.000000000 Z
+date: 2017-09-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: google-cloud-core
@@ -203,6 +203,7 @@ files:
 - lib/google/cloud/storage/file/list.rb
 - lib/google/cloud/storage/file/signer.rb
 - lib/google/cloud/storage/file/verifier.rb
+- lib/google/cloud/storage/notification.rb
 - lib/google/cloud/storage/policy.rb
 - lib/google/cloud/storage/post_object.rb
 - lib/google/cloud/storage/project.rb
@@ -228,7 +229,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.6.12
+rubygems_version: 2.6.13
 signing_key: 
 specification_version: 4
 summary: API Client library for Google Cloud Storage