Managing topics and subscriptions

This document provides information about how to create, delete, and administer Pub/Sub topics and subscriptions. For more information about publishing and accessing message data, see the Publisher Guide and Subscriber Overview.

Managing Topics

You can create, delete, and view topics using the API, the Google Cloud Console, or the gcloud command-line tool. See the gcloud pubsub reference for a complete list of Pub/Sub API gcloud commands.

Creating a topic

You must first create a topic before you can publish or subscribe to it. Here is an example showing how to create a topic:

Protocol

Request:

The request must be authenticated with an access token in the Authorization header. To obtain an access token for the current Application Default Credentials: gcloud auth application-default print-access-token.

PUT https://pubsub.googleapis.com/v1/projects/myproject/topics/mytopic
Authorization: Bearer ACCESS_TOKEN
    

Response:

200 OK
{
 "name": "projects/myproject/topics/mytopic"
}

Command-line

  gcloud pubsub topics create myTopic

C#

Before trying this sample, follow the C# setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries. For more information, see the Cloud Pub/Sub C# API reference documentation.

            PublisherServiceApiClient publisher = PublisherServiceApiClient.Create();

            TopicName topicName = new TopicName(projectId, topicId);
            try
            {
                publisher.CreateTopic(topicName);
            }
            catch (RpcException e)
            when (e.Status.StatusCode == StatusCode.AlreadyExists)
            {
                // Already exists.  That's fine.
            }

Go

Before trying this sample, follow the Go setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries. For more information, see the Cloud Pub/Sub Go API reference documentation.

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/pubsub"
)

func create(w io.Writer, projectID, topicID string) error {
	// projectID := "my-project-id"
	// topicID := "my-topic"
	ctx := context.Background()
	client, err := pubsub.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("pubsub.NewClient: %v", err)
	}

	t, err := client.CreateTopic(ctx, topicID)
	if err != nil {
		return fmt.Errorf("CreateTopic: %v", err)
	}
	fmt.Fprintf(w, "Topic created: %v\n", t)
	return nil
}

Java

Before trying this sample, follow the Java setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries. For more information, see the Cloud Pub/Sub Java API reference documentation.

try (TopicAdminClient topicAdminClient = TopicAdminClient.create()) {
  // projectId <=  unique project identifier, eg. "my-project-id"
  // topicId <= "my-topic-id"
  ProjectTopicName topicName = ProjectTopicName.of(projectId, topicId);
  Topic topic = topicAdminClient.createTopic(topicName);
  return topic;
}

Node.js

Before trying this sample, follow the Node.js setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries. For more information, see the Cloud Pub/Sub Node.js API reference documentation.

/**
 * TODO(developer): Uncomment this variable before running the sample.
 */
// const topicName = 'YOUR_TOPIC_NAME';

// Imports the Google Cloud client library
const {PubSub} = require('@google-cloud/pubsub');

// Creates a client; cache this for further use
const pubSubClient = new PubSub();

async function createTopic() {
  // Creates a new topic
  await pubSubClient.createTopic(topicName);
  console.log(`Topic ${topicName} created.`);
}

createTopic();

PHP

Before trying this sample, follow the PHP setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries. For more information, see the Cloud Pub/Sub PHP API reference documentation.

use Google\Cloud\PubSub\PubSubClient;

/**
 * Creates a Pub/Sub topic.
 *
 * @param string $projectId  The Google project ID.
 * @param string $topicName  The Pub/Sub topic name.
 */
function create_topic($projectId, $topicName)
{
    $pubsub = new PubSubClient([
        'projectId' => $projectId,
    ]);
    $topic = $pubsub->createTopic($topicName);

    printf('Topic created: %s' . PHP_EOL, $topic->name());
}

Python

Before trying this sample, follow the Python setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries. For more information, see the Cloud Pub/Sub Python API reference documentation.

from google.cloud import pubsub_v1

# TODO project_id = "Your Google Cloud Project ID"
# TODO topic_name = "Your Pub/Sub topic name"

publisher = pubsub_v1.PublisherClient()
topic_path = publisher.topic_path(project_id, topic_name)

topic = publisher.create_topic(topic_path)

print("Topic created: {}".format(topic))

Ruby

Before trying this sample, follow the Ruby setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries. For more information, see the Cloud Pub/Sub Ruby API reference documentation.

# project_id = "Your Google Cloud Project ID"
# topic_name = "Your Pubsub topic name"
require "google/cloud/pubsub"

pubsub = Google::Cloud::Pubsub.new project: project_id

topic = pubsub.create_topic topic_name

puts "Topic #{topic.name} created."

Deleting a topic

Here is an example showing how to delete a topic:

Protocol

Request:

The request must be authenticated with an access token in the Authorization header. To obtain an access token for the current Application Default Credentials: gcloud auth application-default print-access-token.

DELETE https://pubsub.googleapis.com/v1/projects/myproject/topics/mytopic
Authorization: Bearer ACCESS_TOKEN
    

Response:

200 OK
{
 "name": "projects/myproject/topics/mytopic"
}

gcloud command

  gcloud pubsub topics delete myTopic

C#

Before trying this sample, follow the C# setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries. For more information, see the Cloud Pub/Sub C# API reference documentation.

PublisherServiceApiClient publisher = PublisherServiceApiClient.Create();
TopicName topicName = new TopicName(projectId, topicId);
publisher.DeleteTopic(topicName);
Console.WriteLine("Topic deleted.");

Go

Before trying this sample, follow the Go setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries. For more information, see the Cloud Pub/Sub Go API reference documentation.

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/pubsub"
)

func delete(w io.Writer, projectID, topicID string) error {
	// projectID := "my-project-id"
	// topicID := "my-topic"
	ctx := context.Background()
	client, err := pubsub.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("pubsub.NewClient: %v", err)
	}

	t := client.Topic(topicID)
	if err := t.Delete(ctx); err != nil {
		return fmt.Errorf("Delete: %v", err)
	}
	fmt.Fprintf(w, "Deleted topic: %v\n", t)
	return nil
}

