google-cloud-pubsub 2.3.0 → 2.6.0

Sign up to get free protection for your applications and to get access to all the features.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 355d1480255766f32036dedb71834ec3cf28f8e0966bb95b9017e056633954fa
4
- data.tar.gz: c3a3583e51f3a3b066c168650677ad9c7efe598a39ea987fa8d5559f9c7d26d5
3
+ metadata.gz: 3ad1e392a28fae7f97e78f0e5a73fcccb4cef83462b7ff6caac53c4e450cbf91
4
+ data.tar.gz: 0d71eca6ba2b40ddb7d1855b2ea9bd4c75422aed74cc2f008cee1881fc850c43
5
5
  SHA512:
6
- metadata.gz: 0ece0f850c4b9e019104e6224c6918c888e999b70860fffd0cb7e57b4a3dd9678a4d2ba9497217aa779e69421cb50706287517c7a5ed294204cbafe954677b5d
7
- data.tar.gz: df5687af6d2805c0e48ac4bc13536af942efd6022c55a6027cd39824d750929c9746732d03c59dd59001d9954af631b3813c6d9e3a07c2f49f46ab4042dbaa14
6
+ metadata.gz: 4ff13cb0796a1fff747785b078ead8f2c0e71d56cfabdaed4156b83eb5bb800c8e35fbc84a4e722f51df8602ff6ca8b81ddfbeac51ada0eb0c7029e5258467d8
7
+ data.tar.gz: '058a56e42f9f42366f709c86f1efe2cec8d1fe909ae2097ac2e7dc9a1e061376636bb7d109711ded9d84284c48b05bf739707b592e500ae8671fda76d22bbf88'
data/CHANGELOG.md CHANGED
@@ -1,5 +1,54 @@
1
1
  # Release History
2
2
 
