Crea sottoscrizioni push

Questo documento descrive come creare un abbonamento push. Puoi utilizzare lo nella console Google Cloud, in Google Cloud CLI, nella libreria client API Pub/Sub per creare una sottoscrizione push.

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 nel 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 sottoscrizioni push, chiedi all'amministratore di concederti Ruolo IAM dell'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 sottoscrizioni push. Per vedere le autorizzazioni esatte obbligatorie, espandi la sezione Autorizzazioni obbligatorie:

Autorizzazioni obbligatorie

Per creare sottoscrizioni push sono necessarie le seguenti autorizzazioni:

• Creare un abbonamento: pubsub.subscriptions.create
• Eliminare una sottoscrizione: 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 un push sottoscrizioni in un progetto associate a un argomento in un altro chiedi all'amministratore dell'argomento di concederti anche l'editor Pub/Sub (roles/pubsub.editor) nell'argomento.

Proprietà delle sottoscrizioni push

Quando configuri una sottoscrizione push, puoi specificare quanto segue proprietà.

Proprietà comuni

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

Endpoint

URL endpoint (obbligatorio). Un indirizzo HTTPS pubblicamente accessibile. Il server per il 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 recapita i messaggi nella stessa regione Google Cloud secondo il criterio del "best effort".

Pub/Sub non richiede più la prova della proprietà per il push domini URL abbonamento. Se il tuo dominio riceve richieste POST inaspettate 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 inoltre concedere un ruolo specifico a un agente di servizio, come illustrato in nella prossima sezione.

• Account di servizio gestito dall'utente (obbligatorio). L'account di servizio associato al push abbonamento. Questo account viene utilizzato come claim 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 della sottoscrizione 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 distinzione tra maiuscole e minuscole a cui il webhook per convalidare il pubblico previsto di questo particolare token.

• Agente di servizio (obbligatorio).

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

  • A questo agente di servizio deve essere concesso Autorizzazione iam.serviceAccounts.getOpenIdToken (inclusa in roles/iam.serviceAccountTokenCreator ) per consentire a Pub/Sub di creare token JWT per 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 di nuovo i metadati del messaggio rimossi in precedenza nel l'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 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. Queste sottoscrizioni push continuano 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 push usando 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 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 Tipo di pubblicazione come Push.
6. Specifica l'URL di un 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 l'URL di un 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 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",
  // Only needed if you are using push delivery
  "pushConfig": {
    "pushEndpoint": "PUSH_ENDPOINT"
  }
}

Dove:

PROJECT_ID è l'ID progetto.

SUBSCRIPTION_ID è l'ID del tuo 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 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 API Pub/Sub C# documentazione di riferimento.

Per eseguire l'autenticazione su Pub/Sub, configura le credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura 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 nel Guida rapida di Pub/Sub con 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 API Pub/Sub Java documentazione di riferimento.

Per eseguire l'autenticazione su Pub/Sub, configura le credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura 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 API Pub/Sub PHP documentazione di riferimento.

Per autenticarti a Pub/Sub, configura le credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura 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 nel Guida rapida di Pub/Sub con 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 ulteriori informazioni, vedi Configura 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 nel Guida rapida di Pub/Sub con librerie client. Per ulteriori informazioni, consulta API Pub/Sub Ruby documentazione di riferimento.

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

Cloud Monitoring fornisce una serie di metriche monitorare gli abbonamenti.

Per un elenco di tutte le metriche disponibili relative a Pub/Sub e le relative descrizioni, vedi Documentazione sul monitoraggio di Pub/Sub.

Puoi anche monitorare le sottoscrizioni all'interno di Pub/Sub.

Passaggi successivi

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