google-cloud-storage 0.20.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,7 @@
1
+ ---
2
+ SHA1:
3
+ metadata.gz: 6a1c76520a0d11fc1c5c1eab6e2d1f1b4ff91722
4
+ data.tar.gz: 13c3e68262197af5291c8ad83176390781a4fcad
5
+ SHA512:
6
+ metadata.gz: 3a72a3dc3325b969ecb69737731f794e5115a3691d3d2194858df9358a3384a5cb3f21e6cc54c0a67f14bd5004e05131acd1d636385df8a07543348bc93eb9d9
7
+ data.tar.gz: 24acdbc0c2ebf827a4f6a2a64457f1b45719d8222df10612054e0579b3fea5719f97a8ef845470e884dc9c334ec508b8f9c7d751147753da555304166b8d66a6
@@ -0,0 +1,124 @@
1
+ # Copyright 2016 Google Inc. All rights reserved.
2
+ #
3
+ # Licensed under the Apache License, Version 2.0 (the "License");
4
+ # you may not use this file except in compliance with the License.
5
+ # You may obtain a copy of the License at
6
+ #
7
+ # http://www.apache.org/licenses/LICENSE-2.0
8
+ #
9
+ # Unless required by applicable law or agreed to in writing, software
10
+ # distributed under the License is distributed on an "AS IS" BASIS,
11
+ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12
+ # See the License for the specific language governing permissions and
13
+ # limitations under the License.
14
+
15
+ ##
16
+ # This file is here to be autorequired by bundler, so that the .bigquery and
17
+ # #bigquery methods can be available, but the library and all dependencies won't
18
+ # be loaded until required and used.
19
+
20
+
21
+ gem "google-cloud-core"
22
+ require "google/cloud"
23
+
24
+ module Google
25
+ module Cloud
26
+ ##
27
+ # Creates a new object for connecting to the Storage service.
28
+ # Each call creates a new connection.
29
+ #
30
+ # For more information on connecting to Google Cloud see the [Authentication
31
+ # Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/guides/authentication).
32
+ #
33
+ # @see https://cloud.google.com/storage/docs/authentication#oauth Storage
34
+ # OAuth 2.0 Authentication
35
+ #
36
+ # @param [String, Array<String>] scope The OAuth 2.0 scopes controlling the
37
+ # set of resources and operations that the connection can access. See
38
+ # [Using OAuth 2.0 to Access Google
39
+ # APIs](https://developers.google.com/identity/protocols/OAuth2).
40
+ #
41
+ # The default scope is:
42
+ #
43
+ # * `https://www.googleapis.com/auth/devstorage.full_control`
44
+ # @param [Integer] retries Number of times to retry requests on server
45
+ # error. The default value is `3`. Optional.
46
+ # @param [Integer] timeout Default timeout to use in requests. Optional.
47
+ #
48
+ # @return [Google::Cloud::Storage::Project]
49
+ #
50
+ # @example
51
+ # require "google/cloud"
52
+ #
53
+ # gcloud = Google::Cloud.new
54
+ # storage = gcloud.storage
55
+ # bucket = storage.bucket "my-bucket"
56
+ # file = bucket.file "path/to/my-file.ext"
57
+ #
58
+ # @example The default scope can be overridden with the `scope` option:
59
+ # require "google/cloud"
60
+ #
61
+ # gcloud = Google::Cloud.new
62
+ # readonly_scope = "https://www.googleapis.com/auth/devstorage.read_only"
63
+ # readonly_storage = gcloud.storage scope: readonly_scope
64
+ #
65
+ def storage scope: nil, retries: nil, timeout: nil
66
+ Google::Cloud.storage @project, @keyfile, scope: scope,
67
+ retries: (retries || @retries),
68
+ timeout: (timeout || @timeout)
69
+ end
70
+
71
+ ##
72
+ # Creates a new object for connecting to the Storage service.
73
+ # Each call creates a new connection.
74
+ #
75
+ # For more information on connecting to Google Cloud see the [Authentication
76
+ # Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/guides/authentication).
77
+ #
78
+ # @param [String] project Project identifier for the Storage service you are
79
+ # connecting to.
80
+ # @param [String, Hash] keyfile Keyfile downloaded from Google Cloud. If
81
+ # file path the file must be readable.
82
+ # @param [String, Array<String>] scope The OAuth 2.0 scopes controlling the
83
+ # set of resources and operations that the connection can access. See
84
+ # [Using OAuth 2.0 to Access Google
85
+ # APIs](https://developers.google.com/identity/protocols/OAuth2).
86
+ #
87
+ # The default scope is:
88
+ #
89
+ # * `https://www.googleapis.com/auth/devstorage.full_control`
90
+ # @param [Integer] retries Number of times to retry requests on server
91
+ # error. The default value is `3`. Optional.
92
+ # @param [Integer] timeout Default timeout to use in requests. Optional.
93
+ #
94
+ # @return [Google::Cloud::Storage::Project]
95
+ #
96
+ # @example
97
+ # require "google/cloud/storage"
98
+ #
99
+ # storage = Google::Cloud.storage "my-todo-project",
100
+ # "/path/to/keyfile.json"
101
+ #
102
+ # bucket = storage.bucket "my-bucket"
103
+ # file = bucket.file "path/to/my-file.ext"
104
+ #
105
+ def self.storage project = nil, keyfile = nil, scope: nil, retries: nil,
106
+ timeout: nil
107
+ require "google/cloud/storage"
108
+ project ||= Google::Cloud::Storage::Project.default_project
109
+ project = project.to_s # Always cast to a string
110
+ fail ArgumentError, "project is missing" if project.empty?
111
+
112
+ if keyfile.nil?
113
+ credentials = Google::Cloud::Storage::Credentials.default scope: scope
114
+ else
115
+ credentials = Google::Cloud::Storage::Credentials.new(
116
+ keyfile, scope: scope)
117
+ end
118
+
119
+ Google::Cloud::Storage::Project.new(
120
+ Google::Cloud::Storage::Service.new(
121
+ project, credentials, retries: retries, timeout: timeout))
122
+ end
123
+ end
124
+ end
@@ -0,0 +1,412 @@
1
+ # Copyright 2014 Google Inc. All rights reserved.
2
+ #
3
+ # Licensed under the Apache License, Version 2.0 (the "License");
4
+ # you may not use this file except in compliance with the License.
5
+ # You may obtain a copy of the License at
6
+ #
7
+ # http://www.apache.org/licenses/LICENSE-2.0
8
+ #
9
+ # Unless required by applicable law or agreed to in writing, software
10
+ # distributed under the License is distributed on an "AS IS" BASIS,
11
+ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12
+ # See the License for the specific language governing permissions and
13
+ # limitations under the License.
14
+
15
+
16
+ require "google-cloud-storage"
17
+ require "google/cloud/storage/project"
18
+
19
+ module Google
20
+ module Cloud
21
+ ##
22
+ # # Google Cloud Storage
23
+ #
24
+ # Google Cloud Storage is an Internet service to store data in Google's
25
+ # cloud. It allows world-wide storage and retrieval of any amount of data
26
+ # and at any time, taking advantage of Google's own reliable and fast
27
+ # networking infrastructure to perform data operations in a cost effective
28
+ # manner.
29
+ #
30
+ # The goal of google-cloud is to provide a API that is comfortable to
31
+ # Rubyists. Authentication is handled by {Google::Cloud#storage}. You can
32
+ # provide the project and credential information to connect to the Storage
33
+ # service, or if you are running on Google Compute Engine this configuration
34
+ # is taken care of for you.
35
+ #
36
+ # ```ruby
37
+ # require "google/cloud"
38
+ #
39
+ # gcloud = Google::Cloud.new "my-todo-project",
40
+ # "/path/to/keyfile.json"
41
+ # storage = gcloud.storage
42
+ #
43
+ # bucket = storage.bucket "my-bucket"
44
+ # file = bucket.file "path/to/my-file.ext"
45
+ # ```
46
+ #
47
+ # You can learn more about various options for connection on the
48
+ # [Authentication
49
+ # Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/guides/authentication).
50
+ #
51
+ # To learn more about Cloud Storage, read the
52
+ # [Google Cloud Storage Overview
53
+ # ](https://cloud.google.com/storage/docs/overview).
54
+ #
55
+ # ## Retrieving Buckets
56
+ #
57
+ # A Bucket is the container for your data. There is no limit on the number
58
+ # of buckets that you can create in a project. You can use buckets to
59
+ # organize and control access to your data. Each bucket has a unique name,
60
+ # which is how they are retrieved: (See
61
+ # {Google::Cloud::Storage::Project#bucket})
62
+ #
63
+ # ```ruby
64
+ # require "google/cloud"
65
+ #
66
+ # gcloud = Google::Cloud.new
67
+ # storage = gcloud.storage
68
+ #
69
+ # bucket = storage.bucket "my-todo-app"
70
+ # ```
71
+ #
72
+ # You can also retrieve all buckets on a project: (See
73
+ # {Google::Cloud::Storage::Project#buckets})
74
+ #
75
+ # ```ruby
76
+ # require "google/cloud"
77
+ #
78
+ # gcloud = Google::Cloud.new
79
+ # storage = gcloud.storage
80
+ #
81
+ # all_buckets = storage.buckets
82
+ # ```
83
+ #
84
+ # If you have a significant number of buckets, you may need to paginate
85
+ # through them: (See {Google::Cloud::Storage::Bucket::List#token})
86
+ #
87
+ # ```ruby
88
+ # require "google/cloud"
89
+ #
90
+ # gcloud = Google::Cloud.new
91
+ # storage = gcloud.storage
92
+ #
93
+ # all_buckets = []
94
+ # tmp_buckets = storage.buckets
95
+ # while tmp_buckets.any? do
96
+ # tmp_buckets.each do |bucket|
97
+ # all_buckets << bucket
98
+ # end
99
+ # # break loop if no more buckets available
100
+ # break if tmp_buckets.token.nil?
101
+ # # get the next group of buckets
102
+ # tmp_buckets = storage.buckets token: tmp_buckets.token
103
+ # end
104
+ # ```
105
+ #
106
+ # ## Creating a Bucket
107
+ #
108
+ # A unique name is all that is needed to create a new bucket: (See
109
+ # {Google::Cloud::Storage::Project#create_bucket})
110
+ #
111
+ # ```ruby
112
+ # require "google/cloud"
113
+ #
114
+ # gcloud = Google::Cloud.new
115
+ # storage = gcloud.storage
116
+ #
117
+ # bucket = storage.create_bucket "my-todo-app-attachments"
118
+ # ```
119
+ #
120
+ # ## Retrieving Files
121
+ #
122
+ # A File is an individual pieces of data that you store in Google Cloud
123
+ # Storage. Files contain the data stored as well as metadata describing the
124
+ # data. Files belong to a bucket and cannot be shared among buckets. There
125
+ # is no limit on the number of objects that you can create in a bucket.
126
+ #
127
+ # Files are retrieved by their name, which is the path of the file in the
128
+ # bucket: (See {Google::Cloud::Storage::Bucket#file})
129
+ #
130
+ # ```ruby
131
+ # require "google/cloud"
132
+ #
133
+ # gcloud = Google::Cloud.new
134
+ # storage = gcloud.storage
135
+ #
136
+ # bucket = storage.bucket "my-todo-app"
137
+ # file = bucket.file "avatars/heidi/400x400.png"
138
+ # ```
139
+ #
140
+ # You can also retrieve all files in a bucket: (See Bucket#files)
141
+ #
142
+ # ```ruby
143
+ # require "google/cloud"
144
+ #
145
+ # gcloud = Google::Cloud.new
146
+ # storage = gcloud.storage
147
+ #
148
+ # bucket = storage.bucket "my-todo-app"
149
+ # all_files = bucket.files
150
+ # ```
151
+ #
152
+ # Or you can retrieve all files in a specified path:
153
+ #
154
+ # ```ruby
155
+ # require "google/cloud"
156
+ #
157
+ # gcloud = Google::Cloud.new
158
+ # storage = gcloud.storage
159
+ #
160
+ # bucket = storage.bucket "my-todo-app"
161
+ # avatar_files = bucket.files prefix: "avatars/"
162
+ # ```
163
+ #
164
+ # If you have a significant number of files, you may need to paginate
165
+ # through them: (See {Google::Cloud::Storage::File::List#token})
166
+ #
167
+ # ```ruby
168
+ # require "google/cloud"
169
+ #
170
+ # gcloud = Google::Cloud.new
171
+ # storage = gcloud.storage
172
+ #
173
+ # bucket = storage.bucket "my-todo-app"
174
+ #
175
+ # all_files = []
176
+ # tmp_files = bucket.files
177
+ # while tmp_files.any? do
178
+ # tmp_files.each do |file|
179
+ # all_files << file
180
+ # end
181
+ # # break loop if no more files available
182
+ # break if tmp_files.token.nil?
183
+ # # get the next group of files
184
+ # tmp_files = bucket.files token: tmp_files.token
185
+ # end
186
+ # ```
187
+ #
188
+ # ## Creating a File
189
+ #
190
+ # A new File can be uploaded by specifying the location of a file on the
191
+ # local file system, and the name/path that the file should be stored in the
192
+ # bucket. (See {Google::Cloud::Storage::Bucket#create_file})
193
+ #
194
+ # ```ruby
195
+ # require "google/cloud"
196
+ #
197
+ # gcloud = Google::Cloud.new
198
+ # storage = gcloud.storage
199
+ #
200
+ # bucket = storage.bucket "my-todo-app"
201
+ # bucket.create_file "/var/todo-app/avatars/heidi/400x400.png",
202
+ # "avatars/heidi/400x400.png"
203
+ # ```
204
+ #
205
+ # ### Customer-supplied encryption keys
206
+ #
207
+ # By default, Google Cloud Storage manages server-side encryption keys on
208
+ # your behalf. However, a [customer-supplied encryption
209
+ # key](https://cloud.google.com/storage/docs/encryption#customer-supplied)
210
+ # can be provided with the `encryption_key` and `encryption_key_sha256`
211
+ # options. If given, the same key and SHA256 hash also must be provided to
212
+ # subsequently download or copy the file. If you use customer-supplied
213
+ # encryption keys, you must securely manage your keys and ensure that they
214
+ # are not lost. Also, please note that file metadata is not encrypted, with
215
+ # the exception of the CRC32C checksum and MD5 hash. The names of files and
216
+ # buckets are also not encrypted, and you can read or update the metadata of
217
+ # an encrypted file without providing the encryption key.
218
+ #
219
+ # ```ruby
220
+ # require "google/cloud"
221
+ # require "digest/sha2"
222
+ #
223
+ # gcloud = Google::Cloud.new
224
+ # storage = gcloud.storage
225
+ # bucket = storage.bucket "my-todo-app"
226
+ #
227
+ # # Key generation shown for example purposes only. Write your own.
228
+ # cipher = OpenSSL::Cipher.new "aes-256-cfb"
229
+ # cipher.encrypt
230
+ # key = cipher.random_key
231
+ # key_hash = Digest::SHA256.digest key
232
+ #
233
+ # bucket.create_file "/var/todo-app/avatars/heidi/400x400.png",
234
+ # "avatars/heidi/400x400.png",
235
+ # encryption_key: key,
236
+ # encryption_key_sha256: key_hash
237
+ #
238
+ # # Store your key and hash securely for later use.
239
+ # file = bucket.file "avatars/heidi/400x400.png",
240
+ # encryption_key: key,
241
+ # encryption_key_sha256: key_hash
242
+ # ```
243
+ #
244
+ # ## Downloading a File
245
+ #
246
+ # Files can be downloaded to the local file system. (See
247
+ # {Google::Cloud::Storage::File#download})
248
+ #
249
+ # ```ruby
250
+ # require "google/cloud"
251
+ #
252
+ # gcloud = Google::Cloud.new
253
+ # storage = gcloud.storage
254
+ #
255
+ # bucket = storage.bucket "my-todo-app"
256
+ # file = bucket.file "avatars/heidi/400x400.png"
257
+ # file.download "/var/todo-app/avatars/heidi/400x400.png"
258
+ # ```
259
+ #
260
+ # ## Using Signed URLs
261
+ #
262
+ # Access without authentication can be granted to a File for a specified
263
+ # period of time. This URL uses a cryptographic signature of your
264
+ # credentials to access the file. (See
265
+ # {Google::Cloud::Storage::File#signed_url})
266
+ #
267
+ # ```ruby
268
+ # require "google/cloud"
269
+ #
270
+ # gcloud = Google::Cloud.new
271
+ # storage = gcloud.storage
272
+ #
273
+ # bucket = storage.bucket "my-todo-app"
274
+ # file = bucket.file "avatars/heidi/400x400.png"
275
+ # shared_url = file.signed_url method: "GET",
276
+ # expires: 300 # 5 minutes from now
277
+ # ```
278
+ #
279
+ # ## Controlling Access to a Bucket
280
+ #
281
+ # Access to a bucket is controlled with
282
+ # {Google::Cloud::Storage::Bucket#acl}. A bucket has owners, writers, and
283
+ # readers. Permissions can be granted to an individual user's email address,
284
+ # a group's email address, as well as many predefined lists. See the [Access
285
+ # Control guide](https://cloud.google.com/storage/docs/access-control) for
286
+ # more.
287
+ #
288
+ # Access to a bucket can be granted to a user by appending `"user-"` to the
289
+ # email address:
290
+ #
291
+ # ```ruby
292
+ # require "google/cloud"
293
+ #
294
+ # gcloud = Google::Cloud.new
295
+ # storage = gcloud.storage
296
+ #
297
+ # bucket = storage.bucket "my-todo-app"
298
+ #
299
+ # email = "heidi@example.net"
300
+ # bucket.acl.add_reader "user-#{email}"
301
+ # ```
302
+ #
303
+ # Access to a bucket can be granted to a group by appending `"group-"` to
304
+ # the email address:
305
+ #
306
+ # ```ruby
307
+ # require "google/cloud"
308
+ #
309
+ # gcloud = Google::Cloud.new
310
+ # storage = gcloud.storage
311
+ #
312
+ # bucket = storage.bucket "my-todo-app"
313
+ #
314
+ # email = "authors@example.net"
315
+ # bucket.acl.add_reader "group-#{email}"
316
+ # ```
317
+ #
318
+ # Access to a bucket can also be granted to a predefined list of
319
+ # permissions:
320
+ #
321
+ # ```ruby
322
+ # require "google/cloud"
323
+ #
324
+ # gcloud = Google::Cloud.new
325
+ # storage = gcloud.storage
326
+ #
327
+ # bucket = storage.bucket "my-todo-app"
328
+ #
329
+ # bucket.acl.public!
330
+ # ```
331
+ #
332
+ # ## Controlling Access to a File
333
+ #
334
+ # Access to a file is controlled in two ways, either by the setting the
335
+ # default permissions to all files in a bucket with
336
+ # {Google::Cloud::Storage::Bucket#default_acl}, or by setting permissions to
337
+ # an individual file with {Google::Cloud::Storage::File#acl}.
338
+ #
339
+ # Access to a file can be granted to a user by appending `"user-"` to the
340
+ # email address:
341
+ #
342
+ # ```ruby
343
+ # require "google/cloud"
344
+ #
345
+ # gcloud = Google::Cloud.new
346
+ # storage = gcloud.storage
347
+ #
348
+ # bucket = storage.bucket "my-todo-app"
349
+ # file = bucket.file "avatars/heidi/400x400.png"
350
+ #
351
+ # email = "heidi@example.net"
352
+ # file.acl.add_reader "user-#{email}"
353
+ # ```
354
+ #
355
+ # Access to a file can be granted to a group by appending `"group-"` to the
356
+ # email address:
357
+ #
358
+ # ```ruby
359
+ # require "google/cloud"
360
+ #
361
+ # gcloud = Google::Cloud.new
362
+ # storage = gcloud.storage
363
+ #
364
+ # bucket = storage.bucket "my-todo-app"
365
+ # file = bucket.file "avatars/heidi/400x400.png"
366
+ #
367
+ # email = "authors@example.net"
368
+ # file.acl.add_reader "group-#{email}"
369
+ # ```
370
+ #
371
+ # Access to a file can also be granted to a predefined list of permissions:
372
+ #
373
+ # ```ruby
374
+ # require "google/cloud"
375
+ #
376
+ # gcloud = Google::Cloud.new
377
+ # storage = gcloud.storage
378
+ #
379
+ # bucket = storage.bucket "my-todo-app"
380
+ # file = bucket.file "avatars/heidi/400x400.png"
381
+ #
382
+ # file.acl.public!
383
+ # ```
384
+ #
385
+ # ## Configuring retries and timeout
386
+ #
387
+ # You can configure how many times API requests may be automatically
388
+ # retried. When an API request fails, the response will be inspected to see
389
+ # if the request meets criteria indicating that it may succeed on retry,
390
+ # such as `500` and `503` status codes or a specific internal error code
391
+ # such as `rateLimitExceeded`. If it meets the criteria, the request will be
392
+ # retried after a delay. If another error occurs, the delay will be
393
+ # increased before a subsequent attempt, until the `retries` limit is
394
+ # reached.
395
+ #
396
+ # You can also set the request `timeout` value in seconds.
397
+ #
398
+ # ```ruby
399
+ # require "google/cloud"
400
+ #
401
+ # gcloud = Google::Cloud.new
402
+ # storage = gcloud.storage retries: 10, timeout: 120
403
+ # ```
404
+ #
405
+ # See the [Storage status and error
406
+ # codes](https://cloud.google.com/storage/docs/json_api/v1/status-codes)
407
+ # for a list of error conditions.
408
+ #
409
+ module Storage
410
+ end
411
+ end
412
+ end