pubsub

Documentation

Overview

Package pubsub contains a Google Cloud Pub/Sub client.

This package is experimental and may make backwards-incompatible changes.

More information about Google Cloud Pub/Sub is available at https://cloud.google.com/pubsub/docs

Index

• Constants
• func Ack(ctx context.Context, sub string, id ...string) error
• func CreateSub(ctx context.Context, name string, topic string, deadline time.Duration, ...) error
• func CreateTopic(ctx context.Context, name string) error
• func DeleteSub(ctx context.Context, name string) error
• func DeleteTopic(ctx context.Context, name string) error
• func ModifyAckDeadline(ctx context.Context, sub string, id string, deadline time.Duration) error
• func ModifyPushEndpoint(ctx context.Context, sub, endpoint string) error
• func Publish(ctx context.Context, topic string, msgs ...*Message) ([]string, error)
• func SubExists(ctx context.Context, name string) (bool, error)
• func TopicExists(ctx context.Context, name string) (bool, error)
• type Client
  • func NewClient(ctx context.Context, projectID string, opts ...cloud.ClientOption) (*Client, error)
  • func (c *Client) NewTopic(ctx context.Context, name string) (*TopicHandle, error)
  • func (c *Client) Subscription(name string) *SubscriptionHandle
  • func (c *Client) Subscriptions(ctx context.Context) ([]*SubscriptionHandle, error)
  • func (c *Client) Topic(name string) *TopicHandle
  • func (c *Client) Topics(ctx context.Context) ([]*TopicHandle, error)
• type Message
  • func Pull(ctx context.Context, sub string, n int) ([]*Message, error)
  • func PullWait(ctx context.Context, sub string, n int) ([]*Message, error)
• type SubscriptionConfig
• type SubscriptionHandle
  • func (s *SubscriptionHandle) Delete(ctx context.Context) error
  • func (s *SubscriptionHandle) Exists(ctx context.Context) (bool, error)
  • func (s *SubscriptionHandle) Name() string
• type TopicHandle
  • func (t *TopicHandle) Delete(ctx context.Context) error
  • func (t *TopicHandle) Exists(ctx context.Context) (bool, error)
  • func (t *TopicHandle) Name() string
  • func (t *TopicHandle) Subscribe(ctx context.Context, name string, config *SubscriptionConfig) (*SubscriptionHandle, error)
  • func (t *TopicHandle) Subscriptions(ctx context.Context) ([]*SubscriptionHandle, error)

Constants

const (
	// ScopePubSub grants permissions to view and manage Pub/Sub
	// topics and subscriptions.
	ScopePubSub = "https://www.googleapis.com/auth/pubsub"

	// ScopeCloudPlatform grants permissions to view and manage your data
	// across Google Cloud Platform services.
	ScopeCloudPlatform = "https://www.googleapis.com/auth/cloud-platform"
)

Functions

func Ack

func Ack(ctx context.Context, sub string, id ...string) error

Ack acknowledges one or more Pub/Sub messages on the specified subscription.

func CreateSub

func CreateSub(ctx context.Context, name string, topic string, deadline time.Duration, endpoint string) error

CreateSub creates a Pub/Sub subscription on the backend.

A subscription should subscribe to an existing topic.

The messages that haven't acknowledged will be pushed back to the subscription again when the default acknowledgement deadline is reached. You can override the default deadline by providing a non-zero deadline. Deadline must not be specified to precision greater than one second.

As new messages are being queued on the subscription, you may recieve push notifications regarding to the new arrivals. To receive notifications of new messages in the queue, specify an endpoint callback URL. If endpoint is an empty string the backend will not notify the client of new messages.

If the subscription already exists an error will be returned.

func CreateTopic

func CreateTopic(ctx context.Context, name string) error

CreateTopic creates a new topic with the specified name on the backend.

Deprecated: Use Client.NewTopic instead.

It will return an error if topic already exists.

func DeleteSub

func DeleteSub(ctx context.Context, name string) error

DeleteSub deletes the subscription.

Deprecated: Use SubscriptionHandle.Delete instead.

func DeleteTopic

func DeleteTopic(ctx context.Context, name string) error

DeleteTopic deletes the specified topic.

Deprecated: Use TopicHandle.Delete instead.

func ModifyAckDeadline

func ModifyAckDeadline(ctx context.Context, sub string, id string, deadline time.Duration) error

ModifyAckDeadline modifies the acknowledgement deadline for the messages retrieved from the specified subscription. Deadline must not be specified to precision greater than one second.

func ModifyPushEndpoint

func ModifyPushEndpoint(ctx context.Context, sub, endpoint string) error

ModifyPushEndpoint modifies the URL endpoint to modify the resource to handle push notifications coming from the Pub/Sub backend for the specified subscription.

