Creare sottoscrizioni push

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

Prima di iniziare

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

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 discusso più avanti in questa sezione.

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

Autorizzazioni obbligatorie

Per creare iscrizioni push sono necessarie le seguenti autorizzazioni:

• 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 push 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 push

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

Proprietà comuni

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

Endpoint

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

Pub/Sub non richiede più una prova della proprietà per i domini URL con sottoscrizione push. Se il tuo dominio riceve richieste POST impreviste da Pub/Sub, puoi segnalare un presunto abuso.

Autenticazione

Attiva l'autenticazione. Se questa opzione è attivata, i messaggi inviati da Pub/Sub all'endpoint push includono un'intestazione di autorizzazione per consentire all'endpoint di autenticare la richiesta. I meccanismi di autenticazione e autorizzazione automatici sono disponibili per gli endpoint delle funzioni App Engine Standard e Cloud Run ospitati nello stesso progetto dell'abbonamento.

La configurazione dell'autenticazione per una sottoscrizione push autenticata è costituita da un account di servizio gestito dall'utente e dai parametri del segmento di pubblico specificati in una chiamata create, patch o ModifyPushConfig. Devi anche concedere un ruolo specifico a un agente di servizio, come discusso nella sezione successiva.

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

  • Questo account di servizio deve trovarsi nello stesso progetto dell'abbonamento push.

  • L'entità che crea o modifica l'iscrizione push deve avere l'autorizzazione iam.serviceAccounts.actAs per l'account di servizio. Puoi concedere un ruolo con questa autorizzazione al progetto, alla cartella o all'organizzazione per consentire all'utente chiamante di rubare l'identità di più account di servizio oppure concedere un ruolo con questa autorizzazione all'account di servizio per consentire all'utente chiamante di rubare l'identità solo di questo account di servizio.

• Pubblico. Una singola stringa senza sensibilità alle maiuscole che il webhook utilizza per convalidare il pubblico previsto di questo token specifico.

• Agente di servizio (obbligatorio).

  • Pub/Sub crea automaticamente un account di servizio per te 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 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 da tutti i messaggi Pub/Sub tutti i metadati, ad eccezione dei dati del messaggio. Con lo scollegamento del payload, i dati del messaggio vengono inviati direttamente come corpo HTTP.

• Scrivi metadati. Aggiunge nuovamente i metadati del messaggio rimossi in precedenza all'intestazione della richiesta.

Controlli di servizio VPC

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

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

• Quando inoltri gli eventi tramite Eventarc alle destinazioni di Workflows per le quali l'endpoint push è impostato su un'esecuzione di Workflows, puoi creare nuovi abbonamenti push solo tramite Eventarc.

• Non puoi aggiornare le iscrizioni push esistenti. Questi abbonamenti push continueranno a funzionare, anche se non sono protetti dai Controlli di servizio VPC.

Creare una sottoscrizione push

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

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

Console

Per creare un abbonamento push:

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 le 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. Seleziona Tipo di pubblicazione come Push.
6. Specifica un URL endpoint.
7. Mantieni invariati tutti gli altri valori predefiniti.
8. 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 le linee guida per assegnare un nome a un argomento o a un abbonamento.

5. Seleziona Tipo di pubblicazione come Push.
6. Specifica un URL endpoint.
7. Mantieni invariati tutti gli altri valori predefiniti.
8. 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 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: il nome o l'ID del nuovo abbonamento 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 è il tuo ID abbonamento.

TOPIC_ID è l'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 di configurazione C++ riportate nella guida rapida all'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 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;

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 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 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 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 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 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 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 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"
# 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 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"
# 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."

Monitorare le iscrizioni push

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

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