pubsub

Documentation

Overview

Package pubsub is a Google Cloud Pub/Sub client.

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

Example (Auth)

package main

import (
	"log"
	"net/http"

	"github.com/golang/oauth2/google"
	"google.golang.org/cloud"
	"google.golang.org/cloud/pubsub"
)

func main() {
	// Initialize an authorized transport with Google Developers Console
	// JSON key. Read the google package examples to learn more about
	// different authorization flows you can use.
	// http://godoc.org/github.com/golang/oauth2/google
	conf, err := google.NewServiceAccountJSONConfig(
		"/path/to/json/keyfile.json",
		pubsub.ScopeCloudPlatform,
		pubsub.ScopePubSub)
	if err != nil {
		log.Fatal(err)
	}

	c := &http.Client{Transport: conf.NewTransport()}
	ctx := cloud.NewContext("project-id", c)
	_ = ctx // See the other samples to learn how to use the context.
}

Example (PublishAndSubscribe)

package main

import (
	"log"
	"net/http"

	"google.golang.org/cloud"
	"google.golang.org/cloud/pubsub"
)

func main() {
	tr := (http.RoundTripper)(nil) // initiate a RoundTripper. See the auth example.
	ctx := cloud.NewContext("project-id", &http.Client{Transport: tr})

	// Publish hello world on topic1.
	go func() {
		for {
			err := pubsub.Publish(ctx, "topic1", []byte("hello"), nil)
			if err != nil {
				log.Println(err)
			}
		}
	}()

	// sub1 is a subscription that is subscribed to topic1.
	// E.g. c.CreateSub("sub1", "topic1", time.Duration(0), "")
	for {
		m, err := pubsub.PullWait(ctx, "sub1")
		if err != nil {
			log.Println(err)
		} else {
			log.Println("new message arrived:", m)
			if err := pubsub.Ack(ctx, "sub1", m.AckID); err != nil {
				log.Println("error while acknowledging the message:", err)
			}
		}
	}
}

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, deadline time.Duration) error
• func ModifyPushEndpoint(ctx context.Context, sub, endpoint string) error
• func Publish(ctx context.Context, topic string, data []byte, labels map[string]string) error
• func SubExists(ctx context.Context, name string) (bool, error)
• func TopicExists(ctx context.Context, name string) (bool, error)
• type Message
  • func Pull(ctx context.Context, sub string) (*Message, error)
  • func PullWait(ctx context.Context, sub string) (*Message, error)

Examples

• Package (Auth)
• Package (PublishAndSubscribe)

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. It will return an error if topic already exists.

func DeleteSub

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

DeleteSub deletes the subscription.

func DeleteTopic

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

DeleteTopic deletes the specified topic.

func ModifyAckDeadline

func ModifyAckDeadline(ctx context.Context, sub 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, data []byte, labels map[string]string) error

Publish publishes a new message to the specified topic's subscribers. You don't have to label your message. Use nil if there are no labels. Label values could be either int64 or string. It will return an error if you provide a value of another kind.

func SubExists

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

SubExists returns true if subscription exists.

func TopicExists

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

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

Types

type Message

type Message struct {
	// AckID is the identifier to acknowledge this message.
	AckID string

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

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

Message represents a Pub/Sub message.

func Pull

func Pull(ctx context.Context, sub string) (*Message, error)

Pull pulls a new message from the specified subscription queue.

func PullWait

func PullWait(ctx context.Context, sub string) (*Message, error)

PullWait pulls a new message from the specified subscription queue. If there are no messages left in the subscription queue, it will block until a new message arrives or timeout occurs.