3
+ ### 2.6.0 / 2021-04-19
4
+
5
+ #### Features
6
+
7
+ * Add ordering_key to Topic#publish
8
+ * Add ordering_key to BatchPublisher#publish
9
+
10
+ #### Documentation
11
+
12
+ * The immediate: false option is recommended to avoid adverse impacts on the performance of pull operations ([#11153](https://www.github.com/googleapis/google-cloud-ruby/issues/11153))
13
+ * Update Subscription#pull docs and samples to recommend immediate: false
14
+
15
+ ### 2.5.0 / 2021-04-01
16
+
17
+ #### Features
18
+
19
+ * Add Schema support
20
+ * Add Schema
21
+ * Add Project#create_schema
22
+ * Add Project#schema
23
+ * Add Project#schemas (Schema::List)
24
+ * Add Project#valid_schema?
25
+ * Add schema options to Project#create_topic
26
+ * Add Topic#schema_name
27
+ * Add Topic#message_encoding
28
+ * Add Topic#message_encoding_binary?
29
+ * Add Topic#message_encoding_json?
30
+
31
+ ### 2.4.0 / 2021-03-10
32
+
33
+ #### Features
34
+
35
+ * Drop support for Ruby 2.4 and add support for Ruby 3.0
36
+
37
+ ### 2.3.2 / 2021-02-08
38
+
39
+ #### Bug Fixes
40
+
41
+ * Fix project option in Project#topic and Project#subscription
42
+ * Ensure that project option is used when skip_lookup is false.
43
+ * Improve documentation of topic_name, subscription_name and snapshot_name.
44
+
45
+ ### 2.3.1 / 2021-01-13
46
+
47
+ #### Bug Fixes
48
+
49
+ * Update Subscription#retry_policy=
50
+ * Remove conditional RPC to fetch full resource before update.
51
+
3
52
  ### 2.3.0 / 2020-11-18
4
53
 
5
54
  #### Features
data/CONTRIBUTING.md CHANGED
@@ -24,7 +24,7 @@ be able to accept your pull requests.
24
24
  In order to use the google-cloud-pubsub console and run the project's tests,
25
25
  there is a small amount of setup:
26
26
 
27
- 1. Install Ruby. google-cloud-pubsub requires Ruby 2.4+. You may choose to
27
+ 1. Install Ruby. google-cloud-pubsub requires Ruby 2.5+. You may choose to
28
28
  manage your Ruby and gem installations with [RVM](https://rvm.io/),
29
29
  [rbenv](https://github.com/rbenv/rbenv), or
30
30
  [chruby](https://github.com/postmodern/chruby).
@@ -45,7 +45,7 @@ there is a small amount of setup:
45
45
 
46
46
  ```sh
47
47
  $ cd google-cloud-pubsub/
48
- $ bundle exec rake bundleupdate
48
+ $ bundle install
49
49
  ```
50
50
 
51
51
  ## Console
@@ -119,15 +119,14 @@ If you alter an example's title, you may encounter breaking tests.
119
119
  ### Pub/Sub Acceptance Tests
120
120
 
121
121
  The Pub/Sub acceptance tests interact with the live service API. Follow the
122
- instructions in the {file:AUTHENTICATION.md Authentication guide} for enabling
122
+ instructions in the {file:AUTHENTICATION.md Authentication Guide} for enabling
123
123
  the Pub/Sub API. Occasionally, some API features may not yet be generally
124
124
  available, making it difficult for some contributors to successfully run the
125
125
  entire acceptance test suite. However, please ensure that you do successfully
126
126
  run acceptance tests for any code areas covered by your pull request.
127
127
 
128
128
  To run the acceptance tests, first create and configure a project in the Google
129
- Developers Console, as described in the {file:AUTHENTICATION.md Authentication
130
- guide}. Be sure to download the JSON KEY file. Make note of the PROJECT_ID and
129
+ Developers Console, as described in the {file:AUTHENTICATION.md Authentication Guide}. Be sure to download the JSON KEY file. Make note of the PROJECT_ID and
131
130
  the KEYFILE location on your system.
132
131
 
133
132
  Before you can run the Pub/Sub acceptance tests, you must first create indexes
data/LOGGING.md CHANGED
@@ -3,7 +3,7 @@
3
3
  To enable logging for this library, set the logger for the underlying
4
4
  [gRPC](https://github.com/grpc/grpc/tree/master/src/ruby) library. The logger
5
5
  that you set may be a Ruby stdlib
6
- [`Logger`](https://ruby-doc.org/stdlib-2.5.0/libdoc/logger/rdoc/Logger.html) as
6
+ [`Logger`](https://ruby-doc.org/stdlib/libdoc/logger/rdoc/Logger.html) as
7
7
  shown below, or a
8
8
  [`Google::Cloud::Logging::Logger`](https://googleapis.dev/ruby/google-cloud-logging/latest)
9
9
  that will write logs to [Stackdriver
data/OVERVIEW.md CHANGED
@@ -205,13 +205,16 @@ sleep
205
205
  Messages also can be pulled directly in a one-time operation. (See
206
206
  {Google::Cloud::PubSub::Subscription#pull Subscription#pull})
207
207
 
208
+ The `immediate: false` option is recommended to avoid adverse impacts on the
209
+ performance of pull operations.
210
+
208
211
  ```ruby
209
212
  require "google/cloud/pubsub"
210
213
 
211
214
  pubsub = Google::Cloud::PubSub.new
212
215
 
213
216
  sub = pubsub.subscription "my-topic-sub"
214
- received_messages = sub.pull
217
+ received_messages = sub.pull immediate: false
215
218
  ```
216
219
 
217
220
  A maximum number of messages to pull can be specified:
@@ -222,7 +225,7 @@ require "google/cloud/pubsub"
222
225
  pubsub = Google::Cloud::PubSub.new
223
226
 
224
227
  sub = pubsub.subscription "my-topic-sub"
225
- received_messages = sub.pull max: 10
228
+ received_messages = sub.pull immediate: false, max: 10
226
229
  ```
227
230
 
228
231
  ## Acknowledging a Message
@@ -263,7 +266,7 @@ require "google/cloud/pubsub"
263
266
  pubsub = Google::Cloud::PubSub.new
264
267
 
265
268
  sub = pubsub.subscription "my-topic-sub"
266
- received_messages = sub.pull
269
+ received_messages = sub.pull immediate: false
267
270
  sub.acknowledge received_messages
268
271
  ```
269
272
 
@@ -328,7 +331,7 @@ require "google/cloud/pubsub"
328
331
  pubsub = Google::Cloud::PubSub.new
329
332
 
330
333
  sub = pubsub.subscription "my-topic-sub"
331
- received_messages = sub.pull
334
+ received_messages = sub.pull immediate: false
332
335
  sub.modify_ack_deadline 120, received_messages
333
336
  ```
334
337
 
@@ -474,7 +477,7 @@ sub = pubsub.subscription "my-topic-sub"
474
477
 
475
478
  snapshot = sub.create_snapshot
476
479
 
477
- received_messages = sub.pull
480
+ received_messages = sub.pull immediate: false
478
481
  sub.acknowledge received_messages
479
482
 
480
483
  sub.seek snapshot
@@ -521,5 +524,5 @@ sub.topic.name #=> "projects/other-project-id/topics/other-topic"
521
524
  ## Additional information
522
525
 
523
526
  Google Cloud Pub/Sub can be configured to use an emulator or to enable gRPC's
524
- logging. To learn more, see the {file:EMULATOR.md Emulator guide} and
527
+ logging. To learn more, see the {file:EMULATOR.md Emulator guide}} and
525
528
  {file:LOGGING.md Logging guide}.
@@ -44,8 +44,8 @@ module Google
44
44
  #
45
45
  # topic.async_publisher.stop!
46
46
  #
47
- # @attr_reader [String] topic_name The name of the topic the messages are published to. In the form of
48
- # "/projects/project-identifier/topics/topic-name".
47
+ # @attr_reader [String] topic_name The name of the topic the messages are published to. The value is a
48
+ # fully-qualified topic name in the form `projects/{project_id}/topics/{topic_id}`.
49
49
  # @attr_reader [Integer] max_bytes The maximum size of messages to be collected before the batch is published.
50
50
  # Default is 1,000,000 (1MB).
51
51
  # @attr_reader [Integer] max_messages The maximum number of messages to be collected before the batch is
@@ -59,8 +59,12 @@ module Google
59
59
  class AsyncPublisher
60
60
  include MonitorMixin
61
61
 
62
- attr_reader :topic_name, :max_bytes, :max_messages, :interval,
63
- :publish_threads, :callback_threads
62
+ attr_reader :topic_name
63
+ attr_reader :max_bytes
64
+ attr_reader :max_messages
65
+ attr_reader :interval
66
+ attr_reader :publish_threads
67
+ attr_reader :callback_threads
64
68
  ##
65
69
  # @private Implementation accessors
66
70
  attr_reader :service, :batch, :publish_thread_pool,
@@ -303,7 +307,7 @@ module Google
303
307
 
304
308
  def publish_batches! stop: nil
305
309
  @batches.reject! { |_ordering_key, batch| batch.empty? }
306
- @batches.values.each do |batch|
310
+ @batches.each_value do |batch|
307
311
  ready = batch.publish! stop: stop
308
312
  publish_batch_async @topic_name, batch if ready
309
313
  end
@@ -25,7 +25,8 @@ module Google
25
25
  class Batch
26
26
  include MonitorMixin
27
27
 
28
- attr_reader :items, :ordering_key
28
+ attr_reader :items
29
+ attr_reader :ordering_key
29
30
 
30
31
  def initialize publisher, ordering_key
31
32
  # init MonitorMixin
@@ -13,6 +13,8 @@
13
13
  # limitations under the License.
14
14
 
15
15
 
16
+ require "google/cloud/pubsub/convert"
17
+
16
18
  module Google
17
19
  module Cloud
18
20
  module PubSub
@@ -26,11 +28,12 @@ module Google
26
28
  # pubsub = Google::Cloud::PubSub.new
27
29
  #
28
30
  # topic = pubsub.topic "my-topic"
29
- # msgs = topic.publish do |t|
30
- # t.publish "task 1 completed", foo: :bar
31
- # t.publish "task 2 completed", foo: :baz
32
- # t.publish "task 3 completed", foo: :bif
31
+ # msgs = topic.publish do |batch_publisher|
32
+ # batch_publisher.publish "task 1 completed", foo: :bar
33
+ # batch_publisher.publish "task 2 completed", foo: :baz
34
+ # batch_publisher.publish "task 3 completed", foo: :bif
33
35
  # end
36
+ #
34
37
  class BatchPublisher
35
38
  ##
36
39
  # @private The messages to publish
@@ -38,20 +41,40 @@ module Google
38
41
 
39
42
  ##
40
43
  # @private Create a new instance of the object.
41
- def initialize data = nil, attributes = {}
44
+ def initialize data, attributes, ordering_key, extra_attrs
42
45
  @messages = []
43
46
  @mode = :batch
44
47
  return if data.nil?
45
48
  @mode = :single
46
- publish data, attributes
49
+ publish data, attributes, ordering_key: ordering_key, **extra_attrs
47
50
  end
48
51
 
49
52
  ##
50
53
  # Add a message to the batch to be published to the topic.
51
54
  # All messages added to the batch will be published at once.
52
55
  # See {Google::Cloud::PubSub::Topic#publish}
53
- def publish data, attributes = {}
54
- @messages << create_pubsub_message(data, attributes)
56
+ #
57
+ # @param [String, File] data The message payload. This will be converted
58
+ # to bytes encoded as ASCII-8BIT.
59
+ # @param [Hash] attributes Optional attributes for the message.
60
+ # @param [String] ordering_key Identifies related messages for which
61
+ # publish order should be respected.
62
+ #
63
+ # @example Multiple messages can be sent at the same time using a block:
64
+ # require "google/cloud/pubsub"
65
+ #
66
+ # pubsub = Google::Cloud::PubSub.new
67
+ #
68
+ # topic = pubsub.topic "my-topic"
69
+ # msgs = topic.publish do |batch_publisher|
70
+ # batch_publisher.publish "task 1 completed", foo: :bar
71
+ # batch_publisher.publish "task 2 completed", foo: :baz
72
+ # batch_publisher.publish "task 3 completed", foo: :bif
73
+ # end
74
+ #
75
+ def publish data, attributes = nil, ordering_key: nil, **extra_attrs
76
+ msg = Convert.pubsub_message data, attributes, ordering_key, extra_attrs
77
+ @messages << msg
55
78
  end
56
79
 
57
80
  ##
@@ -69,28 +92,6 @@ module Google
69
92
  msgs
70
93
  end
71
94
  end
72
-
73
- protected
74
-
75
- def create_pubsub_message data, attributes
76
- attributes ||= {}
77
- if data.is_a?(::Hash) && attributes.empty?
78
- attributes = data
79
- data = nil
80
- end
81
- # Convert IO-ish objects to strings
82
- if data.respond_to?(:read) && data.respond_to?(:rewind)
83
- data.rewind
84
- data = data.read
85
- end
86
- # Convert data to encoded byte array to match the protobuf defn
87
- data_bytes = String(data).dup.force_encoding(Encoding::ASCII_8BIT).freeze
88
-
89
- # Convert attributes to strings to match the protobuf definition
90
- attributes = Hash[attributes.map { |k, v| [String(k), String(v)] }]
91
-
92
- Google::Cloud::PubSub::V1::PubsubMessage.new data: data_bytes, attributes: attributes
93
- end
94
95
  end
95
96
  end
96
97
 
@@ -14,7 +14,7 @@
14
14
 
15
15
 
16
16
  require "googleauth"
17
- require "google/cloud/pubsub/v1/publisher/credentials.rb"
17
+ require "google/cloud/pubsub/v1/publisher/credentials"
18
18
 
19
19
  module Google
20
20
  module Cloud
@@ -68,7 +68,8 @@ module Google
68
68
  # end
69
69
  #
70
70
  class Policy
71
- attr_reader :etag, :roles
71
+ attr_reader :etag
72
+ attr_reader :roles
72
73
 
73
74
  ##
74
75
  # @private Creates a Policy object.
@@ -167,7 +168,7 @@ module Google
167
168
  role: role_name,
168
169
  members: roles[role_name]
169
170
  )
170
- end
171
+ end.compact
171
172
  )
172
173
  end
173
174
 
@@ -18,6 +18,7 @@ require "google/cloud/pubsub/service"
18
18
  require "google/cloud/pubsub/credentials"
19
19
  require "google/cloud/pubsub/topic"
20
20
  require "google/cloud/pubsub/batch_publisher"
21
+ require "google/cloud/pubsub/schema"
21
22
  require "google/cloud/pubsub/snapshot"
22
23
 
23
24
  module Google
@@ -75,10 +76,14 @@ module Google
75
76
  ##
76
77
  # Retrieves topic by name.
77
78
  #
78
- # @param [String] topic_name Name of a topic.
79
+ # @param [String] topic_name Name of a topic. The value can be a simple
80
+ # topic ID (relative name), in which case the current project ID will
81
+ # be supplied, or a fully-qualified topic name in the form
82
+ # `projects/{project_id}/topics/{topic_id}`.
79
83
  # @param [String] project If the topic belongs to a project other than
80
84
  # the one currently connected to, the alternate project ID can be
81
- # specified here. Optional.
85
+ # specified here. Optional. Not used if a fully-qualified topic name
86
+ # is provided for `topic_name`.
82
87
  # @param [Boolean] skip_lookup Optionally create a {Topic} object
83
88
  # without verifying the topic resource exists on the Pub/Sub service.
84
89
  # Calls made on this object will raise errors if the topic resource
@@ -147,7 +152,7 @@ module Google
147
152
  ensure_service!
148
153
  options = { project: project }
149
154
  return Topic.from_name topic_name, service, options if skip_lookup
150
- grpc = service.get_topic topic_name
155
+ grpc = service.get_topic topic_name, options
151
156
  Topic.from_grpc grpc, service, async: async
152
157
  rescue Google::Cloud::NotFoundError
153
158
  nil
@@ -158,7 +163,16 @@ module Google
158
163
  ##
159
164
  # Creates a new topic.
160
165
  #
161
- # @param [String] topic_name Name of a topic.
166
+ # @param [String] topic_name Name of a topic. Required.
167
+ # The value can be a simple topic ID (relative name), in which
168
+ # case the current project ID will be supplied, or a fully-qualified
169
+ # topic name in the form `projects/{project_id}/topics/{topic_id}`.
170
+ #
171
+ # The topic ID (relative name) must start with a letter, and
172
+ # contain only letters (`[A-Za-z]`), numbers (`[0-9]`), dashes (`-`),
173
+ # underscores (`_`), periods (`.`), tildes (`~`), plus (`+`) or percent
174
+ # signs (`%`). It must be between 3 and 255 characters in length, and
175
+ # it must not start with `goog`.
162
176
  # @param [Hash] labels A hash of user-provided labels associated with
163
177
  # the topic. You can use these to organize and group your topics.
164
178
  # Label keys and values can be no longer than 63 characters, can only
@@ -179,15 +193,31 @@ module Google
179
193
  #
180
194
  # Hash keys and values may include the following:
181
195
  #
182
- # * `:max_bytes` (Integer) The maximum size of messages to be collected before the batch is published. Default
183
- # is 1,000,000 (1MB).
184
- # * `:max_messages` (Integer) The maximum number of messages to be collected before the batch is published.
185
- # Default is 100.
186
- # * `:interval` (Numeric) The number of seconds to collect messages before the batch is published. Default is
187
- # 0.01.
188
- # * `:threads` (Hash) The number of threads to create to handle concurrent calls by the publisher:
189
- # * `:publish` (Integer) The number of threads used to publish messages. Default is 2.
190
- # * `:callback` (Integer) The number of threads to handle the published messages' callbacks. Default is 4.
196
+ # * `:max_bytes` (Integer) The maximum size of messages to be collected
197
+ # before the batch is published. Default is 1,000,000 (1MB).
198
+ # * `:max_messages` (Integer) The maximum number of messages to be
199
+ # collected before the batch is published. Default is 100.
200
+ # * `:interval` (Numeric) The number of seconds to collect messages before
201
+ # the batch is published. Default is 0.01.
202
+ # * `:threads` (Hash) The number of threads to create to handle concurrent
203
+ # calls by the publisher:
204
+ #
205
+ # * `:publish` (Integer) The number of threads used to publish messages.
206
+ # Default is 2.
207
+ # * `:callback` (Integer) The number of threads to handle the published
208
+ # messages' callbacks. Default is 4.
209
+ # @param [String] schema_name The name of the schema that messages
210
+ # published should be validated against. Optional. The value can be a
211
+ # simple schema ID (relative name), in which case the current project
212
+ # ID will be supplied, or a fully-qualified schema name in the form
213
+ # `projects/{project_id}/schemas/{schema_id}`. If provided,
214
+ # `message_encoding` must also be provided.
215
+ # @param [String, Symbol] message_encoding The encoding of messages validated
216
+ # against the schema identified by `schema_name`. Optional. Values include:
217
+ #
218
+ # * `JSON` - JSON encoding.
219
+ # * `BINARY` - Binary encoding, as defined by the schema type. For some
220
+ # schema types, binary encoding may not be available.
191
221
  #
192
222
  # @return [Google::Cloud::PubSub::Topic]
193
223
  #
@@ -197,12 +227,20 @@ module Google
197
227
  # pubsub = Google::Cloud::PubSub.new
198
228
  # topic = pubsub.create_topic "my-topic"
199
229
  #
200
- def create_topic topic_name, labels: nil, kms_key: nil, persistence_regions: nil, async: nil
230
+ def create_topic topic_name,
231
+ labels: nil,
232
+ kms_key: nil,
233
+ persistence_regions: nil,
234
+ async: nil,
235
+ schema_name: nil,
236
+ message_encoding: nil
201
237
  ensure_service!
202
238
  grpc = service.create_topic topic_name,
203
239
  labels: labels,
204
240
  kms_key_name: kms_key,
205
- persistence_regions: persistence_regions
241
+ persistence_regions: persistence_regions,
242
+ schema_name: schema_name,
243
+ message_encoding: message_encoding
206
244
  Topic.from_grpc grpc, service, async: async
207
245
  end
208
246
  alias new_topic create_topic
@@ -250,10 +288,14 @@ module Google
250
288
  ##
251
289
  # Retrieves subscription by name.
252
290
  #
253
- # @param [String] subscription_name Name of a subscription.
291
+ # @param [String] subscription_name Name of a subscription. The value can
292
+ # be a simple subscription ID, in which case the current project ID
293
+ # will be supplied, or a fully-qualified subscription name in the form
294
+ # `projects/{project_id}/subscriptions/{subscription_id}`.
254
295
  # @param [String] project If the subscription belongs to a project other
255
296
  # than the one currently connected to, the alternate project ID can be
256
- # specified here.
297
+ # specified here. Not used if a fully-qualified subscription name is
298
+ # provided for `subscription_name`.
257
299
  # @param [Boolean] skip_lookup Optionally create a {Subscription} object
258
300
  # without verifying the subscription resource exists on the Pub/Sub
259
301
  # service. Calls made on this object will raise errors if the service
@@ -283,7 +325,7 @@ module Google
283
325
  ensure_service!
284
326
  options = { project: project }
285
327
  return Subscription.from_name subscription_name, service, options if skip_lookup
286
- grpc = service.get_subscription subscription_name
328
+ grpc = service.get_subscription subscription_name, options
287
329
  Subscription.from_grpc grpc, service
288
330
  rescue Google::Cloud::NotFoundError
289
331
  nil
@@ -370,6 +412,198 @@ module Google
370
412
  alias find_snapshots snapshots
371
413
  alias list_snapshots snapshots
372
414
 
415
+ ##
416
+ # Retrieves schema by name.
417
+ #
418
+ # @param [String] schema_name Name of a schema. The value can
419
+ # be a simple schema ID, in which case the current project ID
420
+ # will be supplied, or a fully-qualified schema name in the form
421
+ # `projects/{project_id}/schemas/{schema_id}`.
422
+ # @param view [Symbol, String, nil] Possible values:
423
+ # * `BASIC` - Include the `name` and `type` of the schema, but not the `definition`.
424
+ # * `FULL` - Include all Schema object fields.
425
+ #
426
+ # The default value is `BASIC`.
427
+ # @param [String] project If the schema belongs to a project other
428
+ # than the one currently connected to, the alternate project ID can be
429
+ # specified here. Not used if a fully-qualified schema name is
430
+ # provided for `schema_name`.
431
+ # @param [Boolean] skip_lookup Optionally create a {Schema} object
432
+ # without verifying the schema resource exists on the Pub/Sub
433
+ # service. Calls made on this object will raise errors if the service
434
+ # resource does not exist. Default is `false`.
435
+ #
436
+ # @return [Google::Cloud::PubSub::Schema, nil] Returns `nil` if
437
+ # the schema does not exist.
438
+ #
439
+ # @example
440
+ # require "google/cloud/pubsub"
441
+ #
442
+ # pubsub = Google::Cloud::PubSub.new
443
+ #
444
+ # schema = pubsub.schema "my-schema"
445
+ # schema.name #=> "projects/my-project/schemas/my-schema"
446
+ # schema.type #=> :PROTOCOL_BUFFER
447
+ # # schema.definition # nil - Use view: :full to load complete resource.
448
+ #
449
+ # @example Skip the lookup against the service with `skip_lookup`:
450
+ # require "google/cloud/pubsub"
451
+ #
452
+ # pubsub = Google::Cloud::PubSub.new
453
+ #
454
+ # # No API call is made to retrieve the schema information.
455
+ # # The default project is used in the name.
456
+ # schema = pubsub.schema "my-schema", skip_lookup: true
457
+ # schema.name #=> "projects/my-project/schemas/my-schema"
458
+ # schema.type #=> nil
459
+ # schema.definition #=> nil
460
+ #
461
+ # @example Get the schema definition with `view: :full`:
462
+ # require "google/cloud/pubsub"
463
+ #
464
+ # pubsub = Google::Cloud::PubSub.new
465
+ #
466
+ # schema = pubsub.schema "my-schema", view: :full
467
+ # schema.name #=> "projects/my-project/schemas/my-schema"
468
+ # schema.type #=> :PROTOCOL_BUFFER
469
+ # schema.definition # The schema definition
470
+ #
471
+ def schema schema_name, view: nil, project: nil, skip_lookup: nil
472
+ ensure_service!
473
+ options = { project: project }
474
+ return Schema.from_name schema_name, view, service, options if skip_lookup
475
+ view ||= :BASIC
476
+ grpc = service.get_schema schema_name, view, options
477
+ Schema.from_grpc grpc, service
478
+ rescue Google::Cloud::NotFoundError
479
+ nil
480
+ end
481
+ alias get_schema schema
482
+ alias find_schema schema
483
+
484
+ ##
485
+ # Creates a new schema.
486
+ #
487
+ # @param [String] schema_id The ID to use for the schema, which will
488
+ # become the final component of the schema's resource name. Required.
489
+ #
490
+ # The schema ID (relative name) must start with a letter, and
491
+ # contain only letters (`[A-Za-z]`), numbers (`[0-9]`), dashes (`-`),
492
+ # underscores (`_`), periods (`.`), tildes (`~`), plus (`+`) or percent
493
+ # signs (`%`). It must be between 3 and 255 characters in length, and
494
+ # it must not start with `goog`.
495
+ # @param [String, Symbol] type The type of the schema. Required. Possible
496
+ # values are case-insensitive and include:
497
+ #
498
+ # * `PROTOCOL_BUFFER` - A Protocol Buffer schema definition.
499
+ # * `AVRO` - An Avro schema definition.
500
+ # @param [String] definition The definition of the schema. Required. This
501
+ # should be a string representing the full definition of the schema that
502
+ # is a valid schema definition of the type specified in `type`.
503
+ # @param [String] project If the schema belongs to a project other
504
+ # than the one currently connected to, the alternate project ID can be
505
+ # specified here. Optional.
506
+ #
507
+ # @return [Google::Cloud::PubSub::Schema]
508
+ #
509
+ # @example
510
+ # require "google/cloud/pubsub"
511
+ #
512
+ # pubsub = Google::Cloud::PubSub.new
513
+ #
514
+ # definition = "..."
515
+ # schema = pubsub.create_schema "my-schema", :avro, definition
516
+ # schema.name #=> "projects/my-project/schemas/my-schema"
517
+ #
518
+ def create_schema schema_id, type, definition, project: nil
519
+ ensure_service!
520
+ type = type.to_s.upcase
521
+ grpc = service.create_schema schema_id, type, definition, project: project
522
+ Schema.from_grpc grpc, service
523
+ end
524
+ alias new_schema create_schema
525
+
526
+ ##
527
+ # Retrieves a list of schemas for the given project.
528
+ #
529
+ # @param view [String, Symbol, nil] The set of fields to return in the response. Possible values:
530
+ #
531
+ # * `BASIC` - Include the `name` and `type` of the schema, but not the `definition`.
532
+ # * `FULL` - Include all Schema object fields.
533
+ #
534
+ # The default value is `BASIC`.
535
+ # @param [String] token A previously-returned page token representing
536
+ # part of the larger set of results to view.
537
+ # @param [Integer] max Maximum number of schemas to return.
538
+ #
539
+ # @return [Array<Google::Cloud::PubSub::Schema>] (See
540
+ # {Google::Cloud::PubSub::Schema::List})
541
+ #
542
+ # @example
543
+ # require "google/cloud/pubsub"
544
+ #
545
+ # pubsub = Google::Cloud::PubSub.new
546
+ #
547
+ # schemas = pubsub.schemas
548
+ # schemas.each do |schema|
549
+ # puts schema.name
550
+ # end
551
+ #
552
+ # @example Retrieve all schemas: (See {Schema::List#all})
553
+ # require "google/cloud/pubsub"
554
+ #
555
+ # pubsub = Google::Cloud::PubSub.new
556
+ #
557
+ # schemas = pubsub.schemas
558
+ # schemas.all do |schema|
559
+ # puts schema.name
560
+ # end
561
+ #
562
+ def schemas view: nil, token: nil, max: nil
563
+ ensure_service!
564
+ view ||= :BASIC
565
+ options = { token: token, max: max }
566
+ grpc = service.list_schemas view, options
567
+ Schema::List.from_grpc grpc, service, view, max
568
+ end
569
+ alias find_schemas schemas
570
+ alias list_schemas schemas
571
+
572
+ ##
573
+ # Validates a schema type and definition.
574
+ #
575
+ # @param [String, Symbol] type The type of the schema. Required. Possible
576
+ # values are case-insensitive and include:
577
+ #
578
+ # * `PROTOCOL_BUFFER` - A Protocol Buffer schema definition.
579
+ # * `AVRO` - An Avro schema definition.
580
+ # @param [String] definition The definition of the schema. Required. This
581
+ # should be a string representing the full definition of the schema that
582
+ # is a valid schema definition of the type specified in `type`.
583
+ # @param [String] project If the schema belongs to a project other
584
+ # than the one currently connected to, the alternate project ID can be
585
+ # specified here. Optional.
586
+ #
587
+ # @return [Boolean] `true` if the schema is valid, `false` otherwise.
588
+ #
589
+ # @example
590
+ # require "google/cloud/pubsub"
591
+ #
592
+ # pubsub = Google::Cloud::PubSub.new
593
+ #
594
+ # definition = "..."
595
+ # pubsub.validate_schema :avro, definition #=> true
596
+ #
597
+ def valid_schema? type, definition, project: nil
598
+ ensure_service!
599
+ type = type.to_s.upcase
600
+ service.validate_schema type, definition, project: project # return type is empty
601
+ true
602
+ rescue Google::Cloud::InvalidArgumentError
603
+ false
604
+ end
605
+ alias validate_schema valid_schema?
606
+
373
607
  protected
374
608
 
375
609
  ##