Crea sottoscrizioni pull

Questo documento descrive come creare una sottoscrizione 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

Autorizzazioni e ruoli richiesti

Per creare un abbonamento, devi configurare il controllo dell'accesso a livello di progetto. Devi disporre delle autorizzazioni a livello di risorsa anche se le sottoscrizioni e gli argomenti si trovano in progetti diversi, come illustrato più avanti in questa sezione.

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

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

Autorizzazioni obbligatorie

Per creare sottoscrizioni pull, sono necessarie le seguenti autorizzazioni:

  • Esegui il pull da una sottoscrizione: pubsub.subscriptions.consume
  • Crea una sottoscrizione: pubsub.subscriptions.create
  • Elimina una sottoscrizione: pubsub.subscriptions.delete
  • Acquista un abbonamento: pubsub.subscriptions.get
  • Elenca un abbonamento: pubsub.subscriptions.list
  • Aggiorna un abbonamento: pubsub.subscriptions.update
  • Allega una sottoscrizione a un argomento: pubsub.topics.attachSubscription
  • Ottieni il criterio IAM per una sottoscrizione: pubsub.subscriptions.getIamPolicy
  • Configura il criterio IAM per un abbonamento: pubsub.subscriptions.setIamPolicy

Potresti anche essere in grado di ottenere queste autorizzazioni con i ruoli personalizzati o altri ruoli predefiniti.

Se devi creare sottoscrizioni 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.

Esegui il pull delle proprietà della sottoscrizione

Quando configuri una sottoscrizione pull, puoi specificare le seguenti proprietà.

Proprietà comuni

Scopri di più sulle proprietà di abbonamento comuni che puoi impostare per tutte le sottoscrizioni.

Consegna "exactly-once"

Distribuzione "exactly-once". Se impostato, Pub/Sub soddisfa le garanzie di consegna exactly-once. Se non specificato, la sottoscrizione supporta la consegna at-least-once per ogni messaggio.

Creare una sottoscrizione pull

I seguenti esempi mostrano come creare una sottoscrizione con consegna pull, utilizzando le impostazioni predefinite fornite.

Console

Per creare una sottoscrizione pull, completa i passaggi riportati di seguito.

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

    Vai ad Abbonamenti

  2. Fai clic su Crea sottoscrizione.

  3. Inserisci un nome nel campo ID abbonamento.

    Per informazioni su come assegnare un nome a una sottoscrizione, consulta le linee guida per assegnare un nome a un argomento o a una sottoscrizione.

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

Puoi creare un abbonamento anche dalla sezione Argomenti. Questa scorciatoia è utile per associare gli argomenti agli abbonamenti.

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

    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 una sottoscrizione, consulta le linee guida per assegnare un nome a un argomento o a una sottoscrizione.

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

gcloud

  1. Nella console Google Cloud, attiva Cloud Shell.

    Attiva Cloud Shell

    Nella parte inferiore della console Google Cloud viene avviata una sessione di Cloud Shell che mostra un prompt della riga di comando. Cloud Shell è un ambiente shell con Google Cloud CLI già installato e con valori già impostati per il progetto attuale. L'inizializzazione della sessione può richiedere alcuni secondi.

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

    Sostituisci quanto segue:

    • SUBSCRIPTION_ID: il nome o l'ID della nuova sottoscrizione 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 Credenziali predefinite dell'applicazione correnti: 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 del tuo 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++ nella guida rapida di Pub/Sub sull'utilizzo delle librerie client. Per maggiori informazioni, consulta la documentazione di riferimento dell'API C++ di Pub/Sub.

    Per eseguire l'autenticazione in Pub/Sub, configura le Credenziali predefinite dell'applicazione. Per maggiori informazioni, 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# nella guida rapida di Pub/Sub sull'utilizzo delle librerie client. Per maggiori informazioni, consulta la documentazione di riferimento dell'API C# di Pub/Sub.

    Per eseguire l'autenticazione in Pub/Sub, configura le Credenziali predefinite dell'applicazione. Per maggiori informazioni, 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 nella guida rapida di Pub/Sub sull'utilizzo delle librerie client. Per maggiori informazioni, consulta la documentazione di riferimento dell'API Go di Pub/Sub.

    Per eseguire l'autenticazione in Pub/Sub, configura le Credenziali predefinite dell'applicazione. Per maggiori informazioni, 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 nella guida rapida di Pub/Sub sull'utilizzo delle librerie client. Per maggiori informazioni, consulta la documentazione di riferimento dell'API Java di Pub/Sub.

    Per eseguire l'autenticazione in Pub/Sub, configura le Credenziali predefinite dell'applicazione. Per maggiori informazioni, 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 nella guida rapida di Pub/Sub sull'utilizzo delle librerie client. Per maggiori informazioni, consulta la documentazione di riferimento dell'API PHP di Pub/Sub.

    Per eseguire l'autenticazione in Pub/Sub, configura le Credenziali predefinite dell'applicazione. Per maggiori informazioni, 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 nella guida rapida di Pub/Sub sull'utilizzo delle librerie client. Per maggiori informazioni, consulta la documentazione di riferimento dell'API Python di Pub/Sub.

    Per eseguire l'autenticazione in Pub/Sub, configura le Credenziali predefinite dell'applicazione. Per maggiori informazioni, 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 nella guida rapida di Pub/Sub sull'utilizzo delle librerie client. Per maggiori informazioni, consulta la documentazione di riferimento dell'API Ruby di Pub/Sub.

    Per eseguire l'autenticazione in Pub/Sub, configura le Credenziali predefinite dell'applicazione. Per maggiori informazioni, 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."

    Passaggi successivi

    • Crea o modifica una sottoscrizione con i comandi gcloud.
    • Creare o modificare una sottoscrizione con le API REST.