Esta página foi traduzida pela API Cloud Translation.

Solução de problemas gerais

Saiba mais sobre as etapas de solução de problemas que podem ser úteis se você tiver problemas ao usar o Pub/Sub.

Não é possível criar um tópico

Verifique se você tem as permissões necessárias. Para criar um tópico do Pub/Sub, você precisa do papel de gerenciamento de identidade e acesso do Editor do Pub/Sub (roles/pubsub.editor) no projeto. Se você não tiver essa função, entre em contato com o administrador. Para mais informações sobre solução de problemas, consulte as seguintes páginas:

Não é possível criar uma assinatura

Verifique se você fez o seguinte:

Verifique se você tem as permissões necessárias. Para criar uma assinatura do Pub/Sub, você precisa do papel de IAM Editor do Pub/Sub (roles/pubsub.editor) no projeto. Se você não tiver essa função, entre em contato com o administrador.
Especificou um nome para a assinatura.
Especificou o nome de um tópico atual a que você quer anexar a assinatura.
Se você estiver criando uma assinatura push, especifique https:// em letras minúsculas (não http:// ou HTTPS://) como o protocolo para o URL de recebimento no campo pushEndpoint.

Para mais informações sobre a solução de problemas de assinaturas, consulte as seguintes páginas:

Resolver problemas de permissão

As permissões do Pub/Sub controlam quais usuários e contas de serviço podem realizar ações nos seus recursos do Pub/Sub. Quando as permissões são configuradas incorretamente, isso pode levar a erros de permissão negada e interromper o fluxo de mensagens. Os registros de auditoria fornecem um registro detalhado de todas as mudanças de permissão, permitindo que você identifique a origem desses problemas.

Para resolver problemas de permissão do Pub/Sub com registros de auditoria:

Conseguir as permissões necessárias para acessar o Explorador de registros.

Para mais informações, consulte Antes de começar.
No console do Google Cloud, acesse a página do Explorador de registros.

Acessar o Explorador de registros
Selecione um Google Cloud projeto, uma pasta ou uma organização.
Confira uma lista de filtros que você pode usar para encontrar registros relevantes:
- resource.type="pubsub_topic" OR resource.type="pubsub_subscription": use essa consulta como ponto de partida ao resolver problemas que possam envolver mudanças nas configurações de tópicos ou assinaturas ou no controle de acesso. Você pode combinar esse filtro com outros para refinar ainda mais sua pesquisa.
- protoPayload.methodName="google.iam.v1.SetIamPolicy": use essa consulta quando você suspeitar que um problema foi causado por permissões incorretas ou ausentes. Ele ajuda a acompanhar quem fez alterações na política do IAM e quais foram essas mudanças. Isso pode ser útil para resolver problemas como usuários que não conseguem publicar em tópicos ou assinar assinaturas, aplicativos que tiveram o acesso negado aos recursos do Pub/Sub ou mudanças inesperadas no controle de acesso.
- protoPayload.status.code=7: use essa consulta quando encontrar erros explicitamente relacionados a permissões. Isso ajuda a identificar quais ações estão falhando e quem está tentando fazer isso. É possível combinar essa consulta com as anteriores para identificar a mudança específica de recursos e políticas do IAM que pode estar causando a recusa de permissão.
Analise os registros para determinar fatores como o carimbo de data/hora do evento, o responsável pela mudança e o tipo de mudança feita.
Com base nas informações coletadas nos registros de auditoria, é possível realizar ações corretivas.

A assinatura foi excluída

As assinaturas do Pub/Sub podem ser excluídas de duas maneiras principais:

Uma conta de usuário ou de serviço com permissões suficientes exclui intencionalmente a assinatura.
Uma assinatura é excluída automaticamente após um período de inatividade, que é de 31 dias por padrão. Para mais informações sobre a política de expiração de assinaturas, consulte Período de expiração.

Para resolver problemas com uma assinatura excluída, siga estas etapas:

