jomz-google-api-client 0.7.1

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.
Files changed (63) hide show
  1. data/CHANGELOG.md +144 -0
  2. data/CONTRIBUTING.md +32 -0
  3. data/Gemfile +41 -0
  4. data/LICENSE +202 -0
  5. data/README.md +192 -0
  6. data/Rakefile +46 -0
  7. data/lib/cacerts.pem +2183 -0
  8. data/lib/compat/multi_json.rb +16 -0
  9. data/lib/google/api_client.rb +672 -0
  10. data/lib/google/api_client/auth/compute_service_account.rb +28 -0
  11. data/lib/google/api_client/auth/file_storage.rb +87 -0
  12. data/lib/google/api_client/auth/installed_app.rb +122 -0
  13. data/lib/google/api_client/auth/jwt_asserter.rb +126 -0
  14. data/lib/google/api_client/auth/key_utils.rb +93 -0
  15. data/lib/google/api_client/auth/pkcs12.rb +41 -0
  16. data/lib/google/api_client/batch.rb +323 -0
  17. data/lib/google/api_client/client_secrets.rb +176 -0
  18. data/lib/google/api_client/discovery.rb +19 -0
  19. data/lib/google/api_client/discovery/api.rb +300 -0
  20. data/lib/google/api_client/discovery/media.rb +77 -0
  21. data/lib/google/api_client/discovery/method.rb +363 -0
  22. data/lib/google/api_client/discovery/resource.rb +156 -0
  23. data/lib/google/api_client/discovery/schema.rb +121 -0
  24. data/lib/google/api_client/environment.rb +42 -0
  25. data/lib/google/api_client/errors.rb +60 -0
  26. data/lib/google/api_client/gzip.rb +28 -0
  27. data/lib/google/api_client/logging.rb +32 -0
  28. data/lib/google/api_client/media.rb +259 -0
  29. data/lib/google/api_client/railtie.rb +16 -0
  30. data/lib/google/api_client/reference.rb +27 -0
  31. data/lib/google/api_client/request.rb +351 -0
  32. data/lib/google/api_client/result.rb +253 -0
  33. data/lib/google/api_client/service.rb +233 -0
  34. data/lib/google/api_client/service/batch.rb +103 -0
  35. data/lib/google/api_client/service/request.rb +144 -0
  36. data/lib/google/api_client/service/resource.rb +40 -0
  37. data/lib/google/api_client/service/result.rb +162 -0
  38. data/lib/google/api_client/service/simple_file_store.rb +151 -0
  39. data/lib/google/api_client/service/stub_generator.rb +59 -0
  40. data/lib/google/api_client/service_account.rb +18 -0
  41. data/lib/google/api_client/version.rb +31 -0
  42. data/lib/google/inflection.rb +28 -0
  43. data/spec/fixtures/files/privatekey.p12 +0 -0
  44. data/spec/fixtures/files/sample.txt +33 -0
  45. data/spec/fixtures/files/secret.pem +19 -0
  46. data/spec/google/api_client/batch_spec.rb +249 -0
  47. data/spec/google/api_client/discovery_spec.rb +652 -0
  48. data/spec/google/api_client/gzip_spec.rb +86 -0
  49. data/spec/google/api_client/media_spec.rb +179 -0
  50. data/spec/google/api_client/request_spec.rb +30 -0
  51. data/spec/google/api_client/result_spec.rb +203 -0
  52. data/spec/google/api_client/service_account_spec.rb +164 -0
  53. data/spec/google/api_client/service_spec.rb +586 -0
  54. data/spec/google/api_client/simple_file_store_spec.rb +137 -0
  55. data/spec/google/api_client_spec.rb +253 -0
  56. data/spec/spec_helper.rb +56 -0
  57. data/tasks/gem.rake +97 -0
  58. data/tasks/git.rake +45 -0
  59. data/tasks/metrics.rake +22 -0
  60. data/tasks/spec.rake +57 -0
  61. data/tasks/wiki.rake +82 -0
  62. data/tasks/yard.rake +29 -0
  63. metadata +309 -0