Java

Before trying this sample, follow the Java setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries. For more information, see the Cloud Pub/Sub Java API reference documentation.

try (TopicAdminClient topicAdminClient = TopicAdminClient.create()) {
  ProjectTopicName topicName = ProjectTopicName.of(projectId, topicId);
  topicAdminClient.deleteTopic(topicName);
  return topicName;
}

Node.js

Before trying this sample, follow the Node.js setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries. For more information, see the Cloud Pub/Sub Node.js API reference documentation.

/**
 * TODO(developer): Uncomment this variable before running the sample.
 */
// const topicName = 'YOUR_TOPIC_NAME';

// Imports the Google Cloud client library
const {PubSub} = require('@google-cloud/pubsub');

// Creates a client; cache this for further use
const pubSubClient = new PubSub();

async function deleteTopic() {
  /**
   * TODO(developer): Uncomment the following line to run the sample.
   */
  // const topicName = 'my-topic';

  // Deletes the topic
  await pubSubClient.topic(topicName).delete();
  console.log(`Topic ${topicName} deleted.`);
}

deleteTopic().catch(console.error);

PHP

Before trying this sample, follow the PHP setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries. For more information, see the Cloud Pub/Sub PHP API reference documentation.

use Google\Cloud\PubSub\PubSubClient;

/**
 * Creates a Pub/Sub topic.
 *
 * @param string $projectId  The Google project ID.
 * @param string $topicName  The Pub/Sub topic name.
 */
function delete_topic($projectId, $topicName)
{
    $pubsub = new PubSubClient([
        'projectId' => $projectId,
    ]);
    $topic = $pubsub->topic($topicName);
    $topic->delete();

    printf('Topic deleted: %s' . PHP_EOL, $topic->name());
}

Python

Before trying this sample, follow the Python setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries. For more information, see the Cloud Pub/Sub Python API reference documentation.

from google.cloud import pubsub_v1

# TODO project_id = "Your Google Cloud Project ID"
# TODO topic_name = "Your Pub/Sub topic name"

publisher = pubsub_v1.PublisherClient()
topic_path = publisher.topic_path(project_id, topic_name)

publisher.delete_topic(topic_path)

print("Topic deleted: {}".format(topic_path))

Ruby

Before trying this sample, follow the Ruby setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries. For more information, see the Cloud Pub/Sub Ruby API reference documentation.

# project_id = "Your Google Cloud Project ID"
# topic_name = "Your Pubsub topic name"
require "google/cloud/pubsub"

pubsub = Google::Cloud::Pubsub.new project: project_id

topic = pubsub.topic topic_name
topic.delete

puts "Topic #{topic_name} deleted."

When you delete a topic, its subscriptions are not deleted, and the subscription's message backlog is available for subscribers. After a topic is deleted, its subscriptions have the topic name _deleted-topic_. If you try to create a topic with the same name as a topic you had just deleted, expect an error for a brief period of time after the deletion.

Listing topics

Here is an example showing how to get a list of topics:

Protocol

Request:

The request must be authenticated with an access token in the Authorization header. To obtain an access token for the current Application Default Credentials: gcloud auth application-default print-access-token.

GET https://pubsub.googleapis.com/v1/projects/myproject/topics
Authorization: Bearer ACCESS_TOKEN
    

Response:

200 OK
{
  "topics": [
    {
      "name": "projects/myproject/topics/mytopic1"
    },
    {
      "name": "projects/myproject/topics/mytopic2"
    }
  ]
}

gcloud command

   gcloud pubsub topics list

C#

Before trying this sample, follow the C# setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries. For more information, see the Cloud Pub/Sub C# API reference documentation.

ProjectName projectName = new ProjectName(projectId);
IEnumerable<Topic> topics = publisher.ListTopics(projectName);
foreach (Topic topic in topics)
{
    Console.WriteLine($"{topic.Name}");
}

Go

Before trying this sample, follow the Go setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries. For more information, see the Cloud Pub/Sub Go API reference documentation.

import (
	"context"
	"fmt"

	"cloud.google.com/go/pubsub"
	"google.golang.org/api/iterator"
)

func list(projectID string) ([]*pubsub.Topic, error) {
	// projectID := "my-project-id"
	ctx := context.Background()
	client, err := pubsub.NewClient(ctx, projectID)
	if err != nil {
		return nil, fmt.Errorf("pubsub.NewClient: %v", err)
	}

	var topics []*pubsub.Topic

	it := client.Topics(ctx)
	for {
		topic, err := it.Next()
		if err == iterator.Done {
			break
		}
		if err != nil {
			return nil, fmt.Errorf("Next: %v", err)
		}
		topics = append(topics, topic)
	}

	return topics, nil
}

Java

Before trying this sample, follow the Java setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries. For more information, see the Cloud Pub/Sub Java API reference documentation.

try (TopicAdminClient topicAdminClient = TopicAdminClient.create()) {
  ListTopicsRequest listTopicsRequest =
      ListTopicsRequest.newBuilder().setProject(ProjectName.format(projectId)).build();
  ListTopicsPagedResponse response = topicAdminClient.listTopics(listTopicsRequest);
  Iterable<Topic> topics = response.iterateAll();
  for (Topic topic : topics) {
    // do something with the topic
  }
  return response;
}

Node.js

Before trying this sample, follow the Node.js setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries. For more information, see the Cloud Pub/Sub Node.js API reference documentation.

// Imports the Google Cloud client library
const {PubSub} = require('@google-cloud/pubsub');

// Creates a client; cache this for further use
const pubSubClient = new PubSub();

async function listAllTopics() {
  // Lists all topics in the current project
  const [topics] = await pubSubClient.getTopics();
  console.log('Topics:');
  topics.forEach(topic => console.log(topic.name));
}