No console do Google Cloud, acesse a página de assinaturas do Pub/Sub e verifique se a assinatura não está mais listada. Para mais informações sobre como listar assinaturas, consulte Listar uma assinatura.
Verifique os registros de auditoria. Acesse a Análise de registros. Use o filtro protoPayload.methodName="google.pubsub.v1.Subscriber.DeleteSubscription" para encontrar as inscrições excluídas. Examine os registros para determinar se alguém excluiu a assinatura ou se ela foi excluída devido à inatividade. InternalExpireInactiveSubscription indica que uma assinatura foi excluída devido à inatividade. Para mais informações sobre como usar os registros de auditoria para resolver problemas, consulte Resolver problemas do Pub/Sub com registros de auditoria.

`403 (Forbidden)` erro

Se você receber esse erro, faça o seguinte:

Verifique se você ativou a API Pub/Sub no Console do Google Cloud.
Confira se quem fez a solicitação tem as permissões necessárias para os recursos relevantes da API Pub/Sub, especialmente se você estiver usando a API Pub/Sub para a comunicação entre projetos.
Se você usa o Dataflow, verifique se o {PROJECT_NUMBER}@cloudservices.gserviceaccount.com e a conta de serviço do Compute Engine {PROJECT_NUMBER}-compute@developer.gserviceaccount.com têm as permissões necessárias no recurso da API Pub/Sub relevante. Para mais informações, consulte Segurança e permissões do Dataflow.
Se você estiver usando o App Engine, verifique a página "Permissões" do projeto para ver se uma conta de serviço do App Engine está listada como um editor do Pub/Sub. Se não houver, adicione sua conta de serviço do App Engine como um editor do Pub/Sub. Normalmente, a conta de serviço do App Engine está no formato <project-id>@appspot.gserviceaccount.com.

Outros códigos de erro comuns

Para conferir uma lista de outros códigos de erro comuns relacionados à API Pub/Sub e as descrições deles, consulte Códigos de erro.

Operações administrativas excessivas

Se você perceber que está gastando muito da cota de operações administrativas, talvez seja necessário refatorar o código. Para ilustrar, considere este pseudocódigo. Neste exemplo, uma operação administrativa (GET) está sendo usada para verificar a presença de uma assinatura antes de tentar consumir os recursos dela. As operações GET e CREATE são do administrador:

if !GetSubscription my-sub {
  CreateSubscription my-sub
}
Consume from subscription my-sub

Um padrão mais eficiente é tentar consumir mensagens da assinatura (supondo que você esteja razoavelmente seguro do nome da assinatura). Nessa abordagem otimista, você só recebe ou cria a assinatura em caso de erro. Por exemplo,

try {
  Consume from subscription my-sub
} catch NotFoundError {
  CreateSubscription my-sub
  Consume from subscription my-sub
}

Use os exemplos de código abaixo para implementar esse padrão na linguagem que você preferir:

Go

Antes de testar esta amostra, siga as instruções de configuração do Go no Guia de início rápido do Pub/Sub: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub Go.

Para autenticar no Pub/Sub, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

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

	"cloud.google.com/go/pubsub"
	"google.golang.org/grpc/codes"
	"google.golang.org/grpc/status"
)

// optimisticSubscribe shows the recommended pattern for optimistically
// assuming a subscription exists prior to receiving messages.
func optimisticSubscribe(w io.Writer, projectID, topicID, subID string) error {
	// projectID := "my-project-id"
	// topicID := "my-topic"
	// subID := "my-sub"
	ctx := context.Background()
	client, err := pubsub.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("pubsub.NewClient: %w", err)
	}
	defer client.Close()

	sub := client.Subscription(subID)

	// Receive messages for 10 seconds, which simplifies testing.
	// Comment this out in production, since `Receive` should
	// be used as a long running operation.
	ctx, cancel := context.WithTimeout(ctx, 10*time.Second)
	defer cancel()

	// Instead of checking if the subscription exists, optimistically try to
	// receive from the subscription.
	err = sub.Receive(ctx, func(_ context.Context, msg *pubsub.Message) {
		fmt.Fprintf(w, "Got from existing subscription: %q\n", string(msg.Data))
		msg.Ack()
	})
	if err != nil {
		if st, ok := status.FromError(err); ok {
			if st.Code() == codes.NotFound {
				// Since the subscription does not exist, create the subscription.
				s, err := client.CreateSubscription(ctx, subID, pubsub.SubscriptionConfig{
					Topic: client.Topic(topicID),
				})
				if err != nil {
					return err
				}
				fmt.Fprintf(w, "Created subscription: %q\n", subID)

				// Pull from the new subscription.
				err = s.Receive(ctx, func(ctx context.Context, msg *pubsub.Message) {
					fmt.Fprintf(w, "Got from new subscription: %q\n", string(msg.Data))
					msg.Ack()
				})
				if err != nil && !errors.Is(err, context.Canceled) {
					return err
				}
			}
		}
	}
	return nil
}

