Method: projects.subscriptions.pull

Pulls messages from the server. Returns an empty list if there are no messages available in the backlog. The server may return UNAVAILABLE if there are too many concurrent pull requests pending for the given subscription.

HTTP request

POST https://pubsub.googleapis.com/v1/{subscription}:pull

Path parameters

Parameters
subscription

string

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": number,
}
Fields
returnImmediately

boolean

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. The client may cancel the request if it does not wish to wait any longer for the response.

maxMessages

number

The maximum number of messages returned for this request. The Pub/Sub system may return fewer than the number specified.

Response body

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

Response for the subscriptions.pull method.

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

object(ReceivedMessage)

Received Pub/Sub messages. The Pub/Sub system will return zero messages if there are no more available in the backlog. The Pub/Sub system may return fewer than the maxMessages requested even if there are more messages available in the backlog.

Authorization

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 Auth Guide.

ReceivedMessage

A message and its corresponding acknowledgment ID.

JSON representation
{
  "ackId": string,
  "message": {
    object(PubsubMessage)
  },
}
Fields
ackId

string

This ID can be used to acknowledge the received message.

message

object(PubsubMessage)

The message.

Try it!

Monitor your resources on the go

Get the Google Cloud Console app to help you manage your projects.

Send feedback about...

Cloud Pub/Sub