listAllTopics().catch(console.error);

PHP

Before trying this sample, follow the PHP setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries. For more information, see the Cloud Pub/Sub PHP API reference documentation.

use Google\Cloud\PubSub\PubSubClient;

/**
 * Lists all Pub/Sub topics.
 *
 * @param string $projectId  The Google project ID.
 */
function list_topics($projectId)
{
    $pubsub = new PubSubClient([
        'projectId' => $projectId,
    ]);
    foreach ($pubsub->topics() as $topic) {
        printf('Topic: %s' . PHP_EOL, $topic->name());
    }
}

Python

Before trying this sample, follow the Python setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries. For more information, see the Cloud Pub/Sub Python API reference documentation.

from google.cloud import pubsub_v1

# TODO project_id = "Your Google Cloud Project ID"

publisher = pubsub_v1.PublisherClient()
project_path = publisher.project_path(project_id)

for topic in publisher.list_topics(project_path):
    print(topic)

Ruby

Before trying this sample, follow the Ruby setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries. For more information, see the Cloud Pub/Sub Ruby API reference documentation.

# project_id = "Your Google Cloud Project ID"
require "google/cloud/pubsub"

pubsub = Google::Cloud::Pubsub.new project: project_id

topics = pubsub.topics

puts "Topics in project:"
topics.each do |topic|
  puts topic.name
end
By default, a maximum of 100 results are returned per query. You can specify an alternative value up to 1,000 using the page size parameter.

Managing Subscriptions

This section covers how to manage push and pull subscriptions. See the Subscriber Overview for an overview and comparison of pull and push subscriptions.

You must create a subscription to a topic before subscribers can receive messages published to the topic.

Creating subscriptions

You can create subscriptions with the Cloud Console, gcloud command-line tool, or the Cloud Pub/Sub API.

Console

To create a subscription, complete the following steps.

  1. In the Cloud Console, go to the Subscriptions page.

    Go to the Subscriptions page

  2. Click Create subscription.

  3. Enter the Subscription ID.

  4. Choose or create a topic from the drop-down menu. The subscription receives messages from the topic.

  5. Click Create.

You can also create a subscription from the Topics section. This shortcut is useful for associating topics with subscriptions.

  1. In the Cloud Console, go to the Topics page.

    Go to the Topics page

  2. Clicknext to the topic on which to create a subscription.

  3. From the context menu, select Create subscription.

    The context menu with the Create subscription option highlighted.

  4. Enter the Subscription ID.

  5. Click Create.

gcloud

To create a subscription, run the gcloud pubsub subscriptions create command.

gcloud pubsub subscriptions create SUBSCRIPTION_ID
  --topic=TOPIC_ID
  [--ack-deadline=ACK_DEADLINE]
  [--message-retention-duration=MESSAGE_RETENTION_DURATION]
  [--expiration-period=EXPIRATION_PERIOD]
  [--push-endpoint=PUSH_ENDPOINT]
  [--dead-letter-topic=DEAD_LETTER_TOPIC_ID
  --max-delivery-attemptsMAX_DELIVERY_ATTEMPTS]

API

To create a subscription, use the projects.subscriptions.create method.

Protocol

Request:

The request must be authenticated with an access token in the Authorization header. To obtain an access token for the current Application Default Credentials: gcloud auth application-default print-access-token.

PUT https://pubsub.googleapis.com/v1/projects/myproject/subscriptions/mysubscription
Authorization: Bearer ACCESS_TOKEN

Specify the following fields in the request body:

{
  "topic": "projects/someproject/topics/sometopic"
  // Only needed if you are using push delivery
  "pushConfig": {
    "pushEndpoint": "https://myproject.appspot.com/myhandler"
  }
}

Response:

200 OK
{
  "name": "projects/myproject/subscriptions/mysubscription",
  "topic": "projects/someproject/topics/sometopic",
  "pushConfig": {
    "pushEndpoint": "https://myproject.appspot.com/myhandler"
  },
  "ackDeadlineSeconds": 10
}

C#

Before trying this sample, follow the C# setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries. For more information, see the Cloud Pub/Sub C# API reference documentation.

SubscriberServiceApiClient subscriber = SubscriberServiceApiClient.Create();
TopicName topicName = new TopicName(projectId, topicId);
SubscriptionName subscriptionName = new SubscriptionName(projectId,
    subscriptionId);
try
{
    Subscription subscription = subscriber.CreateSubscription(
        subscriptionName, topicName, pushConfig: null,
        ackDeadlineSeconds: 60);
}
catch (RpcException e)
when (e.Status.StatusCode == StatusCode.AlreadyExists)
{
    // Already exists.  That's fine.
}

Go

Before trying this sample, follow the Go setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries. For more information, see the Cloud Pub/Sub Go API reference documentation.

import (
	"context"
	"fmt"
	"io"
	"time"

	"cloud.google.com/go/pubsub"
)

func create(w io.Writer, projectID, subID string, topic *pubsub.Topic) error {
	// projectID := "my-project-id"
	// subID := "my-sub"
	// topic of type https://godoc.org/cloud.google.com/go/pubsub#Topic
	ctx := context.Background()
	client, err := pubsub.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("pubsub.NewClient: %v", err)
	}

	sub, err := client.CreateSubscription(ctx, subID, pubsub.SubscriptionConfig{
		Topic:       topic,
		AckDeadline: 20 * time.Second,
	})
	if err != nil {
		return fmt.Errorf("CreateSubscription: %v", err)
	}
	fmt.Fprintf(w, "Created subscription: %v\n", sub)
	return nil
}

Java

Before trying this sample, follow the Java setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries. For more information, see the Cloud Pub/Sub Java API reference documentation.

