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 ruoloroles/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:
- Nella console Google Cloud, vai alla pagina Abbonamenti.
- Fai clic su Crea sottoscrizione.
- 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.
- Scegli o crea un argomento dal menu a discesa. La sottoscrizione riceve i messaggi dall'argomento.
- Seleziona Tipo di pubblicazione come Push.
- Specifica un URL endpoint.
- Mantieni invariati 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 console Google Cloud, vai alla pagina Topic.
- Fai clic su more_vertaccanto all'argomento per cui creare una sottoscrizione.
- Dal menu contestuale, seleziona Crea abbonamento.
- 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.
- Seleziona Tipo di pubblicazione come Push.
- Specifica un URL endpoint.
- Mantieni invariati tutti gli altri valori predefiniti.
- Fai clic su Crea.
gcloud
-
In the Google Cloud console, 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.
-
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:
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++.
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.
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.
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.
Node.js
Node.js
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.
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.
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.
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.