@@ -0,0 +1,233 @@
1
+ # Copyright 2013 Google Inc.
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
+ require 'google/api_client'
16
+ require 'google/api_client/service/stub_generator'
17
+ require 'google/api_client/service/resource'
18
+ require 'google/api_client/service/request'
19
+ require 'google/api_client/service/result'
20
+ require 'google/api_client/service/batch'
21
+ require 'google/api_client/service/simple_file_store'
22
+
23
+ module Google
24
+ class APIClient
25
+
26
+ ##
27
+ # Experimental new programming interface at the API level.
28
+ # Hides Google::APIClient. Designed to be easier to use, with less code.
29
+ #
30
+ # @example
31
+ # calendar = Google::APIClient::Service.new('calendar', 'v3')
32
+ # result = calendar.events.list('calendarId' => 'primary').execute()
33
+ class Service
34
+ include Google::APIClient::Service::StubGenerator
35
+ extend Forwardable
36
+
37
+ DEFAULT_CACHE_FILE = 'discovery.cache'
38
+
39
+ # Cache for discovered APIs.
40
+ @@discovered = {}
41
+
42
+ ##
43
+ # Creates a new Service.
44
+ #
45
+ # @param [String, Symbol] api_name
46
+ # The name of the API this service will access.
47
+ # @param [String, Symbol] api_version
48
+ # The version of the API this service will access.
49
+ # @param [Hash] options
50
+ # The configuration parameters for the service.
51
+ # @option options [Symbol, #generate_authenticated_request] :authorization
52
+ # (:oauth_1)
53
+ # The authorization mechanism used by the client. The following
54
+ # mechanisms are supported out-of-the-box:
55
+ # <ul>
56
+ # <li><code>:two_legged_oauth_1</code></li>
57
+ # <li><code>:oauth_1</code></li>
58
+ # <li><code>:oauth_2</code></li>
59
+ # </ul>
60
+ # @option options [Boolean] :auto_refresh_token (true)
61
+ # The setting that controls whether or not the api client attempts to
62
+ # refresh authorization when a 401 is hit in #execute. If the token does
63
+ # not support it, this option is ignored.
64
+ # @option options [String] :application_name
65
+ # The name of the application using the client.
66
+ # @option options [String] :application_version
67
+ # The version number of the application using the client.
68
+ # @option options [String] :host ("www.googleapis.com")
69
+ # The API hostname used by the client. This rarely needs to be changed.
70
+ # @option options [String] :port (443)
71
+ # The port number used by the client. This rarely needs to be changed.
72
+ # @option options [String] :discovery_path ("/discovery/v1")
73
+ # The discovery base path. This rarely needs to be changed.
74
+ # @option options [String] :ca_file
75
+ # Optional set of root certificates to use when validating SSL connections.
76
+ # By default, a bundled set of trusted roots will be used.
77
+ # @option options [#generate_authenticated_request] :authorization
78
+ # The authorization mechanism for requests. Used only if
79
+ # `:authenticated` is `true`.
80
+ # @option options [TrueClass, FalseClass] :authenticated (default: true)
81
+ # `true` if requests must be signed or somehow
82
+ # authenticated, `false` otherwise.
83
+ # @option options [TrueClass, FalseClass] :gzip (default: true)
84
+ # `true` if gzip enabled, `false` otherwise.
85
+ # @option options [Faraday::Connection] :connection
86
+ # A custom connection to be used for all requests.
87
+ # @option options [ActiveSupport::Cache::Store, :default] :discovery_cache
88
+ # A cache store to place the discovery documents for loaded APIs.
89
+ # Avoids unnecessary roundtrips to the discovery service.
90
+ # :default loads the default local file cache store.
91
+ def initialize(api_name, api_version, options = {})
92
+ @api_name = api_name.to_s
93
+ if api_version.nil?
94
+ raise ArgumentError,
95
+ "API version must be set"
96
+ end
97
+ @api_version = api_version.to_s
98
+ if options && !options.respond_to?(:to_hash)
99
+ raise ArgumentError,
100
+ "expected options Hash, got #{options.class}"
101
+ end
102
+
103
+ params = {}
104
+ [:application_name, :application_version, :authorization, :host, :port,
105
+ :discovery_path, :auto_refresh_token, :key, :user_ip,
106
+ :ca_file].each do |option|
107
+ if options.include? option
108
+ params[option] = options[option]
109
+ end
110
+ end
111
+
112
+ @client = Google::APIClient.new(params)
113
+
114
+ @connection = options[:connection] || @client.connection
115
+
116
+ @options = options
117
+
118
+ # Initialize cache store. Default to SimpleFileStore if :cache_store
119
+ # is not provided and we have write permissions.
120
+ if options.include? :cache_store
121
+ @cache_store = options[:cache_store]
122
+ else
123
+ cache_exists = File.exist?(DEFAULT_CACHE_FILE)
124
+ if (cache_exists && File.writable?(DEFAULT_CACHE_FILE)) ||
125
+ (!cache_exists && File.writable?(Dir.pwd))
126
+ @cache_store = Google::APIClient::Service::SimpleFileStore.new(
127
+ DEFAULT_CACHE_FILE)
128
+ end
129
+ end
130
+
131
+ # Attempt to read API definition from memory cache.
132
+ # Not thread-safe, but the worst that can happen is a cache miss.
133
+ unless @api = @@discovered[[api_name, api_version]]
134
+ # Attempt to read API definition from cache store, if there is one.
135
+ # If there's a miss or no cache store, call discovery service.
136
+ if !@cache_store.nil?
137
+ @api = @cache_store.fetch("%s/%s" % [api_name, api_version]) do
138
+ @client.discovered_api(api_name, api_version)
139
+ end
140
+ else
141
+ @api = @client.discovered_api(api_name, api_version)
142
+ end
143
+ @@discovered[[api_name, api_version]] = @api
144
+ end
145
+
146
+ generate_call_stubs(self, @api)
147
+ end
148
+
149
+ ##
150
+ # Returns the authorization mechanism used by the service.
151
+ #
152
+ # @return [#generate_authenticated_request] The authorization mechanism.
153
+ def_delegators :@client, :authorization, :authorization=
154
+
155
+ ##
156
+ # The setting that controls whether or not the service attempts to
157
+ # refresh authorization when a 401 is hit during an API call.
158
+ #
159
+ # @return [Boolean]
160
+ def_delegators :@client, :auto_refresh_token, :auto_refresh_token=
161
+
162
+ ##
163
+ # The application's API key issued by the API console.
164
+ #
165
+ # @return [String] The API key.
166
+ def_delegators :@client, :key, :key=
167
+
168
+ ##
169
+ # The Faraday/HTTP connection used by this service.
170
+ #
171
+ # @return [Faraday::Connection]
172
+ attr_accessor :connection
173
+
174
+ ##
175
+ # The cache store used for storing discovery documents.
176
+ #
177
+ # @return [ActiveSupport::Cache::Store,
178
+ # Google::APIClient::Service::SimpleFileStore,
179
+ # nil]
180
+ attr_reader :cache_store
181
+
182
+ ##
183
+ # Prepares a Google::APIClient::BatchRequest object to make batched calls.
184
+ # @param [Array] calls
185
+ # Optional array of Google::APIClient::Service::Request to initialize
186
+ # the batch request with.
187
+ # @param [Proc] block
188
+ # Callback for every call's response. Won't be called if a call defined
189
+ # a callback of its own.
190
+ #
191
+ # @yield [Google::APIClient::Service::Result]
192
+ # block to be called when result ready
193
+ def batch(calls = nil, &block)
194
+ Google::APIClient::Service::BatchRequest.new(self, calls, &block)
195
+ end
196
+
197
+ ##
198
+ # Executes an API request.
199
+ # Do not call directly; this method is only used by Request objects when
200
+ # executing.
201
+ #
202
+ # @param [Google::APIClient::Service::Request,
203
+ # Google::APIClient::Service::BatchCall] request
204
+ # The request to be executed.
205
+ def execute(request)
206
+ if request.instance_of? Google::APIClient::Service::Request
207
+ params = {:api_method => request.method,
208
+ :parameters => request.parameters,
209
+ :connection => @connection}
210
+ if request.respond_to? :body
211
+ if request.body.respond_to? :to_hash
212
+ params[:body_object] = request.body
213
+ else
214
+ params[:body] = request.body
215
+ end
216
+ end
217
+ if request.respond_to? :media
218
+ params[:media] = request.media
219
+ end
220
+ [:authenticated, :gzip].each do |option|
221
+ if @options.include? option
222
+ params[option] = @options[option]
223
+ end
224
+ end
225
+ result = @client.execute(params)
226
+ return Google::APIClient::Service::Result.new(request, result)
227
+ elsif request.instance_of? Google::APIClient::Service::BatchRequest
228
+ @client.execute(request.base_batch)
229
+ end
230
+ end
231
+ end
232
+ end
233
+ end
@@ -0,0 +1,103 @@
1
+ # Copyright 2013 Google Inc.
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
+ require 'google/api_client/service/result'
16
+ require 'google/api_client/batch'
17
+
18
+ module Google
19
+ class APIClient
20
+ class Service
21
+
22
+ ##
23
+ # Helper class to contain the result of an individual batched call.
24
+ #
25
+ class BatchedCallResult < Result
26
+ # @return [Fixnum] Index of the call
27
+ def call_index
28
+ return @base_result.response.call_id.to_i - 1
29
+ end
30
+ end
31
+
32
+ ##
33
+ #
34
+ #
35
+ class BatchRequest
36
+ ##
37
+ # Creates a new batch request.
38
+ # This class shouldn't be instantiated directly, but rather through
39
+ # Service.batch.
40
+ #
41
+ # @param [Array] calls
42
+ # List of Google::APIClient::Service::Request to be made.
43
+ # @param [Proc] block
44
+ # Callback for every call's response. Won't be called if a call
45
+ # defined a callback of its own.
46
+ #
47
+ # @yield [Google::APIClient::Service::Result]
48
+ # block to be called when result ready
49
+ def initialize(service, calls, &block)
50
+ @service = service
51
+ @base_batch = Google::APIClient::BatchRequest.new
52
+ @global_callback = block if block_given?
53
+
54
+ if calls && calls.length > 0
55
+ calls.each do |call|
56
+ add(call)
57
+ end
58
+ end
59
+ end
60
+
61
+ ##
62
+ # Add a new call to the batch request.
63
+ #
64
+ # @param [Google::APIClient::Service::Request] call
65
+ # the call to be added.
66
+ # @param [Proc] block
67
+ # callback for this call's response.
68
+ #
69
+ # @return [Google::APIClient::Service::BatchRequest]
70
+ # the BatchRequest, for chaining
71
+ #
72
+ # @yield [Google::APIClient::Service::Result]
73
+ # block to be called when result ready
74
+ def add(call, &block)
75
+ if !block_given? && @global_callback.nil?
76
+ raise BatchError, 'Request needs a block'
77
+ end
78
+ callback = block || @global_callback
79
+ base_call = {
80
+ :api_method => call.method,
81
+ :parameters => call.parameters
82
+ }
83
+ @base_batch.add(base_call) do |base_result|
84
+ result = Google::APIClient::Service::BatchedCallResult.new(
85
+ call, base_result)
86
+ callback.call(result)
87
+ end
88
+ return self
89
+ end
90
+
91
+ ##
92
+ # Executes the batch request.
93
+ def execute
94
+ @service.execute(self)
95
+ end
96
+
97
+ attr_reader :base_batch
98
+
99
+ end
100
+
101
+ end
102
+ end
103
+ end
@@ -0,0 +1,144 @@
1
+ # Copyright 2013 Google Inc.
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
+ module Google
16
+ class APIClient
17
+ class Service
18
+ ##
19
+ # Handles an API request.
20
+ # This contains a full definition of the request to be made (including
21
+ # method name, parameters, body and media). The remote API call can be
22
+ # invoked with execute().
23
+ class Request
24
+ ##
25
+ # Build a request.
26
+ # This class should not be directly instantiated in user code;
27
+ # instantiation is handled by the stub methods created on Service and
28
+ # Resource objects.
29
+ #
30
+ # @param [Google::APIClient::Service] service
31
+ # The parent Service instance that will execute the request.
32
+ # @param [Google::APIClient::Method] method
33
+ # The Method instance that describes the API method invoked by the
34
+ # request.
35
+ # @param [Hash] parameters
36
+ # A Hash of parameter names and values to be sent in the API call.
37
+ def initialize(service, method, parameters)
38
+ @service = service
39
+ @method = method
40
+ @parameters = parameters
41
+ @body = nil
42
+ @media = nil
43
+
44
+ metaclass = (class << self; self; end)
45
+
46
+ # If applicable, add "body", "body=" and resource-named methods for
47
+ # retrieving and setting the HTTP body for this request.
48
+ # Examples of setting the body for files.insert in the Drive API:
49
+ # request.body = object
50
+ # request.execute
51
+ # OR
52
+ # request.file = object
53
+ # request.execute
54
+ # OR
55
+ # request.body(object).execute
56
+ # OR
57
+ # request.file(object).execute
58
+ # Examples of retrieving the body for files.insert in the Drive API:
59
+ # object = request.body
60
+ # OR
61
+ # object = request.file
62
+ if method.request_schema
63
+ body_name = method.request_schema.data['id'].dup
64
+ body_name[0] = body_name[0].chr.downcase
65
+ body_name_equals = (body_name + '=').to_sym
66
+ body_name = body_name.to_sym
67
+
68
+ metaclass.send(:define_method, :body) do |*args|
69
+ if args.length == 1
70
+ @body = args.first
71
+ return self
72
+ elsif args.length == 0
73
+ return @body
74
+ else
75
+ raise ArgumentError,
76
+ "wrong number of arguments (#{args.length}; expecting 0 or 1)"
77
+ end
78
+ end
79
+
80
+ metaclass.send(:define_method, :body=) do |body|
81
+ @body = body
82
+ end
83
+
84
+ metaclass.send(:alias_method, body_name, :body)
85
+ metaclass.send(:alias_method, body_name_equals, :body=)
86
+ end
87
+
88
+ # If applicable, add "media" and "media=" for retrieving and setting
89
+ # the media object for this request.
90
+ # Examples of setting the media object:
91
+ # request.media = object
92
+ # request.execute
93
+ # OR
94
+ # request.media(object).execute
95
+ # Example of retrieving the media object:
96
+ # object = request.media
97
+ if method.media_upload
98
+ metaclass.send(:define_method, :media) do |*args|
99
+ if args.length == 1
100
+ @media = args.first
101
+ return self
102
+ elsif args.length == 0
103
+ return @media
104
+ else
105
+ raise ArgumentError,
106
+ "wrong number of arguments (#{args.length}; expecting 0 or 1)"
107
+ end
108
+ end
109
+
110
+ metaclass.send(:define_method, :media=) do |media|
111
+ @media = media
112
+ end
113
+ end
114
+ end
115
+
116
+ ##
117
+ # Returns the parent service capable of executing this request.
118
+ #
119
+ # @return [Google::APIClient::Service] The parent service.
120
+ attr_reader :service
121
+
122
+ ##
123
+ # Returns the Method instance that describes the API method invoked by
124
+ # the request.
125
+ #
126
+ # @return [Google::APIClient::Method] The API method description.
127
+ attr_reader :method
128
+
129
+ ##
130
+ # Contains the Hash of parameter names and values to be sent as the
131
+ # parameters for the API call.
132
+ #
133
+ # @return [Hash] The request parameters.
134
+ attr_accessor :parameters
135
+
136
+ ##
137
+ # Executes the request.
138
+ def execute
139
+ @service.execute(self)
140
+ end
141
+ end
142
+ end
143
+ end
144
+ end