try (SubscriptionAdminClient subscriptionAdminClient = SubscriptionAdminClient.create()) {
  // eg. projectId = "my-test-project", topicId = "my-test-topic"
  ProjectTopicName topicName = ProjectTopicName.of(projectId, topicId);
  // eg. subscriptionId = "my-test-subscription"
  ProjectSubscriptionName subscriptionName =
      ProjectSubscriptionName.of(projectId, subscriptionId);
  // create a pull subscription with default acknowledgement deadline
  Subscription subscription =
      subscriptionAdminClient.createSubscription(
          subscriptionName, topicName, PushConfig.getDefaultInstance(), 0);
  return subscription;
}

Node.js

Before trying this sample, follow the Node.js setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries. For more information, see the Cloud Pub/Sub Node.js API reference documentation.

/**
 * TODO(developer): Uncomment these variables before running the sample.
 */
// const topicName = 'YOUR_TOPIC_NAME';
// const subscriptionName = 'YOUR_SUBSCRIPTION_NAME';

// Imports the Google Cloud client library
const {PubSub} = require('@google-cloud/pubsub');

// Creates a client; cache this for further use
const pubSubClient = new PubSub();

async function createSubscription() {
  // Creates a new subscription
  await pubSubClient.topic(topicName).createSubscription(subscriptionName);
  console.log(`Subscription ${subscriptionName} created.`);
}

createSubscription().catch(console.error);

PHP

Before trying this sample, follow the PHP setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries. For more information, see the Cloud Pub/Sub PHP API reference documentation.

use Google\Cloud\PubSub\PubSubClient;

/**
 * Creates a Pub/Sub subscription.
 *
 * @param string $projectId  The Google project ID.
 * @param string $topicName  The Pub/Sub topic name.
 * @param string $subscriptionName  The Pub/Sub subscription name.
 */
function create_subscription($projectId, $topicName, $subscriptionName)
{
    $pubsub = new PubSubClient([
        'projectId' => $projectId,
    ]);
    $topic = $pubsub->topic($topicName);
    $subscription = $topic->subscription($subscriptionName);
    $subscription->create();

    printf('Subscription created: %s' . PHP_EOL, $subscription->name());
}

Python

Before trying this sample, follow the Python setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries. For more information, see the Cloud Pub/Sub Python API reference documentation.

from google.cloud import pubsub_v1

# TODO project_id = "Your Google Cloud Project ID"
# TODO topic_name = "Your Pub/Sub topic name"
# TODO subscription_name = "Your Pub/Sub subscription name"

subscriber = pubsub_v1.SubscriberClient()
topic_path = subscriber.topic_path(project_id, topic_name)
subscription_path = subscriber.subscription_path(
    project_id, subscription_name
)

subscription = subscriber.create_subscription(
    subscription_path, topic_path
)

print("Subscription created: {}".format(subscription))

subscriber.close()

Ruby

Before trying this sample, follow the Ruby setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries. For more information, see the Cloud Pub/Sub Ruby API reference documentation.

# project_id        = "Your Google Cloud Project ID"
# topic_name        = "Your Pubsub topic name"
# subscription_name = "Your Pubsub subscription name"
require "google/cloud/pubsub"

pubsub = Google::Cloud::Pubsub.new project: project_id

topic        = pubsub.topic topic_name
subscription = topic.subscribe subscription_name

puts "Pull subscription #{subscription_name} created."

The following samples demonstrate how to create a subscription with push delivery. By default, subscriptions use pull delivery.

Go

Before trying this sample, follow the Go setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries. For more information, see the Cloud Pub/Sub Go API reference documentation.

import (
	"context"
	"fmt"
	"io"
	"time"

	"cloud.google.com/go/pubsub"
)

func createWithEndpoint(w io.Writer, projectID, subID string, topic *pubsub.Topic, endpoint string) error {
	// projectID := "my-project-id"
	// subID := "my-sub"
	// topic of type https://godoc.org/cloud.google.com/go/pubsub#Topic
	// endpoint := "https://my-test-project.appspot.com/push"
	ctx := context.Background()
	client, err := pubsub.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("pubsub.NewClient: %v", err)
	}

	sub, err := client.CreateSubscription(ctx, subID, pubsub.SubscriptionConfig{
		Topic:       topic,
		AckDeadline: 10 * time.Second,
		PushConfig:  pubsub.PushConfig{Endpoint: endpoint},
	})
	if err != nil {
		return fmt.Errorf("CreateSubscription: %v", err)
	}
	fmt.Fprintf(w, "Created subscription: %v\n", sub)
	return nil
}

Java

Before trying this sample, follow the Java setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries. For more information, see the Cloud Pub/Sub Java API reference documentation.

try (SubscriptionAdminClient subscriptionAdminClient = SubscriptionAdminClient.create()) {
  ProjectTopicName topicName = ProjectTopicName.of(projectId, topicId);
  ProjectSubscriptionName subscriptionName =
      ProjectSubscriptionName.of(projectId, subscriptionId);

  // eg. endpoint = "https://my-test-project.appspot.com/push"
  PushConfig pushConfig = PushConfig.newBuilder().setPushEndpoint(endpoint).build();

  // acknowledgement deadline in seconds for the message received over the push endpoint
  int ackDeadlineInSeconds = 10;

  Subscription subscription =
      subscriptionAdminClient.createSubscription(
          subscriptionName, topicName, pushConfig, ackDeadlineInSeconds);
  return subscription;
}

Node.js

Before trying this sample, follow the Node.js setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries. For more information, see the Cloud Pub/Sub Node.js API reference documentation.

/**
 * TODO(developer): Uncomment these variables before running the sample.
 */
// const topicName = 'YOUR_TOPIC_NAME';
// const subscriptionName = 'YOUR_SUBSCRIPTION_NAME';

// Imports the Google Cloud client library
const {PubSub} = require('@google-cloud/pubsub');

// Creates a client; cache this for further use
const pubSubClient = new PubSub();