func Publish

func Publish(ctx context.Context, topic string, msgs ...*Message) ([]string, error)

Publish publish messages to the topic's subscribers. It returns message IDs upon success.

func SubExists

func SubExists(ctx context.Context, name string) (bool, error)

SubExists returns true if subscription exists.

Deprecated: Use SubscriptionHandle.Exists instead.

func TopicExists

func TopicExists(ctx context.Context, name string) (bool, error)

TopicExists returns true if a topic exists with the specified name.

Deprecated: Use TopicHandle.Exists instead.

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client is a Google Pub/Sub client, which may be used to perform Pub/Sub operations with a project. Note: Some operations are not yet available via Client, and must be performed via the legacy standalone functions. It must be constructed via NewClient.

func NewClient

func NewClient(ctx context.Context, projectID string, opts ...cloud.ClientOption) (*Client, error)

NewClient create a new PubSub client.

func (*Client) NewTopic

func (c *Client) NewTopic(ctx context.Context, name string) (*TopicHandle, error)

NewTopic creates a new topic. The specified topic name must start with a letter, and contain only letters ([A-Za-z]), numbers ([0-9]), dashes (-), underscores (_), periods (.), tildes (~), plus (+) or percent signs (%). It must be between 3 and 255 characters in length, and must not start with "goog". If the topic already exists an error will be returned.

func (*Client) Subscription

func (c *Client) Subscription(name string) *SubscriptionHandle

Subscription creates a reference to a subscription.

func (*Client) Subscriptions

func (c *Client) Subscriptions(ctx context.Context) ([]*SubscriptionHandle, error)

Subscriptions lists all of the subscriptions for the client's project.

func (*Client) Topic

func (c *Client) Topic(name string) *TopicHandle

Topic creates a reference to a topic.

func (*Client) Topics

func (c *Client) Topics(ctx context.Context) ([]*TopicHandle, error)

Topics lists all of the topics for the client's project.

type Message

type Message struct {
	// ID identifies this message.
	ID string

	// AckID is the identifier to acknowledge this message.
	AckID string

	// Data is the actual data in the message.
	Data []byte

	// Attributes represents the key-value pairs the current message
	// is labelled with.
	Attributes map[string]string
}

Message represents a Pub/Sub message.

func Pull

func Pull(ctx context.Context, sub string, n int) ([]*Message, error)

Pull pulls up to n messages from the subscription. n must not be larger than 100.

func PullWait

func PullWait(ctx context.Context, sub string, n int) ([]*Message, error)

PullWait pulls up to n messages from the subscription. If there are no messages in the queue, it will wait until at least one message is available or a timeout occurs. n must not be larger than 100.

type SubscriptionConfig

type SubscriptionConfig struct {
}

TODO(mcgreevy): Allow configuring a PushConfig (endpoint and attributes) and default ack deadline.

type SubscriptionHandle

type SubscriptionHandle struct {
	// contains filtered or unexported fields
}

SubscriptionHandle is a reference to a PubSub subscription.

func (*SubscriptionHandle) Delete

func (s *SubscriptionHandle) Delete(ctx context.Context) error

Delete deletes the subscription.

func (*SubscriptionHandle) Exists

func (s *SubscriptionHandle) Exists(ctx context.Context) (bool, error)

Exists reports whether the subscription exists on the server.

func (*SubscriptionHandle) Name

func (s *SubscriptionHandle) Name() string

Name returns the globally unique name for the subscription.

type TopicHandle

type TopicHandle struct {
	// contains filtered or unexported fields
}

TopicHandle is a reference to a PubSub topic.

func (*TopicHandle) Delete

func (t *TopicHandle) Delete(ctx context.Context) error

Delete deletes the topic.

func (*TopicHandle) Exists

func (t *TopicHandle) Exists(ctx context.Context) (bool, error)

Exists reports whether the topic exists on the server.

func (*TopicHandle) Name

func (t *TopicHandle) Name() string

Name returns the globally unique name for the topic.

func (*TopicHandle) Subscribe

func (t *TopicHandle) Subscribe(ctx context.Context, name string, config *SubscriptionConfig) (*SubscriptionHandle, error)

Subscribe creates a new subscription to the topic. The specified subscription name must start with a letter, and contain only letters ([A-Za-z]), numbers ([0-9]), dashes (-), underscores (_), periods (.), tildes (~), plus (+) or percent signs (%). It must be between 3 and 255 characters in length, and must not start with "goog". If the subscription already exists an error will be returned.

func (*TopicHandle) Subscriptions

func (t *TopicHandle) Subscriptions(ctx context.Context) ([]*SubscriptionHandle, error)

Subscriptions lists the subscriptions for this topic.