Crea sottoscrizioni push

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

Prima di iniziare

• Scopri di più sugli abbonamenti.
• Informazioni su come funzionano le iscrizioni push.

Ruoli e autorizzazioni richiesti

Per creare una sottoscrizione, devi configurare il controllo dell'accesso a livello di progetto. Sono necessarie anche le autorizzazioni a livello di risorsa se le sottoscrizioni e gli argomenti si trovano in progetti diversi, come descritto più avanti in questa sezione.

Per ottenere le autorizzazioni necessarie per creare sottoscrizioni push, 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 push. Per visualizzare esattamente le autorizzazioni necessarie, espandi la sezione Autorizzazioni obbligatorie:

Autorizzazioni obbligatorie

Per creare sottoscrizioni push sono necessarie le seguenti autorizzazioni:

• Crea una sottoscrizione: pubsub.subscriptions.create
• Elimina una sottoscrizione: pubsub.subscriptions.delete
• Acquista un abbonamento: pubsub.subscriptions.get
• Inserisci una sottoscrizione: pubsub.subscriptions.list
• Aggiorna un abbonamento: pubsub.subscriptions.update
• Collega 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 riuscire a ottenere queste autorizzazioni con i ruoli personalizzati o altri ruoli predefiniti.

Se devi creare sottoscrizioni push in un progetto associate 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à delle sottoscrizioni push

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

Proprietà comuni

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

Endpoint

URL endpoint (obbligatorio). Un indirizzo HTTPS pubblicamente accessibile. Il server per l'endpoint push deve avere un certificato SSL valido firmato da un'autorità di certificazione. Il servizio Pub/Sub recapita i messaggi agli endpoint di push dalla stessa regione Google Cloud in cui il servizio Pub/Sub archivia i messaggi. Il servizio Pub/Sub recapita i messaggi dalla stessa regione Google Cloud secondo il criterio del "best effort".

Pub/Sub non richiede più la prova della proprietà per i domini URL con sottoscrizione push. Se il tuo dominio riceve richieste POST impreviste da Pub/Sub, puoi segnalare i sospetti comportamenti illeciti.

Autenticazione

Attiva autenticazione. Se questa opzione è abilitata, i messaggi consegnati da Pub/Sub all'endpoint push includono un'intestazione di autorizzazione per consentire all'endpoint di autenticare la richiesta. Sono disponibili meccanismi automatici di autenticazione e autorizzazione per gli endpoint App Engine Standard e Cloud Functions ospitati nello stesso progetto dell'abbonamento.

La configurazione di autenticazione per un abbonamento push autenticato è composta da un account di servizio gestito dall'utente e i parametri dei segmenti di pubblico specificati in una chiamata create, patch o ModifyPushConfig. Devi inoltre concedere un ruolo specifico a un agente di servizio, come discusso nella prossima sezione.

• Account di servizio gestito dall'utente (obbligatorio). L'account di servizio associato alla sottoscrizione push. Questo account viene utilizzato come attestazione email del token JWT (JSON Web Token) generato. Di seguito è riportato un elenco dei requisiti per l'account di servizio:

  • Questo account di servizio deve trovarsi nello stesso progetto della sottoscrizione push.

  • L'entità che crea o modifica la sottoscrizione push deve avere l'autorizzazione iam.serviceAccounts.actAs per l'account di servizio. Puoi concedere un ruolo con questa autorizzazione nel progetto, nella cartella o nell'organizzazione per consentire al chiamante di impersonare più account di servizio oppure concedere un ruolo con questa autorizzazione nell'account di servizio per consentire al chiamante di impersonare solo questo account di servizio.

• Pubblico. Una singola stringa, senza distinzione tra maiuscole e minuscole, utilizzata dal webhook per convalidare il pubblico previsto per questo particolare token.

• Agente di servizio (obbligatorio).

  • Pub/Sub crea automaticamente un account di servizio con il formato service-{PROJECT_NUMBER}@gcp-sa-pubsub.iam.gserviceaccount.com.

  • A questo agente di servizio deve essere concessa l'autorizzazione iam.serviceAccounts.getOpenIdToken (inclusa nel ruolo di roles/iam.serviceAccountTokenCreator) per consentire a Pub/Sub di creare token JWT per le richieste push autenticate.

Annullamento del wrapping del payload

