Google utilizza la tecnologia AI per tradurre i contenuti nella tua lingua preferita. Le traduzioni generate dall'AI potrebbero contenere errori.

Creare sottoscrizioni push

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

Prima di iniziare

Scopri di più sulle sottoscrizioni.
Scopri come funzionano le sottoscrizioni push.

Ruoli e autorizzazioni richiesti

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

Questo ruolo predefinito contiene le autorizzazioni necessarie per creare una sottoscrizione push. Per vedere quali sono esattamente le autorizzazioni richieste, espandi la sezione Autorizzazioni obbligatorie:

Autorizzazioni obbligatorie

Per creare una sottoscrizione push sono necessarie le seguenti autorizzazioni:

pubsub.subscriptions.create sul progetto
pubsub.topics.attachSubscription sull'argomento

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

Sottoscrizioni tra progetti

Se crei una sottoscrizione in un progetto per un argomento in un altro progetto, devi disporre dell'autorizzazione pubsub.subscriptions.create nel progetto in cui stai creando la sottoscrizione e dell'autorizzazione pubsub.topics.attachSubscription nell'argomento.

Proprietà della sottoscrizione push

Le sottoscrizioni push supportano tutte le proprietà comuni delle sottoscrizioni. Le sezioni seguenti descrivono le proprietà specifiche delle sottoscrizioni push.

Endpoint

URL dell'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 da la stessa Google Cloud regione in cui il servizio Pub/Sub archivia i messaggi. Il servizio Pub/Sub invia i messaggi dalla stessa Google Cloud regione con il massimo impegno.

Se gli abbonati utilizzano un firewall, non possono ricevere richieste push. Per ricevere richieste push, devi disattivare il firewall e verificare il token JWT (JSON Web Token) utilizzato nella richiesta. Se un abbonato ha un firewall, potresti ricevere un errore 403 permission denied.
Pub/Sub non richiede 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 sospetto abuso.

Autenticazione

Abilita l'autenticazione. Se questa opzione è abilitata, i messaggi inviati da Pub/Sub all'endpoint push includono un'intestazione di autorizzazione per consentire all'endpoint di autenticare la richiesta. Sono disponibili meccanismi di autenticazione e autorizzazione automatici per gli endpoint di App Engine standard e Cloud Run Functions ospitati nello stesso progetto della sottoscrizione.

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 che sono specificati in una chiamata create, patch o ModifyPushConfig. Devi anche concedere un ruolo specifico a un account di servizio, come descritto nella sezione successiva.

Segmento di pubblico. Una singola stringa senza distinzione tra maiuscole e minuscole che il webhook utilizza per convalidare il segmento di pubblico previsto di questo token specifico.
Service account. Pub/Sub crea automaticamente un account di servizio per te con il formato service-{PROJECT_NUMBER}@gcp-sa-pubsub.iam.gserviceaccount.com.

Prerequisiti per l'abilitazione dell'autenticazione

Il service account gestito dall'utente è il 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 il account di servizio:

Questo service account gestito dall'utente deve trovarsi nello stesso progetto della sottoscrizione push.
L'entità che crea o modifica la sottoscrizione push deve disporre dell'autorizzazione iam.serviceAccounts.actAs sul service account gestito dall'utente per collegare il account di servizio alla sottoscrizione push. Per saperne di più, consulta Collegare service account alle risorse.
Autorizzazioni obbligatorie: a questo account di servizio deve essere concessa l' iam.serviceAccounts.getOpenIdToken autorizzazione (inclusa nel roles/iam.serviceAccountTokenCreatorruolo) per consentire a Pub/Sub di creare token JWT per il account di servizio specificato per autenticare le richieste push.

Annullamento del wrapping del payload

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

Puoi anche abilitare l'opzione Scrivi metadati. L'opzione Scrivi metadati aggiunge nuovamente i metadati dei messaggi rimossi in precedenza nell'intestazione della richiesta.

Inviare a indirizzi VPC privati

Pub/Sub opera al di fuori delle reti VPC e non può inviare direttamente messaggi a indirizzi VPC privati. Tuttavia, puoi utilizzare Eventarc per instradare i messaggi ai servizi all'interno del tuo VPC. Pub/Sub può inviare messaggi a un trigger Eventarc, che può quindi inoltrarli a un servizio all'interno del tuo VPC, ad esempio un servizio Cloud Run o un'esecuzione di Workflows. Per saperne di più, consulta la documentazione di Eventarc.

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 su un'esecuzione di Workflows. I domini personalizzati non funzionano.
Quando instradi gli eventi tramite Eventarc verso le destinazioni di Workflows per le quali l'endpoint push è impostato su un'esecuzione di Workflows, puoi 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 da Controlli di servizio VPC.

Creare una sottoscrizione push

Gli esempi seguenti mostrano come creare una sottoscrizione con pubblicazione push utilizzando le impostazioni predefinite fornite.

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

Console

Per creare una sottoscrizione push:

Nella Google Cloud console, vai alla pagina Sottoscrizioni.
Vai ad Abbonamenti
Fai clic su Crea sottoscrizione.
Nel campo ID sottoscrizione, inserisci un nome.
Per informazioni su come denominare una sottoscrizione, consulta Linee guida per la denominazione di un argomento o di una sottoscrizione.
Scegli o crea un argomento dal menu a discesa. La sottoscrizione riceve i messaggi dall'argomento.
Seleziona Push come Tipo di pubblicazione.
Specifica un URL dell'endpoint.
Mantieni tutti gli altri valori predefiniti.
Fai clic su Crea.

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

Nella Google Cloud console, vai alla pagina Argomenti.
Vai agli argomenti
Fai clic su accanto all'argomento su cui creare una sottoscrizione.
Dal menu contestuale, seleziona Crea sottoscrizione.
Inserisci l'ID sottoscrizione.
Per informazioni su come denominare una sottoscrizione, consulta Linee guida per la denominazione di un argomento o di una sottoscrizione.
Seleziona Push come Tipo di pubblicazione.
Specifica un URL dell'endpoint.
Mantieni tutti gli altri valori predefiniti.
Fai clic su Crea.

gcloud

Nella Google Cloud console, attiva Cloud Shell.

Attiva Cloud Shell

Nella parte inferiore della Google Cloud console viene avviata una sessione di Cloud Shell e viene visualizzato un prompt della riga di comando. Cloud Shell è un ambiente shell con Google Cloud CLI già inclusa e installata e con valori già impostati per il progetto corrente. L'inizializzazione della sessione può richiedere alcuni secondi.
Per creare una sottoscrizione push, esegui il gcloud pubsub subscriptions create comando.
```
gcloud pubsub subscriptions create SUBSCRIPTION_ID \
--topic=TOPIC_ID \
--push-endpoint=PUSH_ENDPOINT
```
Sostituisci quanto segue:
- SUBSCRIPTION_ID: il nome o l'ID della nuova sottoscrizione push.
- TOPIC_ID: il nome o l'ID dell'argomento.
- PUSH_ENDPOINT: l'URL da utilizzare come endpoint per questa sottoscrizione. Ad esempio, https://myproject.appspot.com/myhandler.

REST

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

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 sottoscrizione.

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 di C++ in Guida rapida all'utilizzo delle librerie client. Per saperne di più, 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# in Guida rapida all'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Pub/Sub C# .


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;
    }
}

Vai

L'esempio seguente utilizza la versione principale della libreria client Go Pub/Sub (v2). Se utilizzi ancora la libreria v1, consulta la guida alla migrazione alla v2. Per visualizzare un elenco di esempi di codice della versione 1, consulta gli esempi di codice deprecati.

Prima di provare questo esempio, segui le istruzioni di configurazione di Go in Guida rapida all'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Pub/Sub Go.

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/pubsub/v2"
	"cloud.google.com/go/pubsub/v2/apiv1/pubsubpb"
)

func createWithEndpoint(w io.Writer, projectID, topic, subscription, endpoint string) error {
	// projectID := "my-project-id"
	// topic := "projects/my-project-id/topics/my-topic"
	// subscription := "projects/my-project/subscriptions/my-sub"
	// 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.SubscriptionAdminClient.CreateSubscription(ctx, &pubsubpb.Subscription{
		Name:               subscription,
		Topic:              topic,
		AckDeadlineSeconds: 10,
		PushConfig:         &pubsubpb.PushConfig{PushEndpoint: endpoint},
	})
	if err != nil {
		return fmt.Errorf("failed to create push sub: %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 in Guida rapida all'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Pub/Sub Java.


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

Prima di provare questo esempio, segui le istruzioni di configurazione di Node.js in guida rapida all'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Pub/Sub 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.ts

/**
 * 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 in guida rapida all'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Pub/Sub PHP.

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 in Guida rapida all'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Pub/Sub Python.

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

L'esempio seguente utilizza la libreria client Ruby Pub/Sub v3. Se utilizzi ancora la libreria v2, consulta la guida alla migrazione alla v3. Per visualizzare un elenco di esempi di codice Ruby v2, consulta gli esempi di codice deprecati.

Prima di provare questo esempio, segui le istruzioni di configurazione di Ruby in Guida rapida all'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Pub/Sub Ruby.

# topic_id          = "your-topic-id"
# subscription_id   = "your-subscription-id"
# endpoint          = "https://your-test-project.appspot.com/push"

pubsub = Google::Cloud::PubSub.new
subscription_admin = pubsub.subscription_admin

subscription = subscription_admin.create_subscription \
  name: pubsub.subscription_path(subscription_id),
  topic: pubsub.topic_path(topic_id),
  push_config: {
    push_endpoint: endpoint
  }

puts "Push subscription #{subscription_id} created."

Monitorare le sottoscrizioni push

Cloud Monitoring fornisce una serie di metriche per monitorare le sottoscrizioni.

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

Puoi anche monitorare le sottoscrizioni da Pub/Sub.

Passaggi successivi

Crea o modifica una sottoscrizione con gcloud comandi.
Crea o modifica una sottoscrizione con le API REST.

Creare sottoscrizioni push Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.