Creare sottoscrizioni pull

Questo documento descrive come creare un abbonamento pull. Puoi utilizzare la console Google Cloud, Google Cloud CLI, la libreria client o l'API Pub/Sub per creare una sottoscrizione pull.

Prima di iniziare

Ruoli e autorizzazioni richiesti

Per creare un abbonamento, devi configurare il controllo dell'accesso a livello di progetto. Sono inoltre necessarie autorizzazioni a livello di risorsa se le iscrizioni e gli argomenti si trovano in progetti diversi, come spiegato più avanti in questa sezione.

Per ottenere le autorizzazioni necessarie per creare iscrizioni pull, chiedi all'amministratore di concederti il ruolo IAM Editor Pub/Sub (roles/pubsub.editor) nel progetto. Per saperne di più sulla concessione dei ruoli, consulta Gestire l'accesso a progetti, cartelle e organizzazioni.

Questo ruolo predefinito contiene le autorizzazioni necessarie per creare abbonamenti pull. Per visualizzare le autorizzazioni esatte richieste, espandi la sezione Autorizzazioni richieste:

Autorizzazioni obbligatorie

Per creare sottoscrizioni pull sono necessarie le seguenti autorizzazioni:

  • Estrazione da un abbonamento: pubsub.subscriptions.consume
  • Creare un abbonamento: pubsub.subscriptions.create
  • Eliminare un abbonamento: pubsub.subscriptions.delete
  • Acquista un abbonamento: pubsub.subscriptions.get
  • Elencare un abbonamento: pubsub.subscriptions.list
  • Aggiornare un abbonamento: pubsub.subscriptions.update
  • Allega una sottoscrizione a un argomento: pubsub.topics.attachSubscription
  • Recupera il criterio IAM per un abbonamento: pubsub.subscriptions.getIamPolicy
  • Configura il criterio IAM per un abbonamento: pubsub.subscriptions.setIamPolicy

Potresti anche ottenere queste autorizzazioni con ruoli personalizzati o altri ruoli predefiniti.

Se devi creare abbonamenti pull in un progetto associati a un argomento in un altro progetto, chiedi all'amministratore dell'argomento di concederti anche il ruolo IAM Editor Pub/Sub(roles/pubsub.editor) per l'argomento.

Proprietà di sottoscrizione pull

Quando configuri un abbonamento pull, puoi specificare le seguenti proprietà.

Proprietà comuni

Scopri le proprietà comuni degli abbonamenti che puoi impostare su tutti gli abbonamenti.

Consegna "exactly-once"

Pubblicazione "exactly-once". Se impostato, Pub/Sub soddisfa le garanzie di consegna exactly-once. Se non specificato, l'abbonamento supporta la consegna almeno una volta per ogni messaggio.

Creare una sottoscrizione pull

Gli esempi riportati di seguito mostrano come creare una sottoscrizione con caricamento pull utilizzando le impostazioni predefinite fornite.

Console

Per creare un abbonamento pull, completa i seguenti passaggi.

  1. Nella console Google Cloud, vai alla pagina Abbonamenti.

    Vai ad Abbonamenti

  2. Fai clic su Crea sottoscrizione.

  3. Per il campo ID sottoscrizione, inserisci un nome.

    Per informazioni su come assegnare un nome a un abbonamento, consulta Linee guida per assegnare un nome a un argomento o a un abbonamento.

  4. Scegli o crea un argomento dal menu a discesa. La sottoscrizione riceve i messaggi dall'argomento.
  5. Mantieni Tipo di consegna impostato su Pull.
  6. Mantieni invariati tutti gli altri valori predefiniti.
  7. Fai clic su Crea.

Puoi anche creare una sottoscrizione dalla sezione Argomenti. Questa scorciatoia è utile per associare gli argomenti alle sottoscrizioni.

  1. Nella console Google Cloud, vai alla pagina Topic.

    Vai ad Argomenti

  2. Fai clic su accanto all'argomento per cui creare una sottoscrizione.
  3. Dal menu contestuale, seleziona Crea abbonamento.

  4. Inserisci l'ID abbonamento.

    Per informazioni su come assegnare un nome a un abbonamento, consulta Linee guida per assegnare un nome a un argomento o a un abbonamento.

  5. Mantieni Tipo di consegna impostato su Pull.
  6. Mantieni invariati tutti gli altri valori predefiniti.
  7. Fai clic su Crea.