async function createPushSubscription() {
  const options = {
    pushConfig: {
      // Set to an HTTPS endpoint of your choice. If necessary, register
      // (authorize) the domain on which the server is hosted.
      pushEndpoint: `https://${pubSubClient.projectId}.appspot.com/push`,
    },
  };

  await pubSubClient
    .topic(topicName)
    .createSubscription(subscriptionName, options);
  console.log(`Subscription ${subscriptionName} created.`);
}

createPushSubscription().catch(console.error);

PHP

Before trying this sample, follow the PHP setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries. For more information, see the Cloud Pub/Sub PHP API reference documentation.

use Google\Cloud\PubSub\PubSubClient;

/**
 * Creates a Pub/Sub push subscription.
 *
 * @param string $projectId  The Google project ID.
 * @param string $topicName  The Pub/Sub topic name.
 * @param string $subscriptionName  The Pub/Sub subscription name.
 * @param string $endpoint  The endpoint for the push subscription.
 */
function create_push_subscription($projectId, $topicName, $subscriptionName, $endpoint)
{
    $pubsub = new PubSubClient([
        'projectId' => $projectId,
    ]);
    $topic = $pubsub->topic($topicName);
    $subscription = $topic->subscription($subscriptionName);
    $subscription->create([
        'pushConfig' => ['pushEndpoint' => $endpoint]
    ]);

    printf('Subscription created: %s' . PHP_EOL, $subscription->name());
}

Python

Before trying this sample, follow the Python setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries. For more information, see the Cloud Pub/Sub Python API reference documentation.

from google.cloud import pubsub_v1

# TODO project_id = "Your Google Cloud Project ID"
# TODO topic_name = "Your Pub/Sub topic name"
# TODO subscription_name = "Your Pub/Sub subscription name"
# TODO endpoint = "https://my-test-project.appspot.com/push"

subscriber = pubsub_v1.SubscriberClient()
topic_path = subscriber.topic_path(project_id, topic_name)
subscription_path = subscriber.subscription_path(
    project_id, subscription_name
)

push_config = pubsub_v1.types.PushConfig(push_endpoint=endpoint)

subscription = subscriber.create_subscription(
    subscription_path, topic_path, push_config
)

print("Push subscription created: {}".format(subscription))
print("Endpoint for subscription is: {}".format(endpoint))

subscriber.close()

Ruby

Before trying this sample, follow the Ruby setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries. For more information, see the Cloud Pub/Sub Ruby API reference documentation.

# project_id        = "Your Google Cloud Project ID"
# topic_name        = "Your Pubsub topic name"
# subscription_name = "Your Pubsub subscription name"
# endpoint          = "Endpoint where your app receives messages"
require "google/cloud/pubsub"

pubsub = Google::Cloud::Pubsub.new project: project_id

topic        = pubsub.topic topic_name
subscription = topic.subscribe subscription_name,
                               endpoint: endpoint

puts "Push subscription #{subscription_name} created."

Using subscription properties

You can set subscription properties when you create or update a subscription. For more information about setting subscription properties with gcloud command-line tool, see the gcloud pubsub subscriptions create or gcloud pubsub subscriptions update optional flags.

Subscriptions have the following properties:

Property Description Default
Delivery method

You can receive messages with pull or push delivery. In pull delivery, your subscriber application initiates requests to the Pub/Sub server to retrieve messages. In push delivery, Pub/Sub initiates requests to your subscriber application to deliver messages.

If unspecified, Pub/Sub subscriptions use pull delivery.

Acknowledgement deadline

If your code doesn't acknowledge the message before the deadline, the message is sent again.

10 seconds is the default acknowledgement deadline. The maximum is 10 minutes.

Message retention duration

The message retention duration specifies how long Cloud Pub/Sub retains messages after publication. After the message retention duration Cloud Pub/Sub might discard the message, regardless of its acknowledgment state.

To retain acknowledged messages for the message retention duration, see Replaying and discarding messages.

7 days is the default message retention duration. The minimum is 10 minutes and the maximum is 7 days.
Dead-letter topics

When a subscriber can't acknowledge a message, Pub/Sub can forward the message to a dead-letter topic. For details, see Forwarding to dead-letter topics.

If you set a dead-letter topic, you can also specify the maximum number of delivery attempts. The default is 5 delivery attempts and you can specify 5-100 delivery attempts.

If you set a dead-letter topic and the topic is in a different project than the subscription, you must also specify the project ID with the dead-letter topic.

Expiration period

Subscriptions without subscriber activity (such as open connections, active pulls, or successful pushes) expire. If Pub/Sub detects subscriber activity, the subscription deletion clock restarts.

31 days is the default expiration period. The minimum is 1 day.

To prevent a subscription from expiring, set the expiration period to never.

Modifying delivery methods

You can switch between push and pull subscriptions with the Cloud Console, gcloud command-line tool, or the Cloud Pub/Sub API.

Console

  1. In the Cloud Console, go to the Subscriptions page.

    Go to the Subscriptions page

  2. Clicknext to the subscription to update.

  3. From the context menu, select Edit.

    The context menu with the Edit option highlighted.

  4. In the Delivery Type, choose Pull or Push.

  5. Click Update.

gcloud

To modify the push endpoint URL, run the modify-push-config command:

gcloud pubsub subscriptions modify-push-config SUBSCRIPTION_ID
  --push-endpoint=PUSH_ENDPOINT

If the subscription is already using pull delivery, setting the push endpoint switches the delivery method to push delivery.

You can switch from push to pull delivery by changing the push endpoint to an empty string.

API

To modify the push endpoint URL, use the projects.subscriptions.modifyPushConfig method.

Go

Before trying this sample, follow the Go setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries. For more information, see the Cloud Pub/Sub Go API reference documentation.

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/pubsub"
)