Java

Antes de testar esta amostra, siga as instruções de configuração do Java no Guia de início rápido do Pub/Sub: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub Java.

Para autenticar no Pub/Sub, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.


import com.google.api.gax.rpc.NotFoundException;
import com.google.cloud.pubsub.v1.AckReplyConsumer;
import com.google.cloud.pubsub.v1.MessageReceiver;
import com.google.cloud.pubsub.v1.Subscriber;
import com.google.cloud.pubsub.v1.SubscriptionAdminClient;
import com.google.common.util.concurrent.MoreExecutors;
import com.google.pubsub.v1.ProjectSubscriptionName;
import com.google.pubsub.v1.PubsubMessage;
import com.google.pubsub.v1.PushConfig;
import com.google.pubsub.v1.Subscription;
import com.google.pubsub.v1.TopicName;
import java.io.IOException;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.TimeoutException;

public class OptimisticSubscribeExample {
  public static void main(String... args) throws Exception {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "your-project-id";
    String subscriptionId = "your-subscription-id";
    String topicId = "your-topic-id";

    optimisticSubscribeExample(projectId, subscriptionId, topicId);
  }

  public static void optimisticSubscribeExample(
      String projectId, String subscriptionId, String topicId) throws IOException {
    ProjectSubscriptionName subscriptionName =
        ProjectSubscriptionName.of(projectId, subscriptionId);

    // Instantiate an asynchronous message receiver.
    MessageReceiver receiver =
        (PubsubMessage message, AckReplyConsumer consumer) -> {
          // Handle incoming message, then ack the received message.
          System.out.println("Id: " + message.getMessageId());
          System.out.println("Data: " + message.getData().toStringUtf8());
          consumer.ack();
        };

    Subscriber subscriber = null;
    try {
      subscriber = Subscriber.newBuilder(subscriptionName, receiver).build();

      // Listen for resource NOT_FOUND errors and rebuild the  subscriber and restart subscribing
      // when the current subscriber encounters these errors.
      subscriber.addListener(
          new Subscriber.Listener() {
            public void failed(Subscriber.State from, Throwable failure) {
              System.out.println(failure.getStackTrace());
              if (failure instanceof NotFoundException) {
                try (SubscriptionAdminClient subscriptionAdminClient =
                    SubscriptionAdminClient.create()) {
                  TopicName topicName = TopicName.of(projectId, topicId);
                  // Create a pull subscription with default acknowledgement deadline of 10 seconds.
                  // The client library will automatically extend acknowledgement deadlines.
                  Subscription subscription =
                      subscriptionAdminClient.createSubscription(
                          subscriptionName, topicName, PushConfig.getDefaultInstance(), 10);
                  System.out.println("Created pull subscription: " + subscription.getName());
                  optimisticSubscribeExample(projectId, subscriptionId, topicId);
                } catch (IOException err) {
                  System.out.println("Failed to create pull subscription: " + err.getMessage());
                }
              }
            }
          },
          MoreExecutors.directExecutor());

      subscriber.startAsync().awaitRunning();
      System.out.printf("Listening for messages on %s:\n", subscriptionName.toString());
      subscriber.awaitTerminated(30, TimeUnit.SECONDS);
    } catch (IllegalStateException e) {
      // Prevent an exception from being thrown if it is the expected NotFoundException
      if (!(subscriber.failureCause() instanceof NotFoundException)) {
        throw e;
      }
    } catch (TimeoutException e) {
      subscriber.stopAsync();
    }
  }
}

Node.js

Antes de testar esta amostra, siga as instruções de configuração do Node.js no Guia de início rápido do Pub/Sub: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub Node.js.