gcloud

  1. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

  2. Per creare una sottoscrizione pull, esegui il gcloud pubsub subscriptions create comando. 
    gcloud pubsub subscriptions create SUBSCRIPTION_ID --topic=TOPIC_ID

    Sostituisci quanto segue:

    • SUBSCRIPTION_ID: il nome o l'ID del nuovo abbonamento pull.
    • TOPIC_ID: il nome o l'ID dell'argomento.

REST

Per creare una sottoscrizione pull, utilizza il metodo projects.subscriptions.create:

Richiesta:

La richiesta deve essere autenticata con un token di accesso nell'intestazione Authorization. Per ottenere un token di accesso per le attuali Credenziali predefinite dell'applicazione: gcloud auth application-default print-access-token. 

PUT https://pubsub.googleapis.com/v1/projects/PROJECT_ID/subscriptions/SUBSCRIPTION_ID
Authorization: Bearer ACCESS_TOKEN

Corpo della richiesta:

{
  "topic": "projects/PROJECT_ID/topics/TOPIC_ID"
}

Dove:

  • PROJECT_ID è l'ID progetto.
  • SUBSCRIPTION_ID è il tuo ID abbonamento.
  • TOPIC_ID è l'ID argomento.

    • Risposta:

    {
  "name": "projects/PROJECT_ID/subscriptions/SUBSCRIPTION_ID",
  "topic": "projects/PROJECT_ID/topics/TOPIC_ID",
  "pushConfig": {},
  "ackDeadlineSeconds": 10,
  "messageRetentionDuration": "604800s",
  "expirationPolicy": {
    "ttl": "2678400s"
  }
}

    C++

    Prima di provare questo esempio, segui le istruzioni di configurazione di C++ riportate nella guida rapida di Pub/Sub che utilizza le librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Pub/Sub C++.

    Per autenticarti a Pub/Sub, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configurare l'autenticazione per le librerie client. 

    namespace pubsub_admin = ::google::cloud::pubsub_admin;
namespace pubsub = ::google::cloud::pubsub;
[](pubsub_admin::SubscriptionAdminClient client,
   std::string const& project_id, std::string const& topic_id,
   std::string const& subscription_id) {
  google::pubsub::v1::Subscription request;
  request.set_name(
      pubsub::Subscription(project_id, subscription_id).FullName());
  request.set_topic(pubsub::Topic(project_id, topic_id).FullName());
  auto sub = client.CreateSubscription(request);
  if (sub.status().code() == google::cloud::StatusCode::kAlreadyExists) {
    std::cout << "The subscription already exists\n";
    return;
  }
  if (!sub) throw std::move(sub).status();

  std::cout << "The subscription was successfully created: "
            << sub->DebugString() << "\n";
}

    C#

    Prima di provare questo esempio, segui le istruzioni di configurazione di C# riportate nella guida rapida di Pub/Sub che utilizza le librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Pub/Sub C#.

    Per autenticarti a Pub/Sub, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configurare l'autenticazione per le librerie client. 

    
using Google.Cloud.PubSub.V1;
using Grpc.Core;

public class CreateSubscriptionSample
{
    public Subscription CreateSubscription(string projectId, string topicId, string subscriptionId)
    {
        SubscriberServiceApiClient subscriber = SubscriberServiceApiClient.Create();
        TopicName topicName = TopicName.FromProjectTopic(projectId, topicId);

        SubscriptionName subscriptionName = SubscriptionName.FromProjectSubscription(projectId, subscriptionId);
        Subscription subscription = null;

        try
        {
            subscription = subscriber.CreateSubscription(subscriptionName, topicName, pushConfig: null, ackDeadlineSeconds: 60);
        }
        catch (RpcException e) when (e.Status.StatusCode == StatusCode.AlreadyExists)
        {
            // Already exists.  That's fine.
        }
        return subscription;
    }
}

    Go

    Prima di provare questo esempio, segui le istruzioni di configurazione di Go riportate nella guida rapida di Pub/Sub che utilizza le librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Pub/Sub Go.

    Per autenticarti a Pub/Sub, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configurare l'autenticazione per le librerie client. 

    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: %w", err)
	}
	defer client.Close()

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

    Java

    Prima di provare questo esempio, segui le istruzioni di configurazione di Java riportate nella guida rapida di Pub/Sub che utilizza le librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Pub/Sub Java.

    Per autenticarti a Pub/Sub, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configurare l'autenticazione per le librerie client. 

    