func updateEndpoint(w io.Writer, projectID, subID string, endpoint string) error {
	// projectID := "my-project-id"
	// subID := "my-sub"
	// endpoint := "https://my-test-project.appspot.com/push"
	ctx := context.Background()
	client, err := pubsub.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("pubsub.NewClient: %v", err)
	}

	subConfig, err := client.Subscription(subID).Update(ctx, pubsub.SubscriptionConfigToUpdate{
		PushConfig: &pubsub.PushConfig{Endpoint: endpoint},
	})
	if err != nil {
		return fmt.Errorf("Update: %v", err)
	}
	fmt.Fprintf(w, "Updated subscription config: %v\n", subConfig)
	return nil
}

Java

Before trying this sample, follow the Java setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries. For more information, see the Cloud Pub/Sub Java API reference documentation.

try (SubscriptionAdminClient subscriptionAdminClient = SubscriptionAdminClient.create()) {
  ProjectSubscriptionName subscriptionName =
      ProjectSubscriptionName.of(projectId, subscriptionId);
  PushConfig pushConfig = PushConfig.newBuilder().setPushEndpoint(endpoint).build();
  subscriptionAdminClient.modifyPushConfig(subscriptionName, pushConfig);
}

Node.js

Before trying this sample, follow the Node.js setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries. For more information, see the Cloud Pub/Sub Node.js API reference documentation.

/**
 * TODO(developer): Uncomment these variables before running the sample.
 */
// const topicName = 'YOUR_TOPIC_NAME';
// const subscriptionName = 'YOUR_SUBSCRIPTION_NAME';

// Imports the Google Cloud client library
const {PubSub} = require('@google-cloud/pubsub');

// Creates a client; cache this for further use
const pubSubClient = new PubSub();

async function modifyPushConfig() {
  const options = {
    // Set to an HTTPS endpoint of your choice. If necessary, register
    // (authorize) the domain on which the server is hosted.
    pushEndpoint: `https://${pubSubClient.projectId}.appspot.com/push`,
  };

  await pubSubClient
    .topic(topicName)
    .subscription(subscriptionName)
    .modifyPushConfig(options);
  console.log(`Modified push config for subscription ${subscriptionName}.`);
}

modifyPushConfig().catch(console.error);

Python

Before trying this sample, follow the Python setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries. For more information, see the Cloud Pub/Sub Python API reference documentation.

from google.cloud import pubsub_v1

# TODO project_id = "Your Google Cloud Project ID"
# TODO topic_name = "Your Pub/Sub topic name"
# TODO subscription_name = "Your Pub/Sub subscription name"
# TODO endpoint = "https://my-test-project.appspot.com/push"

subscriber = pubsub_v1.SubscriberClient()
subscription_path = subscriber.subscription_path(
    project_id, subscription_name
)

push_config = pubsub_v1.types.PushConfig(push_endpoint=endpoint)

subscription = pubsub_v1.types.Subscription(
    name=subscription_path, push_config=push_config
)

update_mask = {"paths": {"push_config"}}
subscriber.update_subscription(subscription, update_mask)
result = subscriber.get_subscription(subscription_path)

print("Subscription updated: {}".format(subscription_path))
print("New endpoint for subscription is: {}".format(result.push_config))

subscriber.close()

Ruby

Before trying this sample, follow the Ruby setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries. For more information, see the Cloud Pub/Sub Ruby API reference documentation.

# project_id        = "Your Google Cloud Project ID"
# subscription_name = "Your Pubsub subscription name"
# new_endpoint      = "Endpoint where your app receives messages""
require "google/cloud/pubsub"

pubsub = Google::Cloud::Pubsub.new project: project_id

subscription          = pubsub.subscription subscription_name
subscription.endpoint = new_endpoint

puts "Push endpoint updated."

If the subscription is already using pull delivery, setting the push endpoint switches the delivery method to push delivery.

You can switch from push to pull delivery by changing the push endpoint to an empty string.

Listing subscriptions

You can list the subscriptions in a Google Cloud project with the Cloud Console, gcloud command-line tool, or Cloud Pub/Sub API.

Console

To list the subscriptions in a project, go to the Subscriptions page.

Go to the Subscriptions page

gcloud

To list the subscriptions in a Google Cloud project, run the gcloud pubsub subscriptions list command:

gcloud pubsub subscriptions list
   [--project=PROJECT_ID]

API

To list the subscriptions in a Google Cloud project, use the projects.subscriptions.list method.

C#

Before trying this sample, follow the C# setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries. For more information, see the Cloud Pub/Sub C# API reference documentation.

SubscriberServiceApiClient subscriber = SubscriberServiceApiClient.Create();
ProjectName projectName = new ProjectName(projectId);
IEnumerable<Subscription> subscriptions =
    subscriber.ListSubscriptions(projectName);
foreach (Subscription subscription in subscriptions)
{
    Console.WriteLine($"{subscription}");
}

Go

Before trying this sample, follow the Go setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries. For more information, see the Cloud Pub/Sub Go API reference documentation.

import (
	"context"
	"fmt"

	"cloud.google.com/go/pubsub"
	"google.golang.org/api/iterator"
)

func list(projectID string) ([]*pubsub.Subscription, error) {
	// projectID := "my-project-id"
	ctx := context.Background()
	client, err := pubsub.NewClient(ctx, projectID)
	if err != nil {
		return nil, fmt.Errorf("pubsub.NewClient: %v", err)
	}

	var subs []*pubsub.Subscription
	it := client.Subscriptions(ctx)
	for {
		s, err := it.Next()
		if err == iterator.Done {
			break
		}
		if err != nil {
			return nil, fmt.Errorf("Next: %v", err)
		}
		subs = append(subs, s)
	}
	return subs, nil
}

Java

Before trying this sample, follow the Java setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries. For more information, see the Cloud Pub/Sub Java API reference documentation.

