lib/google/cloud/storage/bucket.rb in google-cloud-storage-1.6.0 vs lib/google/cloud/storage/bucket.rb in google-cloud-storage-1.7.0

- old
+ new

@@ -46,28 +46,25 @@ ## # @private The Google API Client object. attr_accessor :gapi ## - # A boolean value or a project ID string for a requester pays - # bucket and its files. If this attribute is set to `true`, transit - # costs for operations on the bucket will be billed to the current - # project for this client. (See {Project#project} for the ID of the - # current project.) If this attribute is set to a project ID, and that - # project is authorized for the currently authenticated service account, - # transit costs will be billed to the that project. The default is - # `nil`. + # A boolean value or a project ID string to indicate the project to + # be billed for operations on the bucket and its files. If this + # attribute is set to `true`, transit costs for operations on the bucket + # will be billed to the current project for this client. (See + # {Project#project} for the ID of the current project.) If this + # attribute is set to a project ID, and that project is authorized for + # the currently authenticated service account, transit costs will be + # billed to that project. This attribute is required with requester + # pays-enabled buckets. The default is `nil`. # # In general, this attribute should be set when first retrieving the # bucket by providing the `user_project` option to {Project#bucket}. # - # The requester pays feature is currently available only to whitelisted - # projects. + # See also {#requester_pays=} and {#requester_pays}. # - # See also {#requester_pays=} and {#requester_pays} to enable requester - # pays for a bucket. - # # @example Setting a non-default project: # require "google/cloud/storage" # # storage = Google::Cloud::Storage.new # @@ -344,12 +341,10 @@ # must assume the transit costs related to the access. The requester # must pass the `user_project` option to {Project#bucket} and # {Project#buckets} to indicate the project to which the access costs # should be billed. # - # This feature is currently available only to whitelisted projects. - # # @return [Boolean, nil] Returns `true` if requester pays is enabled for # the bucket. # def requester_pays @gapi.billing.requester_pays if @gapi.billing @@ -361,12 +356,10 @@ # the bucket or a file it contains must assume the transit costs related # to the access. The requester must pass the `user_project` option to # {Project#bucket} and {Project#buckets} to indicate the project to # which the access costs should be billed. # - # This feature is currently available only to whitelisted projects. - # # @param [Boolean] new_requester_pays When set to `true`, requester pays # is enabled for the bucket. # # @example Enable requester pays for a bucket: # require "google/cloud/storage" @@ -710,9 +703,119 @@ gapi = service.insert_file name, file, path, options File.from_gapi gapi, service end alias_method :upload_file, :create_file alias_method :new_file, :create_file + + ## + # Concatenates a list of existing files in the bucket into a new file in + # the bucket. There is a limit (currently 32) to the number of files + # that can be composed in a single operation. + # + # To compose files encrypted with a customer-supplied encryption key, + # use the `encryption_key` option. All source files must have been + # encrypted with the same key, and the resulting destination file will + # also be encrypted with the same key. + # + # @param [Array<String, Google::Cloud::Storage::File>] sources The list + # of source file names or objects that will be concatenated into a + # single file. + # @param [String] destination The name of the new file. + # @param [String] acl A predefined set of access controls to apply to + # this file. + # + # Acceptable values are: + # + # * `auth`, `auth_read`, `authenticated`, `authenticated_read`, + # `authenticatedRead` - File owner gets OWNER access, and + # allAuthenticatedUsers get READER access. + # * `owner_full`, `bucketOwnerFullControl` - File owner gets OWNER + # access, and project team owners get OWNER access. + # * `owner_read`, `bucketOwnerRead` - File owner gets OWNER access, + # and project team owners get READER access. + # * `private` - File owner gets OWNER access. + # * `project_private`, `projectPrivate` - File owner gets OWNER + # access, and project team members get access according to their + # roles. + # * `public`, `public_read`, `publicRead` - File owner gets OWNER + # access, and allUsers get READER access. + # + # @param [String, nil] encryption_key Optional. The customer-supplied, + # AES-256 encryption key used to encrypt the source files, if one was + # used. All source files must have been encrypted with the same key, + # and the resulting destination file will also be encrypted with the + # key. + # + # @yield [file] A block yielding a delegate file object for setting the + # properties of the destination file. + # + # @return [Google::Cloud::Storage::File] The new file. + # + # @example + # require "google/cloud/storage" + # + # storage = Google::Cloud::Storage.new + # + # bucket = storage.bucket "my-bucket" + # + # sources = ["path/to/my-file-1.ext", "path/to/my-file-2.ext"] + # + # new_file = bucket.compose sources, "path/to/new-file.ext" + # + # @example Set the properties of the new file in a block: + # require "google/cloud/storage" + # + # storage = Google::Cloud::Storage.new + # + # bucket = storage.bucket "my-bucket" + # + # sources = ["path/to/my-file-1.ext", "path/to/my-file-2.ext"] + # + # new_file = bucket.compose sources, "path/to/new-file.ext" do |f| + # f.cache_control = "private, max-age=0, no-cache" + # f.content_disposition = "inline; filename=filename.ext" + # f.content_encoding = "deflate" + # f.content_language = "de" + # f.content_type = "application/json" + # end + # + # @example Specify the generation of source files (but skip retrieval): + # require "google/cloud/storage" + # + # storage = Google::Cloud::Storage.new + # + # bucket = storage.bucket "my-bucket" + # + # file_1 = bucket.file "path/to/my-file-1.ext", + # generation: 1490390259479000, skip_lookup: true + # file_2 = bucket.file "path/to/my-file-2.ext", + # generation: 1490310974144000, skip_lookup: true + # + # new_file = bucket.compose [file_1, file_2], "path/to/new-file.ext" + # + def compose sources, destination, acl: nil, encryption_key: nil + ensure_service! + sources = Array sources + if sources.size < 2 + fail ArgumentError, "must provide at least two source files" + end + + options = { acl: File::Acl.predefined_rule_for(acl), + key: encryption_key, + user_project: user_project } + destination_gapi = nil + if block_given? + destination_gapi = Google::Apis::StorageV1::Object.new + updater = File::Updater.new destination_gapi + yield updater + updater.check_for_changed_metadata! + end + gapi = service.compose_file name, sources, destination, + destination_gapi, options + File.from_gapi gapi, service + end + alias_method :compose_file, :compose + alias_method :combine, :compose ## # Access without authentication can be granted to a File for a specified # period of time. This URL uses a cryptographic signature of your # credentials to access the file identified by `path`. A URL can be