Para autenticar no Pub/Sub, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

/**
 * TODO(developer): Uncomment these variables before running the sample.
 */
// const subscriptionNameOrId = 'YOUR_SUBSCRIPTION_NAME_OR_ID';
// const topicNameOrId = 'YOUR_TOPIC_NAME_OR_ID';
// const timeout = 60;

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

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

function optimisticSubscribe(subscriptionNameOrId, topicNameOrId, timeout) {
  // Try using an existing subscription
  let subscription = pubSubClient.subscription(subscriptionNameOrId);

  // Create an event handler to handle messages
  let messageCount = 0;
  const messageHandler = message => {
    console.log(`Received message ${message.id}:`);
    console.log(`\tData: ${message.data}`);
    console.log(`\tAttributes: ${message.attributes}`);
    messageCount += 1;

    // "Ack" (acknowledge receipt of) the message
    message.ack();
  };

  // Set an error handler so that we're notified if the subscription doesn't
  // already exist.
  subscription.on('error', async e => {
    // Resource Not Found
    if (e.code === 5) {
      console.log('Subscription not found, creating it');
      await pubSubClient.createSubscription(
        topicNameOrId,
        subscriptionNameOrId
      );

      // Refresh our subscriber object and re-attach the message handler.
      subscription = pubSubClient.subscription(subscriptionNameOrId);
      subscription.on('message', messageHandler);
    }
  });

  // Listen for new messages until timeout is hit; this will attempt to
  // open the actual subscriber streams. If it fails, the error handler
  // above will be called.
  subscription.on('message', messageHandler);

  // Wait a while for the subscription to run. (Part of the sample only.)
  setTimeout(() => {
    subscription.removeListener('message', messageHandler);
    console.log(`${messageCount} message(s) received.`);
  }, timeout * 1000);
}

Python

Antes de testar esta amostra, siga as instruções de configuração do Python no Guia de início rápido do Pub/Sub: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub Python.

Para autenticar no Pub/Sub, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

from google.api_core.exceptions import NotFound
from google.cloud import pubsub_v1
from concurrent.futures import TimeoutError

# TODO(developer)
# project_id = "your-project-id"
# subscription_id = "your-subscription-id"
# Number of seconds the subscriber should listen for messages
# timeout = 5.0
# topic_id = "your-topic-id"

# Create a subscriber client.
subscriber = pubsub_v1.SubscriberClient()

# The `subscription_path` method creates a fully qualified identifier
# in the form `projects/{project_id}/subscriptions/{subscription_id}`
subscription_path = subscriber.subscription_path(project_id, subscription_id)

# Define callback to be called when a message is received.
def callback(message: pubsub_v1.subscriber.message.Message) -> None:
    # Ack message after processing it.
    message.ack()

# Wrap subscriber in a 'with' block to automatically call close() when done.
with subscriber:
    try:
        # Optimistically subscribe to messages on the subscription.
        streaming_pull_future = subscriber.subscribe(
            subscription_path, callback=callback
        )
        streaming_pull_future.result(timeout=timeout)
    except TimeoutError:
        print("Successfully subscribed until the timeout passed.")
        streaming_pull_future.cancel()  # Trigger the shutdown.
        streaming_pull_future.result()  # Block until the shutdown is complete.
    except NotFound:
        print(f"Subscription {subscription_path} not found, creating it.")

        try:
            # If the subscription does not exist, then create it.
            publisher = pubsub_v1.PublisherClient()
            topic_path = publisher.topic_path(project_id, topic_id)
            subscription = subscriber.create_subscription(
                request={"name": subscription_path, "topic": topic_path}
            )

            if subscription:
                print(f"Subscription {subscription.name} created")
            else:
                raise ValueError("Subscription creation failed.")

            # Subscribe on the created subscription.
            try:
                streaming_pull_future = subscriber.subscribe(
                    subscription.name, callback=callback
                )
                streaming_pull_future.result(timeout=timeout)
            except TimeoutError:
                streaming_pull_future.cancel()  # Trigger the shutdown.
                streaming_pull_future.result()  # Block until the shutdown is complete.
        except Exception as e:
            print(
                f"Exception occurred when creating subscription and subscribing to it: {e}"
            )
    except Exception as e:
        print(f"Exception occurred when attempting optimistic subscribe: {e}")