try (SubscriptionAdminClient subscriptionAdminClient = SubscriptionAdminClient.create()) {
  ListSubscriptionsRequest listSubscriptionsRequest =
      ListSubscriptionsRequest.newBuilder()
          .setProject(ProjectName.of(projectId).toString())
          .build();
  ListSubscriptionsPagedResponse response =
      subscriptionAdminClient.listSubscriptions(listSubscriptionsRequest);
  Iterable<Subscription> subscriptions = response.iterateAll();
  for (Subscription subscription : subscriptions) {
    // do something with the subscription
  }
  return response;
}

Node.js

Before trying this sample, follow the Node.js setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries. For more information, see the Cloud Pub/Sub Node.js API reference documentation.

// Imports the Google Cloud client library
const {PubSub} = require('@google-cloud/pubsub');

// Creates a client; cache this for further use
const pubSubClient = new PubSub();

async function listSubscriptions() {
  // Lists all subscriptions in the current project
  const [subscriptions] = await pubSubClient.getSubscriptions();
  console.log('Subscriptions:');
  subscriptions.forEach(subscription => console.log(subscription.name));
}

listSubscriptions().catch(console.error);

PHP

Before trying this sample, follow the PHP setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries. For more information, see the Cloud Pub/Sub PHP API reference documentation.

use Google\Cloud\PubSub\PubSubClient;

/**
 * Lists all Pub/Sub subscriptions.
 *
 * @param string $projectId  The Google project ID.
 */
function list_subscriptions($projectId)
{
    $pubsub = new PubSubClient([
        'projectId' => $projectId,
    ]);
    foreach ($pubsub->subscriptions() as $subscription) {
        printf('Subscription: %s' . PHP_EOL, $subscription->name());
    }
}

Python

Before trying this sample, follow the Python setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries. For more information, see the Cloud Pub/Sub Python API reference documentation.

from google.cloud import pubsub_v1

# TODO project_id = "Your Google Cloud Project ID"

subscriber = pubsub_v1.SubscriberClient()
project_path = subscriber.project_path(project_id)

for subscription in subscriber.list_subscriptions(project_path):
    print(subscription.name)

subscriber.close()

Ruby

Before trying this sample, follow the Ruby setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries. For more information, see the Cloud Pub/Sub Ruby API reference documentation.

# project_id = Your Google Cloud Project ID
require "google/cloud/pubsub"

pubsub = Google::Cloud::Pubsub.new project: project_id

subscriptions = pubsub.list_subscriptions

puts "Subscriptions:"
subscriptions.each do |subscription|
  puts subscription.name
end

You can list the subscriptions to a topic with the Cloud Console, gcloud command-line tool, or Cloud Pub/Sub API.

Console

  1. In the Cloud Console, go to the Topics page.

    Go to the Topics page

  2. Select a topic ID to open the Topic details page. The Subscriptions section of the page includes of list of subscriptions to the topic.

gcloud

To list the subscriptions in a Google Cloud project, run the gcloud pubsub topics list-subscriptions command:

gcloud pubsub topics list-subscriptions TOPIC_ID

API

To list the subscriptions in a Google Cloud project, use the projects.topics.subscriptions.list method.

Go

Before trying this sample, follow the Go setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries. For more information, see the Cloud Pub/Sub Go API reference documentation.

import (
	"context"
	"fmt"

	"cloud.google.com/go/pubsub"
	"google.golang.org/api/iterator"
)

func listSubscriptions(projectID, topicID string) ([]*pubsub.Subscription, error) {
	// projectID := "my-project-id"
	// topicName := "projects/sample-248520/topics/ocr-go-test-topic"
	ctx := context.Background()
	client, err := pubsub.NewClient(ctx, projectID)
	if err != nil {
		return nil, fmt.Errorf("pubsub.NewClient: %v", err)
	}

	var subs []*pubsub.Subscription

	it := client.Topic(topicID).Subscriptions(ctx)
	for {
		sub, err := it.Next()
		if err == iterator.Done {
			break
		}
		if err != nil {
			return nil, fmt.Errorf("Next: %v", err)
		}
		subs = append(subs, sub)
	}
	return subs, nil
}

Java

Before trying this sample, follow the Java setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries. For more information, see the Cloud Pub/Sub Java API reference documentation.

try (TopicAdminClient topicAdminClient = TopicAdminClient.create()) {
  ProjectTopicName topicName = ProjectTopicName.of(projectId, topicId);
  ListTopicSubscriptionsRequest request =
      ListTopicSubscriptionsRequest.newBuilder().setTopic(topicName.toString()).build();
  ListTopicSubscriptionsPagedResponse response =
      topicAdminClient.listTopicSubscriptions(request);
  Iterable<String> subscriptionNames = response.iterateAll();
  for (String subscriptionName : subscriptionNames) {
    // do something with the subscription name
  }
  return response;
}

Node.js

Before trying this sample, follow the Node.js setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries. For more information, see the Cloud Pub/Sub Node.js API reference documentation.

/**
 * TODO(developer): Uncomment this variable before running the sample.
 */
// const topicName = 'YOUR_TOPIC_NAME';

// Imports the Google Cloud client library
const {PubSub} = require('@google-cloud/pubsub');

// Creates a client; cache this for further use
const pubSubClient = new PubSub();

async function listTopicSubscriptions() {
  // Lists all subscriptions for the topic
  const [subscriptions] = await pubSubClient
    .topic(topicName)
    .getSubscriptions();

  console.log(`Subscriptions for ${topicName}:`);
  subscriptions.forEach(subscription => console.log(subscription.name));
}

listTopicSubscriptions().catch(console.error);

Python

Before trying this sample, follow the Python setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries. For more information, see the Cloud Pub/Sub Python API reference documentation.

from google.cloud import pubsub_v1

# TODO project_id = "Your Google Cloud Project ID"
# TODO topic_name = "Your Pub/Sub topic name"

publisher = pubsub_v1.PublisherClient()
topic_path = publisher.topic_path(project_id, topic_name)

