1 // Copyright (c) 2015, Google Inc.
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
7 // http://www.apache.org/licenses/LICENSE-2.0
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.
17 package google.pubsub.v1beta2;
19 import "google/protobuf/empty.proto";
21 option go_package = "google.golang.org/genproto/googleapis/pubsub/v1beta2;pubsub";
22 option java_multiple_files = true;
23 option java_outer_classname = "PubsubProto";
24 option java_package = "com.google.pubsub.v1beta2";
26 // The service that an application uses to manipulate subscriptions and to
27 // consume messages from a subscription via the Pull method.
29 // Creates a subscription to a given topic for a given subscriber.
30 // If the subscription already exists, returns ALREADY_EXISTS.
31 // If the corresponding topic doesn't exist, returns NOT_FOUND.
33 // If the name is not provided in the request, the server will assign a random
34 // name for this subscription on the same project as the topic.
35 rpc CreateSubscription(Subscription) returns (Subscription);
37 // Gets the configuration details of a subscription.
38 rpc GetSubscription(GetSubscriptionRequest) returns (Subscription);
40 // Lists matching subscriptions.
41 rpc ListSubscriptions(ListSubscriptionsRequest)
42 returns (ListSubscriptionsResponse);
44 // Deletes an existing subscription. All pending messages in the subscription
45 // are immediately dropped. Calls to Pull after deletion will return
46 // NOT_FOUND. After a subscription is deleted, a new one may be created with
47 // the same name, but the new one has no association with the old
48 // subscription, or its topic unless the same topic is specified.
49 rpc DeleteSubscription(DeleteSubscriptionRequest)
50 returns (google.protobuf.Empty);
52 // Modifies the ack deadline for a specific message. This method is useful to
53 // indicate that more time is needed to process a message by the subscriber,
54 // or to make the message available for redelivery if the processing was
56 rpc ModifyAckDeadline(ModifyAckDeadlineRequest)
57 returns (google.protobuf.Empty);
59 // Acknowledges the messages associated with the ack tokens in the
60 // AcknowledgeRequest. The Pub/Sub system can remove the relevant messages
61 // from the subscription.
63 // Acknowledging a message whose ack deadline has expired may succeed,
64 // but such a message may be redelivered later. Acknowledging a message more
65 // than once will not result in an error.
66 rpc Acknowledge(AcknowledgeRequest) returns (google.protobuf.Empty);
68 // Pulls messages from the server. Returns an empty list if there are no
69 // messages available in the backlog. The server may return UNAVAILABLE if
70 // there are too many concurrent pull requests pending for the given
72 rpc Pull(PullRequest) returns (PullResponse);
74 // Modifies the PushConfig for a specified subscription.
76 // This may be used to change a push subscription to a pull one (signified
77 // by an empty PushConfig) or vice versa, or change the endpoint URL and other
78 // attributes of a push subscription. Messages will accumulate for
79 // delivery continuously through the call regardless of changes to the
81 rpc ModifyPushConfig(ModifyPushConfigRequest) returns (google.protobuf.Empty);
84 // The service that an application uses to manipulate topics, and to send
85 // messages to a topic.
87 // Creates the given topic with the given name.
88 rpc CreateTopic(Topic) returns (Topic);
90 // Adds one or more messages to the topic. Returns NOT_FOUND if the topic does
92 rpc Publish(PublishRequest) returns (PublishResponse);
94 // Gets the configuration of a topic.
95 rpc GetTopic(GetTopicRequest) returns (Topic);
97 // Lists matching topics.
98 rpc ListTopics(ListTopicsRequest) returns (ListTopicsResponse);
100 // Lists the name of the subscriptions for this topic.
101 rpc ListTopicSubscriptions(ListTopicSubscriptionsRequest)
102 returns (ListTopicSubscriptionsResponse);
104 // Deletes the topic with the given name. Returns NOT_FOUND if the topic does
105 // not exist. After a topic is deleted, a new topic may be created with the
106 // same name; this is an entirely new topic with none of the old
107 // configuration or subscriptions. Existing subscriptions to this topic are
109 rpc DeleteTopic(DeleteTopicRequest) returns (google.protobuf.Empty);
114 // Name of the topic.
118 // A message data and its attributes.
119 message PubsubMessage {
120 // The message payload. For JSON requests, the value of this field must be
124 // Optional attributes for this message.
125 map<string, string> attributes = 2;
127 // ID of this message assigned by the server at publication time. Guaranteed
128 // to be unique within the topic. This value may be read by a subscriber
129 // that receives a PubsubMessage via a Pull call or a push delivery. It must
130 // not be populated by a publisher in a Publish call.
131 string message_id = 3;
134 // Request for the GetTopic method.
135 message GetTopicRequest {
136 // The name of the topic to get.
140 // Request for the Publish method.
141 message PublishRequest {
142 // The messages in the request will be published on this topic.
145 // The messages to publish.
146 repeated PubsubMessage messages = 2;
149 // Response for the Publish method.
150 message PublishResponse {
151 // The server-assigned ID of each published message, in the same order as
152 // the messages in the request. IDs are guaranteed to be unique within
154 repeated string message_ids = 1;
157 // Request for the ListTopics method.
158 message ListTopicsRequest {
159 // The name of the cloud project that topics belong to.
162 // Maximum number of topics to return.
165 // The value returned by the last ListTopicsResponse; indicates that this is
166 // a continuation of a prior ListTopics call, and that the system should
167 // return the next page of data.
168 string page_token = 3;
171 // Response for the ListTopics method.
172 message ListTopicsResponse {
173 // The resulting topics.
174 repeated Topic topics = 1;
176 // If not empty, indicates that there may be more topics that match the
177 // request; this value should be passed in a new ListTopicsRequest.
178 string next_page_token = 2;
181 // Request for the ListTopicSubscriptions method.
182 message ListTopicSubscriptionsRequest {
183 // The name of the topic that subscriptions are attached to.
186 // Maximum number of subscription names to return.
189 // The value returned by the last ListTopicSubscriptionsResponse; indicates
190 // that this is a continuation of a prior ListTopicSubscriptions call, and
191 // that the system should return the next page of data.
192 string page_token = 3;
195 // Response for the ListTopicSubscriptions method.
196 message ListTopicSubscriptionsResponse {
197 // The names of the subscriptions that match the request.
198 repeated string subscriptions = 1;
200 // If not empty, indicates that there may be more subscriptions that match
201 // the request; this value should be passed in a new
202 // ListTopicSubscriptionsRequest to get more subscriptions.
203 string next_page_token = 2;
206 // Request for the DeleteTopic method.
207 message DeleteTopicRequest {
208 // Name of the topic to delete.
212 // A subscription resource.
213 message Subscription {
214 // Name of the subscription.
217 // The name of the topic from which this subscription is receiving messages.
218 // This will be present if and only if the subscription has not been detached
222 // If push delivery is used with this subscription, this field is
223 // used to configure it. An empty pushConfig signifies that the subscriber
224 // will pull and ack messages using API methods.
225 PushConfig push_config = 4;
227 // This value is the maximum time after a subscriber receives a message
228 // before the subscriber should acknowledge the message. After message
229 // delivery but before the ack deadline expires and before the message is
230 // acknowledged, it is an outstanding message and will not be delivered
231 // again during that time (on a best-effort basis).
233 // For pull delivery this value
234 // is used as the initial value for the ack deadline. It may be overridden
235 // for a specific message by calling ModifyAckDeadline.
237 // For push delivery, this value is also used to set the request timeout for
238 // the call to the push endpoint.
240 // If the subscriber never acknowledges the message, the Pub/Sub
241 // system will eventually redeliver the message.
242 int32 ack_deadline_seconds = 5;
245 // Configuration for a push delivery endpoint.
247 // A URL locating the endpoint to which messages should be pushed.
248 // For example, a Webhook endpoint might use "https://example.com/push".
249 string push_endpoint = 1;
251 // Endpoint configuration attributes.
253 // Every endpoint has a set of API supported attributes that can be used to
254 // control different aspects of the message delivery.
256 // The currently supported attribute is `x-goog-version`, which you can
257 // use to change the format of the push message. This attribute
258 // indicates the version of the data expected by the endpoint. This
259 // controls the shape of the envelope (i.e. its fields and metadata).
260 // The endpoint version is based on the version of the Pub/Sub
263 // If not present during the CreateSubscription call, it will default to
264 // the version of the API used to make such call. If not present during a
265 // ModifyPushConfig call, its value will not be changed. GetSubscription
266 // calls will always return a valid version, even if the subscription was
267 // created without this attribute.
269 // The possible values for this attribute are:
271 // * `v1beta1`: uses the push format defined in the v1beta1 Pub/Sub API.
272 // * `v1beta2`: uses the push format defined in the v1beta2 Pub/Sub API.
274 map<string, string> attributes = 2;
277 // A message and its corresponding acknowledgment ID.
278 message ReceivedMessage {
279 // This ID can be used to acknowledge the received message.
283 PubsubMessage message = 2;
286 // Request for the GetSubscription method.
287 message GetSubscriptionRequest {
288 // The name of the subscription to get.
289 string subscription = 1;
292 // Request for the ListSubscriptions method.
293 message ListSubscriptionsRequest {
294 // The name of the cloud project that subscriptions belong to.
297 // Maximum number of subscriptions to return.
300 // The value returned by the last ListSubscriptionsResponse; indicates that
301 // this is a continuation of a prior ListSubscriptions call, and that the
302 // system should return the next page of data.
303 string page_token = 3;
306 // Response for the ListSubscriptions method.
307 message ListSubscriptionsResponse {
308 // The subscriptions that match the request.
309 repeated Subscription subscriptions = 1;
311 // If not empty, indicates that there may be more subscriptions that match
312 // the request; this value should be passed in a new ListSubscriptionsRequest
313 // to get more subscriptions.
314 string next_page_token = 2;
317 // Request for the DeleteSubscription method.
318 message DeleteSubscriptionRequest {
319 // The subscription to delete.
320 string subscription = 1;
323 // Request for the ModifyPushConfig method.
324 message ModifyPushConfigRequest {
325 // The name of the subscription.
326 string subscription = 1;
328 // The push configuration for future deliveries.
330 // An empty pushConfig indicates that the Pub/Sub system should
331 // stop pushing messages from the given subscription and allow
332 // messages to be pulled and acknowledged - effectively pausing
333 // the subscription if Pull is not called.
334 PushConfig push_config = 2;
337 // Request for the Pull method.
338 message PullRequest {
339 // The subscription from which messages should be pulled.
340 string subscription = 1;
342 // If this is specified as true the system will respond immediately even if
343 // it is not able to return a message in the Pull response. Otherwise the
344 // system is allowed to wait until at least one message is available rather
345 // than returning no messages. The client may cancel the request if it does
346 // not wish to wait any longer for the response.
347 bool return_immediately = 2;
349 // The maximum number of messages returned for this request. The Pub/Sub
350 // system may return fewer than the number specified.
351 int32 max_messages = 3;
354 // Response for the Pull method.
355 message PullResponse {
356 // Received Pub/Sub messages. The Pub/Sub system will return zero messages if
357 // there are no more available in the backlog. The Pub/Sub system may return
358 // fewer than the maxMessages requested even if there are more messages
359 // available in the backlog.
360 repeated ReceivedMessage received_messages = 1;
363 // Request for the ModifyAckDeadline method.
364 message ModifyAckDeadlineRequest {
365 // The name of the subscription.
366 string subscription = 1;
368 // The acknowledgment ID.
371 // The new ack deadline with respect to the time this request was sent to the
372 // Pub/Sub system. Must be >= 0. For example, if the value is 10, the new ack
373 // deadline will expire 10 seconds after the ModifyAckDeadline call was made.
374 // Specifying zero may immediately make the message available for another pull
376 int32 ack_deadline_seconds = 3;
379 // Request for the Acknowledge method.
380 message AcknowledgeRequest {
381 // The subscription whose message is being acknowledged.
382 string subscription = 1;
384 // The acknowledgment ID for the messages being acknowledged that was returned
385 // by the Pub/Sub system in the Pull response. Must not be empty.
386 repeated string ack_ids = 2;