C++

Antes de testar esta amostra, siga as instruções de configuração do C++ no Guia de início rápido do Pub/Sub: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub C++.

Para autenticar no Pub/Sub, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

auto process_response = [](gc::StatusOr<pubsub::PullResponse> response) {
  if (response) {
    std::cout << "Received message " << response->message << "\n";
    std::move(response->handler).ack();
    return gc::Status();
  }
  if (response.status().code() == gc::StatusCode::kUnavailable &&
      response.status().message() == "no messages returned") {
    std::cout << "No messages returned from Pull()\n";
    return gc::Status();
  }
  return response.status();
};

// Instead of checking if the subscription exists, optimistically try to
// consume from the subscription.
auto status = process_response(subscriber.Pull());
if (status.ok()) return;
if (status.code() != gc::StatusCode::kNotFound) throw std::move(status);

// Since the subscription does not exist, create the subscription.
pubsub_admin::SubscriptionAdminClient subscription_admin_client(
    pubsub_admin::MakeSubscriptionAdminConnection());
google::pubsub::v1::Subscription request;
request.set_name(
    pubsub::Subscription(project_id, subscription_id).FullName());
request.set_topic(
    pubsub::Topic(project_id, std::move(topic_id)).FullName());
auto sub = subscription_admin_client.CreateSubscription(request);
if (!sub) throw std::move(sub).status();

// Consume from the new subscription.
status = process_response(subscriber.Pull());
if (!status.ok()) throw std::move(status);

Node.js (TypeScript)

Antes de testar este exemplo, siga as instruções de configuração do Node.js no Guia de início rápido do Pub/Sub: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub Node.js.

Para autenticar no Pub/Sub, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

/**
 * TODO(developer): Uncomment these variables before running the sample.
 */
// const subscriptionNameOrId = 'YOUR_SUBSCRIPTION_NAME_OR_ID';
// const topicNameOrId = 'YOUR_TOPIC_NAME_OR_ID';
// const timeout = 60;

// Imports the Google Cloud client library
import {PubSub, Message, StatusError} from '@google-cloud/pubsub';

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

function optimisticSubscribe(
  subscriptionNameOrId: string,
  topicNameOrId: string,
  timeout: number
) {
  // Try using an existing subscription
  let subscription = pubSubClient.subscription(subscriptionNameOrId);

  // Create an event handler to handle messages
  let messageCount = 0;
  const messageHandler = (message: Message) => {
    console.log(`Received message ${message.id}:`);
    console.log(`\tData: ${message.data}`);
    console.log(`\tAttributes: ${message.attributes}`);
    messageCount += 1;

    // "Ack" (acknowledge receipt of) the message
    message.ack();
  };

  // Set an error handler so that we're notified if the subscription doesn't
  // already exist.
  subscription.on('error', async (e: StatusError) => {
    // Resource Not Found
    if (e.code === 5) {
      console.log('Subscription not found, creating it');
      await pubSubClient.createSubscription(
        topicNameOrId,
        subscriptionNameOrId
      );

      // Refresh our subscriber object and re-attach the message handler.
      subscription = pubSubClient.subscription(subscriptionNameOrId);
      subscription.on('message', messageHandler);
    }
  });

  // Listen for new messages until timeout is hit; this will attempt to
  // open the actual subscriber streams. If it fails, the error handler
  // above will be called.
  subscription.on('message', messageHandler);

  // Wait a while for the subscription to run. (Part of the sample only.)
  setTimeout(() => {
    subscription.removeListener('message', messageHandler);
    console.log(`${messageCount} message(s) received.`);
  }, timeout * 1000);
}

Solução de problemas gerais

Não é possível criar um tópico

Não é possível criar uma assinatura

Resolver problemas de permissão

A assinatura foi excluída

403 (Forbidden) erro

Outros códigos de erro comuns

Operações administrativas excessivas

Go

Java

Node.js

Python

C++

Node.js (TypeScript)

`403 (Forbidden)` erro