Questo documento descrive come creare una sottoscrizione 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 gli abbonamenti push.
Autorizzazioni e ruoli richiesti
Per creare un abbonamento, devi configurare il controllo dell'accesso a livello di progetto. Devi disporre delle autorizzazioni a livello di risorsa anche se le sottoscrizioni e gli argomenti si trovano in progetti diversi, come illustrato 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 le autorizzazioni esatte necessarie, espandi la sezione Autorizzazioni richieste:
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
-
Elenca un abbonamento:
pubsub.subscriptions.list
-
Aggiorna un abbonamento:
pubsub.subscriptions.update
-
Allega 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 essere in grado di ottenere queste autorizzazioni con i ruoli personalizzati o altri ruoli predefiniti.
Se devi creare sottoscrizioni push in un progetto associato 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 di più sulle proprietà di abbonamento comuni che puoi impostare per tutte le sottoscrizioni.
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 consegna i messaggi per il push degli endpoint 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 di proprietà per i domini dell'URL dell'abbonamento push. Se il tuo dominio riceve richieste POST impreviste da Pub/Sub, puoi segnalare un abuso sospetto.
Autenticazione
Attiva l'autenticazione. Quando l'opzione è abilitata, i messaggi recapitati 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 automatica sono disponibili per gli endpoint App Engine Standard e Cloud Functions ospitati nello stesso progetto dell'abbonamento.
La configurazione dell'autenticazione per una sottoscrizione push autenticata è composta da un account di servizio gestito dall'utente e dai parametri di pubblico specificati in una chiamata create, patch o ModifyPushConfig. Devi inoltre concedere un ruolo specifico a un agente di servizio, come illustrato nella sezione successiva.
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 di 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
nell'account di servizio. Puoi concedere un ruolo con questa autorizzazione al progetto, alla cartella o all'organizzazione per permettere 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 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 i messaggi Pub/Sub di tutti i metadati dei messaggi, ad eccezione di quelli dei messaggi. Con l'annullamento del wrapping del payload, i dati dei messaggi vengono recapitati direttamente come corpo HTTP.
- Scrivi metadati. Aggiunge nuovamente i metadati dei messaggi rimossi in precedenza nell'intestazione della richiesta.
Controlli di servizio VPC
Per un progetto protetto dai Controlli di servizio VPC, tieni presente le seguenti limitazioni per le sottoscrizioni push:
Puoi creare nuove sottoscrizioni push solo 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 esegui il routing degli eventi tramite Eventarc alle destinazioni Workflows per cui l'endpoint push è impostato su un'esecuzione di Workflows, puoi creare nuove sottoscrizioni push solo tramite Eventarc.
Non puoi aggiornare le sottoscrizioni push esistenti. Questi abbonamenti 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 un abbonamento con pubblicazione push, utilizzando le impostazioni predefinite fornite.
Per impostazione predefinita, le sottoscrizioni utilizzano la consegna, a meno che non imposti esplicitamente una configurazione push, come mostrato negli esempi seguenti.
Console
Per creare una sottoscrizione push, completa i seguenti passaggi:
- Nella console Google Cloud, vai alla pagina Abbonamenti.
- Fai clic su Crea sottoscrizione.
- Inserisci un nome nel campo ID abbonamento.
Per informazioni su come assegnare un nome a una sottoscrizione, consulta le Linee guida per il nome di un argomento o di una sottoscrizione.
- Scegli o crea un argomento dal menu a discesa. La sottoscrizione riceve i messaggi dall'argomento.
- Per Tipo di pubblicazione, seleziona Push.
- Specifica un URL dell'endpoint.
- Mantieni tutti gli altri valori predefiniti.
- Fai clic su Crea.
Puoi creare un abbonamento anche dalla sezione Argomenti. Questa scorciatoia è utile per associare gli argomenti agli abbonamenti.
- Nella console Google Cloud, vai alla pagina Argomenti.
- Fai clic su more_vert accanto all'argomento per il quale creare una sottoscrizione.
- Dal menu contestuale, seleziona Crea abbonamento.
- Inserisci l'ID abbonamento.
Per informazioni su come assegnare un nome a una sottoscrizione, consulta le Linee guida per il nome di un argomento o di una sottoscrizione.
- Per Tipo di pubblicazione, seleziona Push.
- Specifica un URL dell'endpoint.
- Mantieni tutti gli altri valori predefiniti.
- Fai clic su Crea.
gcloud
-
Nella console Google Cloud, 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.
-
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 tuo 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 di C++ riportate nella Guida rapida sull'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API C++ Pub/Sub.
C#
Prima di provare questo esempio, segui le istruzioni di 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# di Pub/Sub.
Per eseguire l'autenticazione in Pub/Sub, configura le Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per le librerie client.
Go
Prima di provare questo esempio, segui le istruzioni di 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 di Pub/Sub.
Per eseguire l'autenticazione in Pub/Sub, configura le Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per le librerie client.
Java
Prima di provare questo esempio, segui le istruzioni di 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 di Pub/Sub.
Per eseguire l'autenticazione in Pub/Sub, configura le Credenziali predefinite dell'applicazione. Per maggiori informazioni, 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 nella guida rapida di Pub/Sub sull'utilizzo delle librerie client. Per maggiori informazioni, consulta la documentazione di riferimento dell'API PHP di Pub/Sub.
Per eseguire l'autenticazione in Pub/Sub, configura le Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per le librerie client.
Python
Prima di provare questo esempio, segui le istruzioni di 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 di Pub/Sub.
Per eseguire l'autenticazione in Pub/Sub, configura le Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per le librerie client.
Ruby
Prima di provare questo esempio, segui le istruzioni di 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 di Pub/Sub.
Per eseguire l'autenticazione in Pub/Sub, configura le Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per le librerie client.
Passaggi successivi
- Crea o modifica una sottoscrizione con i comandi
gcloud
. - Creare o modificare una sottoscrizione con le API REST.