L'opzione Abilita l'annullamento del wrapping del payload rimuove i messaggi Pub/Sub di tutti i metadati dei messaggi, ad eccezione dei dati dei messaggi. Con l'annullamento del wrapping del payload, i dati dei messaggi vengono consegnati direttamente come il corpo HTTP.

• Scrivi metadati. Aggiunge di nuovo i metadati del messaggio rimossi in precedenza nell'intestazione della richiesta.

Controlli di servizio VPC

Per un progetto protetto da Controlli di servizio VPC, tieni presente le seguenti limitazioni per le sottoscrizioni push:

• Puoi creare solo nuove sottoscrizioni push per le quali l'endpoint push è impostato su un servizio Cloud Run con un URL run.app predefinito o un'esecuzione di Workflows. I domini personalizzati non funzionano.

• Quando si instradano eventi tramite Eventarc a destinazioni Workflows per cui l'endpoint push è impostato su un'esecuzione di Workflows, è possibile creare nuove sottoscrizioni push solo tramite Eventarc.

• Non puoi aggiornare le sottoscrizioni push esistenti. Queste sottoscrizioni push continuano a funzionare, anche se non sono protette dai Controlli di servizio VPC.

Creare una sottoscrizione push

Gli esempi riportati di seguito mostrano come creare una sottoscrizione con consegna push, utilizzando le impostazioni predefinite fornite.

Per impostazione predefinita, le sottoscrizioni utilizzano la consegna pull, a meno che non imposti esplicitamente una configurazione push, come mostrato negli esempi seguenti.

Console

Per creare una sottoscrizione push, completa i seguenti passaggi:

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

   Vai ad Abbonamenti

2. Fai clic su Crea sottoscrizione.
3. Inserisci un nome nel campo Subscription ID (ID abbonamento).

   Per informazioni su come assegnare un nome a una sottoscrizione, vedi 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. Seleziona Push come Tipo di pubblicazione.
6. Specifica l'URL di un endpoint.
7. Conserva tutti gli altri valori predefiniti.
8. Fai clic su Crea.

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

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

   Vai ad Argomenti

2. Fai clic su accanto all'argomento per il quale 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, vedi Linee guida per assegnare un nome a un argomento o a una sottoscrizione.

5. Seleziona Push come Tipo di pubblicazione.
6. Specifica l'URL di un endpoint.
7. Conserva tutti gli altri valori predefiniti.
8. 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 push, esegui il comando gcloud pubsub subscriptions create.

   gcloud pubsub subscriptions create SUBSCRIPTION_ID \
       --topic=TOPIC_ID \
       --push-endpoint=PUSH_ENDPOINT

   Sostituisci quanto segue:

   • SUBSCRIPTION_ID: nome o ID della nuova sottoscrizione push.
   • TOPIC_ID: il nome o l'ID dell'argomento.
   • PUSH_ENDPOINT: l'URL da utilizzare come endpoint per questo abbonamento. Ad esempio, https://myproject.appspot.com/myhandler.

REST

Per creare una sottoscrizione push, 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",
  // Only needed if you are using push delivery
  "pushConfig": {
    "pushEndpoint": "PUSH_ENDPOINT"
  }
}

Dove:

PROJECT_ID è l'ID progetto.

SUBSCRIPTION_ID è l'ID abbonamento.

TOPIC_ID è il tuo ID argomento.

PUSH_ENDPOINT è un URL da utilizzare come endpoint. Ad esempio, https://myproject.appspot.com/myhandler.

Risposta:

{
  "name": "projects/PROJECT_ID/subscriptions/SUBSCRIPTION_ID",
  "topic": "projects/PROJECT_ID/topics/TOPIC_ID",
  "pushConfig": {
    "pushEndpoint": "https://PROJECT_ID.appspot.com/myhandler",
    "attributes": {
      "x-goog-version": "v1"
    }
  },
  "ackDeadlineSeconds": 10,
  "messageRetentionDuration": "604800s",
  "expirationPolicy": {
    "ttl": "2678400s"
  }
}

C++

Prima di provare questo esempio, segui le istruzioni per la configurazione di C++ nella Guida rapida: utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Pub/Sub C++.

namespace pubsub = ::google::cloud::pubsub;
namespace pubsub_admin = ::google::cloud::pubsub_admin;
[](pubsub_admin::SubscriptionAdminClient client,
   std::string const& project_id, std::string const& topic_id,
   std::string const& subscription_id, std::string const& endpoint) {
  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());
  request.mutable_push_config()->set_push_endpoint(endpoint);
  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 per la 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# Pub/Sub.