import com.google.cloud.pubsub.v1.SubscriptionAdminClient;
import com.google.pubsub.v1.PushConfig;
import com.google.pubsub.v1.Subscription;
import com.google.pubsub.v1.SubscriptionName;
import com.google.pubsub.v1.TopicName;
import java.io.IOException;

public class CreatePullSubscriptionExample {
  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";

    createPullSubscriptionExample(projectId, subscriptionId, topicId);
  }

  public static void createPullSubscriptionExample(
      String projectId, String subscriptionId, String topicId) throws IOException {
    try (SubscriptionAdminClient subscriptionAdminClient = SubscriptionAdminClient.create()) {
      TopicName topicName = TopicName.of(projectId, topicId);
      SubscriptionName subscriptionName = SubscriptionName.of(projectId, subscriptionId);
      // Create a pull subscription with default acknowledgement deadline of 10 seconds.
      // Messages not successfully acknowledged within 10 seconds will get resent by the server.
      Subscription subscription =
          subscriptionAdminClient.createSubscription(
              subscriptionName, topicName, PushConfig.getDefaultInstance(), 10);
      System.out.println("Created pull subscription: " + subscription.getName());
    }
  }
}

    Node.js

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

// 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(topicNameOrId, subscriptionNameOrId) {
  // Creates a new subscription
  await pubSubClient
    .topic(topicNameOrId)
    .createSubscription(subscriptionNameOrId);
  console.log(`Subscription ${subscriptionNameOrId} created.`);
}

    Node.js

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

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

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

async function createSubscription(
  topicNameOrId: string,
  subscriptionNameOrId: string
) {
  // Creates a new subscription
  await pubSubClient
    .topic(topicNameOrId)
    .createSubscription(subscriptionNameOrId);
  console.log(`Subscription ${subscriptionNameOrId} created.`);
}

    PHP

    Prima di provare questo esempio, segui le istruzioni di configurazione di PHP riportate nella guida rapida di Pub/Sub che utilizza le librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Pub/Sub PHP.

    Per autenticarti a Pub/Sub, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configurare l'autenticazione per le librerie client. 

    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

    Prima di provare questo esempio, segui le istruzioni di configurazione di Python riportate nella guida rapida di Pub/Sub che utilizza le librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Pub/Sub Python.

    Per autenticarti a Pub/Sub, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configurare l'autenticazione per le librerie client. 

    from google.cloud import pubsub_v1

# TODO(developer)
# project_id = "your-project-id"
# topic_id = "your-topic-id"
# subscription_id = "your-subscription-id"

publisher = pubsub_v1.PublisherClient()
subscriber = pubsub_v1.SubscriberClient()
topic_path = publisher.topic_path(project_id, topic_id)
subscription_path = subscriber.subscription_path(project_id, subscription_id)

# Wrap the subscriber in a 'with' block to automatically call close() to
# close the underlying gRPC channel when done.
with subscriber:
    subscription = subscriber.create_subscription(
        request={"name": subscription_path, "topic": topic_path}
    )

print(f"Subscription created: {subscription}")

    Ruby

    Prima di provare questo esempio, segui le istruzioni di configurazione di Ruby riportate nella guida rapida di Pub/Sub che utilizza le librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Pub/Sub Ruby.

    Per autenticarti a Pub/Sub, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configurare l'autenticazione per le librerie client. 

    # topic_id        = "your-topic-id"
# subscription_id = "your-subscription-id"

pubsub = Google::Cloud::Pubsub.new

topic        = pubsub.topic topic_id
subscription = topic.subscribe subscription_id

puts "Pull subscription #{subscription_id} created."

    Monitorare le sottoscrizioni pull

    Cloud Monitoring fornisce una serie di metriche per monitorare gli abbonamenti.

    Per un elenco di tutte le metriche disponibili relative a Pub/Sub e le relative descrizioni, consulta la documentazione di monitoraggio per Pub/Sub.

    Puoi anche monitorare le iscrizioni dall'interno di Pub/Sub.

    Passaggi successivi