lib/google/cloud/storage.rb in google-cloud-storage-0.20.2 vs lib/google/cloud/storage.rb in google-cloud-storage-0.21.0

- old
+ new

@@ -32,15 +32,16 @@ # provide the project and credential information to connect to the Storage # service, or if you are running on Google Compute Engine this configuration # is taken care of for you. # # ```ruby - # require "google/cloud" + # require "google/cloud/storage" # - # gcloud = Google::Cloud.new "my-todo-project", - # "/path/to/keyfile.json" - # storage = gcloud.storage + # storage = Google::Cloud::Storage.new( + # project: "my-todo-project", + # keyfile: "/path/to/keyfile.json" + # ) # # bucket = storage.bucket "my-bucket" # file = bucket.file "path/to/my-file.ext" # ``` # @@ -59,38 +60,35 @@ # organize and control access to your data. Each bucket has a unique name, # which is how they are retrieved: (See # {Google::Cloud::Storage::Project#bucket}) # # ```ruby - # require "google/cloud" + # require "google/cloud/storage" # - # gcloud = Google::Cloud.new - # storage = gcloud.storage + # storage = Google::Cloud::Storage.new # # bucket = storage.bucket "my-todo-app" # ``` # # You can also retrieve all buckets on a project: (See # {Google::Cloud::Storage::Project#buckets}) # # ```ruby - # require "google/cloud" + # require "google/cloud/storage" # - # gcloud = Google::Cloud.new - # storage = gcloud.storage + # storage = Google::Cloud::Storage.new # # all_buckets = storage.buckets # ``` # # If you have a significant number of buckets, you may need to paginate # through them: (See {Google::Cloud::Storage::Bucket::List#token}) # # ```ruby - # require "google/cloud" + # require "google/cloud/storage" # - # gcloud = Google::Cloud.new - # storage = gcloud.storage + # storage = Google::Cloud::Storage.new # # all_buckets = [] # tmp_buckets = storage.buckets # while tmp_buckets.any? do # tmp_buckets.each do |bucket| @@ -107,14 +105,13 @@ # # A unique name is all that is needed to create a new bucket: (See # {Google::Cloud::Storage::Project#create_bucket}) # # ```ruby - # require "google/cloud" + # require "google/cloud/storage" # - # gcloud = Google::Cloud.new - # storage = gcloud.storage + # storage = Google::Cloud::Storage.new # # bucket = storage.create_bucket "my-todo-app-attachments" # ``` # # ## Retrieving Files @@ -126,51 +123,47 @@ # # Files are retrieved by their name, which is the path of the file in the # bucket: (See {Google::Cloud::Storage::Bucket#file}) # # ```ruby - # require "google/cloud" + # require "google/cloud/storage" # - # gcloud = Google::Cloud.new - # storage = gcloud.storage + # storage = Google::Cloud::Storage.new # # bucket = storage.bucket "my-todo-app" # file = bucket.file "avatars/heidi/400x400.png" # ``` # # You can also retrieve all files in a bucket: (See Bucket#files) # # ```ruby - # require "google/cloud" + # require "google/cloud/storage" # - # gcloud = Google::Cloud.new - # storage = gcloud.storage + # storage = Google::Cloud::Storage.new # # bucket = storage.bucket "my-todo-app" # all_files = bucket.files # ``` # # Or you can retrieve all files in a specified path: # # ```ruby - # require "google/cloud" + # require "google/cloud/storage" # - # gcloud = Google::Cloud.new - # storage = gcloud.storage + # storage = Google::Cloud::Storage.new # # bucket = storage.bucket "my-todo-app" # avatar_files = bucket.files prefix: "avatars/" # ``` # # If you have a significant number of files, you may need to paginate # through them: (See {Google::Cloud::Storage::File::List#token}) # # ```ruby - # require "google/cloud" + # require "google/cloud/storage" # - # gcloud = Google::Cloud.new - # storage = gcloud.storage + # storage = Google::Cloud::Storage.new # # bucket = storage.bucket "my-todo-app" # # all_files = [] # tmp_files = bucket.files @@ -190,14 +183,13 @@ # A new File can be uploaded by specifying the location of a file on the # local file system, and the name/path that the file should be stored in the # bucket. (See {Google::Cloud::Storage::Bucket#create_file}) # # ```ruby - # require "google/cloud" + # require "google/cloud/storage" # - # gcloud = Google::Cloud.new - # storage = gcloud.storage + # storage = Google::Cloud::Storage.new # # bucket = storage.bucket "my-todo-app" # bucket.create_file "/var/todo-app/avatars/heidi/400x400.png", # "avatars/heidi/400x400.png" # ``` @@ -215,15 +207,14 @@ # the exception of the CRC32C checksum and MD5 hash. The names of files and # buckets are also not encrypted, and you can read or update the metadata of # an encrypted file without providing the encryption key. # # ```ruby - # require "google/cloud" + # require "google/cloud/storage" # require "digest/sha2" # - # gcloud = Google::Cloud.new - # storage = gcloud.storage + # storage = Google::Cloud::Storage.new # bucket = storage.bucket "my-todo-app" # # # Key generation shown for example purposes only. Write your own. # cipher = OpenSSL::Cipher.new "aes-256-cfb" # cipher.encrypt @@ -245,14 +236,13 @@ # # Files can be downloaded to the local file system. (See # {Google::Cloud::Storage::File#download}) # # ```ruby - # require "google/cloud" + # require "google/cloud/storage" # - # gcloud = Google::Cloud.new - # storage = gcloud.storage + # storage = Google::Cloud::Storage.new # # bucket = storage.bucket "my-todo-app" # file = bucket.file "avatars/heidi/400x400.png" # file.download "/var/todo-app/avatars/heidi/400x400.png" # ``` @@ -263,14 +253,13 @@ # period of time. This URL uses a cryptographic signature of your # credentials to access the file. (See # {Google::Cloud::Storage::File#signed_url}) # # ```ruby - # require "google/cloud" + # require "google/cloud/storage" # - # gcloud = Google::Cloud.new - # storage = gcloud.storage + # storage = Google::Cloud::Storage.new # # bucket = storage.bucket "my-todo-app" # file = bucket.file "avatars/heidi/400x400.png" # shared_url = file.signed_url method: "GET", # expires: 300 # 5 minutes from now @@ -287,14 +276,13 @@ # # Access to a bucket can be granted to a user by appending `"user-"` to the # email address: # # ```ruby - # require "google/cloud" + # require "google/cloud/storage" # - # gcloud = Google::Cloud.new - # storage = gcloud.storage + # storage = Google::Cloud::Storage.new # # bucket = storage.bucket "my-todo-app" # # email = "heidi@example.net" # bucket.acl.add_reader "user-#{email}" @@ -302,14 +290,13 @@ # # Access to a bucket can be granted to a group by appending `"group-"` to # the email address: # # ```ruby - # require "google/cloud" + # require "google/cloud/storage" # - # gcloud = Google::Cloud.new - # storage = gcloud.storage + # storage = Google::Cloud::Storage.new # # bucket = storage.bucket "my-todo-app" # # email = "authors@example.net" # bucket.acl.add_reader "group-#{email}" @@ -317,14 +304,13 @@ # # Access to a bucket can also be granted to a predefined list of # permissions: # # ```ruby - # require "google/cloud" + # require "google/cloud/storage" # - # gcloud = Google::Cloud.new - # storage = gcloud.storage + # storage = Google::Cloud::Storage.new # # bucket = storage.bucket "my-todo-app" # # bucket.acl.public! # ``` @@ -338,14 +324,13 @@ # # Access to a file can be granted to a user by appending `"user-"` to the # email address: # # ```ruby - # require "google/cloud" + # require "google/cloud/storage" # - # gcloud = Google::Cloud.new - # storage = gcloud.storage + # storage = Google::Cloud::Storage.new # # bucket = storage.bucket "my-todo-app" # file = bucket.file "avatars/heidi/400x400.png" # # email = "heidi@example.net" @@ -354,14 +339,13 @@ # # Access to a file can be granted to a group by appending `"group-"` to the # email address: # # ```ruby - # require "google/cloud" + # require "google/cloud/storage" # - # gcloud = Google::Cloud.new - # storage = gcloud.storage + # storage = Google::Cloud::Storage.new # # bucket = storage.bucket "my-todo-app" # file = bucket.file "avatars/heidi/400x400.png" # # email = "authors@example.net" @@ -369,14 +353,13 @@ # ``` # # Access to a file can also be granted to a predefined list of permissions: # # ```ruby - # require "google/cloud" + # require "google/cloud/storage" # - # gcloud = Google::Cloud.new - # storage = gcloud.storage + # storage = Google::Cloud::Storage.new # # bucket = storage.bucket "my-todo-app" # file = bucket.file "avatars/heidi/400x400.png" # # file.acl.public! @@ -394,19 +377,72 @@ # reached. # # You can also set the request `timeout` value in seconds. # # ```ruby - # require "google/cloud" + # require "google/cloud/storage" # - # gcloud = Google::Cloud.new - # storage = gcloud.storage retries: 10, timeout: 120 + # storage = Google::Cloud::Storage.new retries: 10, timeout: 120 # ``` # # See the [Storage status and error # codes](https://cloud.google.com/storage/docs/json_api/v1/status-codes) # for a list of error conditions. # module Storage + ## + # Creates a new object for connecting to the Storage service. + # Each call creates a new connection. + # + # For more information on connecting to Google Cloud see the + # [Authentication + # Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/guides/authentication). + # + # @param [String] project Project identifier for the Storage service you + # are connecting to. + # @param [String, Hash] keyfile Keyfile downloaded from Google Cloud. If + # file path the file must be readable. + # @param [String, Array<String>] scope The OAuth 2.0 scopes controlling + # the set of resources and operations that the connection can access. + # See [Using OAuth 2.0 to Access Google + # APIs](https://developers.google.com/identity/protocols/OAuth2). + # + # The default scope is: + # + # * `https://www.googleapis.com/auth/devstorage.full_control` + # @param [Integer] retries Number of times to retry requests on server + # error. The default value is `3`. Optional. + # @param [Integer] timeout Default timeout to use in requests. Optional. + # + # @return [Google::Cloud::Storage::Project] + # + # @example + # require "google/cloud/storage" + # + # storage = Google::Cloud::Storage.new( + # project: "my-todo-project", + # keyfile: "/path/to/keyfile.json" + # ) + # + # bucket = storage.bucket "my-bucket" + # file = bucket.file "path/to/my-file.ext" + # + def self.new project: nil, keyfile: nil, scope: nil, retries: nil, + timeout: nil + project ||= Google::Cloud::Storage::Project.default_project + project = project.to_s # Always cast to a string + fail ArgumentError, "project is missing" if project.empty? + + if keyfile.nil? + credentials = Google::Cloud::Storage::Credentials.default scope: scope + else + credentials = Google::Cloud::Storage::Credentials.new( + keyfile, scope: scope) + end + + Google::Cloud::Storage::Project.new( + Google::Cloud::Storage::Service.new( + project, credentials, retries: retries, timeout: timeout)) + end end end end