Per eseguire l'autenticazione su Pub/Sub, configura le Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per le librerie client.

using Google.Cloud.PubSub.V1;

public class CreatePushSubscriptionSample
{
    public Subscription CreatePushSubscription(string projectId, string topicId, string subscriptionId, string pushEndpoint)
    {
        SubscriberServiceApiClient subscriber = SubscriberServiceApiClient.Create();
        TopicName topicName = TopicName.FromProjectTopic(projectId, topicId);
        SubscriptionName subscriptionName = SubscriptionName.FromProjectSubscription(projectId, subscriptionId);

        PushConfig pushConfig = new PushConfig { PushEndpoint = pushEndpoint };

        // The approximate amount of time in seconds (on a best-effort basis) Pub/Sub waits for the
        // subscriber to acknowledge receipt before resending the message.
        var ackDeadlineSeconds = 60;
        var subscription = subscriber.CreateSubscription(subscriptionName, topicName, pushConfig, ackDeadlineSeconds);
        return subscription;
    }
}

Go

Prima di provare questo esempio, segui le istruzioni per la 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 Pub/Sub.

Per eseguire l'autenticazione su 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 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: %w", err)
	}
	defer client.Close()

	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: %w", err)
	}
	fmt.Fprintf(w, "Created push subscription: %v\n", sub)
	return nil
}

Java

Prima di provare questo esempio, segui le istruzioni per la 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 Pub/Sub.

Per eseguire l'autenticazione su 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 CreatePushSubscriptionExample {
  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";
    String pushEndpoint = "https://my-test-project.appspot.com/push";

    createPushSubscriptionExample(projectId, subscriptionId, topicId, pushEndpoint);
  }

  public static void createPushSubscriptionExample(
      String projectId, String subscriptionId, String topicId, String pushEndpoint)
      throws IOException {
    try (SubscriptionAdminClient subscriptionAdminClient = SubscriptionAdminClient.create()) {
      TopicName topicName = TopicName.of(projectId, topicId);
      SubscriptionName subscriptionName = SubscriptionName.of(projectId, subscriptionId);
      PushConfig pushConfig = PushConfig.newBuilder().setPushEndpoint(pushEndpoint).build();

      // Create a push 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, 10);
      System.out.println("Created push subscription: " + subscription.getName());
    }
  }
}

Node.js

/**
 * TODO(developer): Uncomment these variables before running the sample.
 */
// const pushEndpoint = 'YOUR_ENDPOINT_URL';
// 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 createPushSubscription(
  pushEndpoint,
  topicNameOrId,
  subscriptionNameOrId
) {
  const options = {
    pushConfig: {
      // Set to an HTTPS endpoint of your choice. If necessary, register
      // (authorize) the domain on which the server is hosted.
      pushEndpoint,
    },
  };

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

Node.js

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

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

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

async function createPushSubscription(
  pushEndpoint: string,
  topicNameOrId: string,
  subscriptionNameOrId: string
) {
  const options: CreateSubscriptionOptions = {
    pushConfig: {
      // Set to an HTTPS endpoint of your choice. If necessary, register
      // (authorize) the domain on which the server is hosted.
      pushEndpoint,
    },
  };

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

PHP

Prima di provare questo esempio, segui le istruzioni per la 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 Pub/Sub.

Per eseguire l'autenticazione su 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 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

Prima di provare questo esempio, segui le istruzioni per la 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 Pub/Sub.

Per eseguire l'autenticazione su 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"
# endpoint = "https://my-test-project.appspot.com/push"

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)

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

# 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,
            "push_config": push_config,
        }
    )

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

Ruby

Prima di provare questo esempio, segui le istruzioni per la 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 Pub/Sub.

Per eseguire l'autenticazione su 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"
# endpoint          = "https://your-test-project.appspot.com/push"

pubsub = Google::Cloud::Pubsub.new

topic        = pubsub.topic topic_id
subscription = topic.subscribe subscription_id,
                               endpoint: endpoint

puts "Push subscription #{subscription_id} created."

Passaggi successivi

• Crea o modifica una sottoscrizione con i comandi gcloud.
• Crea o modifica un abbonamento con le API REST.