for subscription in publisher.list_topic_subscriptions(topic_path):
    print(subscription)

Ruby

Before trying this sample, follow the Ruby setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries. For more information, see the Cloud Pub/Sub Ruby API reference documentation.

# project_id = "Your Google Cloud Project ID"
# topic_name = "Your Pubsub topic name"
require "google/cloud/pubsub"

pubsub = Google::Cloud::Pubsub.new project: project_id

topic         = pubsub.topic topic_name
subscriptions = topic.subscriptions

puts "Subscriptions in topic #{topic.name}:"
subscriptions.each do |subscription|
  puts subscription.name
end

Deleting subscriptions

You can delete subscriptions with the Cloud Console, gcloud command-line tool, or Cloud Pub/Sub API.

Console

  1. In the Cloud Console, go to the Subscriptions page.

    Go to the Subscriptions page

  2. Select the subscription to delete.

  3. Click Delete.

gcloud

To delete a subscription, run the gcloud pubsub subscriptions delete command:

gcloud pubsub subscriptions delete SUBSCRIPTION_ID

API

To delete a subscription, use the projects.topics.subscriptions.delete method.

C#

Before trying this sample, follow the C# setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries. For more information, see the Cloud Pub/Sub C# API reference documentation.

SubscriberServiceApiClient subscriber = SubscriberServiceApiClient.Create();
SubscriptionName subscriptionName = new SubscriptionName(projectId,
    subscriptionId);
subscriber.DeleteSubscription(subscriptionName);
Console.WriteLine("Subscription deleted.");

Go

Before trying this sample, follow the Go setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries. For more information, see the Cloud Pub/Sub Go API reference documentation.

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/pubsub"
)

func delete(w io.Writer, projectID, subID string) error {
	// projectID := "my-project-id"
	// subID := "my-sub"
	ctx := context.Background()
	client, err := pubsub.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("pubsub.NewClient: %v", err)
	}

	sub := client.Subscription(subID)
	if err := sub.Delete(ctx); err != nil {
		return fmt.Errorf("Delete: %v", err)
	}
	fmt.Fprintf(w, "Subscription %q deleted.", subID)
	return nil
}

Java

Before trying this sample, follow the Java setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries. For more information, see the Cloud Pub/Sub Java API reference documentation.

try (SubscriptionAdminClient subscriptionAdminClient = SubscriptionAdminClient.create()) {
  ProjectSubscriptionName subscriptionName =
      ProjectSubscriptionName.of(projectId, subscriptionId);
  subscriptionAdminClient.deleteSubscription(subscriptionName);
  return subscriptionName;
}

Node.js

Before trying this sample, follow the Node.js setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries. For more information, see the Cloud Pub/Sub Node.js API reference documentation.

/**
 * TODO(developer): Uncomment this variable before running the sample.
 */
// const subscriptionName = 'YOUR_SUBSCRIPTION_NAME';

// Imports the Google Cloud client library
const {PubSub} = require('@google-cloud/pubsub');

// Creates a client; cache this for further use
const pubSubClient = new PubSub();

async function deleteSubscription() {
  // Deletes the subscription
  await pubSubClient.subscription(subscriptionName).delete();
  console.log(`Subscription ${subscriptionName} deleted.`);
}

deleteSubscription().catch(console.error);

PHP

Before trying this sample, follow the PHP setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries. For more information, see the Cloud Pub/Sub PHP API reference documentation.

use Google\Cloud\PubSub\PubSubClient;

/**
 * Creates a Pub/Sub subscription.
 *
 * @param string $projectId  The Google project ID.
 * @param string $subscriptionName  The Pub/Sub subscription name.
 */
function delete_subscription($projectId, $subscriptionName)
{
    $pubsub = new PubSubClient([
        'projectId' => $projectId,
    ]);
    $subscription = $pubsub->subscription($subscriptionName);
    $subscription->delete();

    printf('Subscription deleted: %s' . PHP_EOL, $subscription->name());
}

Python

Before trying this sample, follow the Python setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries. For more information, see the Cloud Pub/Sub Python API reference documentation.

from google.cloud import pubsub_v1

# TODO project_id = "Your Google Cloud Project ID"
# TODO subscription_name = "Your Pub/Sub subscription name"

subscriber = pubsub_v1.SubscriberClient()
subscription_path = subscriber.subscription_path(
    project_id, subscription_name
)

subscriber.delete_subscription(subscription_path)

print("Subscription deleted: {}".format(subscription_path))

subscriber.close()

Ruby

Before trying this sample, follow the Ruby setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries. For more information, see the Cloud Pub/Sub Ruby API reference documentation.

# project_id        = "Your Google Cloud Project ID"
# subscription_name = "Your Pubsub subscription name"
require "google/cloud/pubsub"

pubsub = Google::Cloud::Pubsub.new project: project_id

subscription = pubsub.subscription subscription_name
subscription.delete

puts "Subscription #{subscription_name} deleted."

Resource names

A Pub/Sub resource name uniquely identifies a Pub/Sub resource, such as a subscription or topic, and must fit the following format:

projects/project-identifier/collection/relative-name

The project-identifier must be the project ID, available from the Google Cloud Console. For example, projects/myproject/topics/mytopic.

The collection must be one of subscriptions or topics.

The relative-name must:

  • Not begin with the string goog.
  • Start with a letter
  • Contain between 3 and 255 characters
  • Contain only the following characters:

    • Letters: [A-Za-z]
    • Numbers: [0-9]
    • Dashes: -
    • Underscores: _
    • Periods: .
    • Tildes: ~
    • Plus signs: +
    • Percent signs: %

      The special characters in the above list can be used in resource names without URL-encoding. However, you must ensure that any other special characters are properly encoded/decoded when used in URLs. For example, mi-tópico is an invalid relative-name. However, mi-t%C3%B3pico is valid.

      This is particularly important for REST calls.