Method: projects.subscriptions.pull

HTTP request
Path parameters
Request body
- JSON representation
Response body
- JSON representation
Authorization scopes
ReceivedMessage
- JSON representation
Try it!

Pulls messages from the server.

HTTP request

Choose a location:

Path parameters

Parameters

Parameters
`subscription`	`string` Required. The subscription from which messages should be pulled. Format is `projects/{project}/subscriptions/{sub}` .

subscription

string

Required. The subscription from which messages should be pulled. Format is projects/{project}/subscriptions/{sub} .

Request body

The request body contains data with the following structure:

JSON representation
{ "returnImmediately" : boolean , "maxMessages" : integer }

Fields

Fields
`returnImmediately (deprecated)`	`boolean` Optional. If this field set to true, the system will respond immediately even if it there are no messages available to return in the `subscriptions.pull` response. Otherwise, the system may wait (for a bounded amount of time) until at least one message is available, rather than returning no messages. Warning: setting this field to `true` is discouraged because it adversely impacts the performance of `subscriptions.pull` operations. We recommend that users do not set this field.
`maxMessages`	`integer` Required. The maximum number of messages to return for this request. Must be a positive integer. The Pub/Sub system may return fewer than the number specified.

returnImmediately
 (deprecated)

boolean

Optional. If this field set to true, the system will respond immediately even if it there are no messages available to return in the subscriptions.pull response. Otherwise, the system may wait (for a bounded amount of time) until at least one message is available, rather than returning no messages. Warning: setting this field to true is discouraged because it adversely impacts the performance of subscriptions.pull operations. We recommend that users do not set this field.

maxMessages

integer

Required. The maximum number of messages to return for this request. Must be a positive integer. The Pub/Sub system may return fewer than the number specified.

Response body

Response for the subscriptions.pull method.

If successful, the response body contains data with the following structure:

JSON representation
{ "receivedMessages" : [ { object ( `ReceivedMessage` ) } ] }

Fields

Fields
`receivedMessages[]`	`object ( ReceivedMessage )` Optional. Received Pub/Sub messages. The list will be empty if there are no more messages available in the backlog, or if no messages could be returned before the request timeout. For JSON, the response can be entirely empty. The Pub/Sub system may return fewer than the `maxMessages` requested even if there are more messages available in the backlog.

receivedMessages[]

object ( ReceivedMessage )

Optional. Received Pub/Sub messages. The list will be empty if there are no more messages available in the backlog, or if no messages could be returned before the request timeout. For JSON, the response can be entirely empty. The Pub/Sub system may return fewer than the maxMessages requested even if there are more messages available in the backlog.

Authorization scopes

Requires one of the following OAuth scopes:

https://www.googleapis.com/auth/pubsub
https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview .

ReceivedMessage

A message and its corresponding acknowledgment ID.

JSON representation
{ "ackId" : string , "message" : { object ( `PubsubMessage` ) } , "deliveryAttempt" : integer }

Fields

Fields
`ackId`	`string` Optional. This ID can be used to acknowledge the received message.
`message`	`object ( PubsubMessage )` Optional. The message.
`deliveryAttempt`	`integer` Optional. The approximate number of times that Pub/Sub has attempted to deliver the associated message to a subscriber. More precisely, this is 1 + (number of NACKs) + (number of ack_deadline exceeds) for this message. A NACK is any call to subscriptions.modifyAckDeadline with a 0 deadline. An ack_deadline exceeds event is whenever a message is not acknowledged within ack_deadline. Note that ack_deadline is initially Subscription.ackDeadlineSeconds, but may get extended automatically by the client library. Upon the first delivery of a given message, `deliveryAttempt` will have a value of 1. The value is calculated at best effort and is approximate. If a DeadLetterPolicy is not set on the subscription, this will be 0.

ackId

string

Optional. This ID can be used to acknowledge the received message.

message

object ( PubsubMessage )

Optional. The message.

deliveryAttempt

integer

Optional. The approximate number of times that Pub/Sub has attempted to deliver the associated message to a subscriber.

More precisely, this is 1 + (number of NACKs) + (number of ack_deadline exceeds) for this message.

A NACK is any call to subscriptions.modifyAckDeadline with a 0 deadline. An ack_deadline exceeds event is whenever a message is not acknowledged within ack_deadline. Note that ack_deadline is initially Subscription.ackDeadlineSeconds, but may get extended automatically by the client library.

Upon the first delivery of a given message, deliveryAttempt will have a value of 1. The value is calculated at best effort and is approximate.

If a DeadLetterPolicy is not set on the subscription, this will be 0.

Method: projects.subscriptions.pull Stay organized with collections Save and categorize content based on your preferences.

HTTP request

Path parameters

Request body

Response body

Authorization scopes

ReceivedMessage

Method: projects.subscriptions.pull