Trigger Pub/Sub

In Cloud Run, puoi attivare i servizi in risposta ai messaggi Pub/Sub utilizzando Eventarc. Quando specifichi un trigger Pub/Sub per il tuo servizio, specifichi anche un argomento Pub/Sub. A seguito di questo attivatore, il servizio viene chiamato ogni volta che pubblichi un messaggio nell'argomento specificato.

Il repository Google Events contiene risorse aggiuntive per lavorare con i dati sugli eventi.

Prima di iniziare

  1. Assicurati di aver configurato un nuovo progetto per Cloud Run come descritto nella pagina di configurazione.

  2. Abilita le API Artifact Registry, Cloud Build, Cloud Run Admin, Eventarc, Cloud Logging e Pub/Sub:

    Abilita le API

Imposta i ruoli obbligatori

  1. Se sei il creator del progetto, ti viene concesso il ruolo di proprietario di base (roles/owner). Per impostazione predefinita, questo ruolo IAM include le autorizzazioni necessarie per l'accesso completo alla maggior parte delle risorse Google Cloud e puoi saltare questo passaggio.

    Se non sei il creator del progetto, le autorizzazioni richieste devono essere concesse al principale appropriato. Ad esempio, un'entità può essere un Account Google (per gli utenti finali) o un account di servizio (per le applicazioni e i carichi di lavoro di calcolo). Per ulteriori informazioni, consulta la pagina Ruoli e autorizzazioni per la destinazione dell'evento.

    Tieni presente che per impostazione predefinita, le autorizzazioni di Cloud Build includono le autorizzazioni per caricare e scaricare gli elementi di Artifact Registry.

    Autorizzazioni obbligatorie

    Per ottenere le autorizzazioni necessarie per configurare gli attivatori Pub/Sub, chiedi all'amministratore di concederti i seguenti ruoli IAM nel progetto:

    Per saperne di più sulla concessione dei ruoli, consulta Gestire l'accesso a progetti, cartelle e organizzazioni.

    Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

  2. Prendi nota dell'account di servizio predefinito di Compute Engine, poiché lo collegherai a un trigger Eventarc per rappresentare l'identità dell'trigger a fini di test. Questo account di servizio viene creato automaticamente dopo aver attivato o utilizzato un servizio Google Cloud che utilizza Compute Engine e con il seguente formato email:

    PROJECT_NUMBER-compute@developer.gserviceaccount.com

    Sostituisci PROJECT_NUMBER con il numero del tuo progetto Google Cloud. Puoi trovare il numero del progetto nella pagina Welcome della console Google Cloud o eseguendo il seguente comando:

    gcloud projects describe PROJECT_ID --format='value(projectNumber)'

    Per gli ambienti di produzione, ti consigliamo vivamente di creare un nuovo account di servizio e di assegnargli uno o più ruoli IAM contenenti le autorizzazioni minime richieste e di seguire il principio del privilegio minimo.

  3. Per impostazione predefinita, i servizi Cloud Run possono essere chiamati solo da proprietari, editor e amministratori e invocatori di progetti Cloud Run. Puoi controllare l'accesso in base al servizio. Tuttavia, per scopi di test, concedi il ruolo invocatore Cloud Run (run.invoker) nel progetto Google Cloud all'account di servizio Compute Engine. In questo modo, il ruolo viene concesso a tutti i servizi e i job Cloud Run di un progetto. 
    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
    --role=roles/run.invoker

    Tieni presente che se crei un trigger per un servizio Cloud Run autenticato senza concedere il ruolo Invoker di Cloud Run, l'trigger viene creato correttamente ed è attivo. Tuttavia, l'attivatore non funzionerà come previsto e nei log verrà visualizzato un messaggio simile al seguente:

    The request was not authenticated. Either allow unauthenticated invocations or set the proper Authorization header.
  4. Concedi il ruolo Riepilogatore eventi Eventarc (roles/eventarc.eventReceiver) sul progetto all'account di servizio predefinito di Compute Engine in modo che l'attivatore Eventarc possa ricevere eventi dai fornitori di eventi. 
    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
    --role=roles/eventarc.eventReceiver
  5. Se hai attivato l'agente di servizio Cloud Pub/Sub il giorno 8 aprile 2021 o in una data precedente per supportare le richieste push Pub/Sub autenticate, concedi all'agente di servizio il ruolo Creatore token account di servizio (roles/iam.serviceAccountTokenCreator). In caso contrario, questo ruolo viene concesso per impostazione predefinita: 
    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com \
    --role=roles/iam.serviceAccountTokenCreator

Creare un attivatore per i servizi

Puoi specificare un trigger dopo aver eseguito il deployment di un servizio.

Fai clic sulla scheda per le istruzioni relative allo strumento che preferisci.

Console

  1. Esegui il deployment del servizio Cloud Run utilizzando container o da sorgente.

  2. Nella console Google Cloud, vai a Cloud Run:

    Vai a Cloud Run

  3. Nell'elenco dei servizi, fai clic su un servizio esistente.

  4. Nella pagina Dettagli servizio, vai alla scheda Trigger.

  5. Fai clic su Aggiungi trigger e seleziona Trigger Pub/Sub.

  6. Nel riquadro Trigger Eventarc, modifica i dettagli dell'attivatore come segue:

    1. Nel campo Nome attivatore, inserisci un nome per l'attivatore o utilizza il nome predefinito.

    2. Seleziona un Tipo di attivatore dall'elenco per specificare uno dei seguenti tipi di attivatore:

      • Origini Google per specificare gli trigger per Pub/Sub, Cloud Storage, Firestore e altri fornitori di eventi Google.

      • Di terze parti per l'integrazione con fornitori non Google che offrono un'origine Eventarc. Per ulteriori informazioni, consulta Eventi di terze parti in Eventarc.

    3. Seleziona Pub/Sub dall'elenco Provider di eventi per selezionare un prodotto che fornisca il tipo di evento per attivare il servizio. Per l'elenco dei fornitori di eventi, consulta Fornitori e destinazioni di eventi.

    4. Seleziona google.cloud.pubsub.topic.v1.messagePublished dall'elenco Tipo di evento. La configurazione dell'attivatore varia a seconda del tipo di evento supportato. Per saperne di più, consulta Tipi di eventi.

    5. Nel campo Seleziona un argomento Cloud Pub/Sub, scegli un argomento da monitorare per l'attivatore. I messaggi pubblicati in questo argomento attivano le chiamate alla funzione.

    6. Se il campo Regione è attivato, seleziona una località per l'attivatore Eventarc. In generale, la posizione di un trigger Eventarc deve corrispondere alla posizione della risorsa Google Cloud per la quale vuoi monitorare gli eventi. Nella maggior parte dei casi, devi anche eseguire il deployment del servizio nella stessa regione. Consulta la sezione Informazioni sulle località Eventarc per ulteriori dettagli sulle località dei trigger Eventarc.

    7. Nel campo Account di servizio, seleziona un account di servizio. Gli attivatori Eventarc sono collegati agli account di servizio da usare come identità quando viene invocato il servizio. L'account di servizio dell'attivatore Eventarc deve disporre dell'autorizzazione per richiamare il servizio. Per impostazione predefinita, Cloud Run utilizza l'account di servizio predefinito di Compute Engine.

    8. Se vuoi, specifica il percorso dell'URL del servizio a cui inviare la richiesta in arrivo. Si tratta del percorso relativo nel servizio di destinazione a cui devono essere inviati gli eventi per l'attivatore. Ad esempio: /, /route, route e route/subroute.

    9. Dopo aver compilato i campi obbligatori, fai clic su Salva trigger.

  7. Dopo aver creato l'attivatore, verificane l'integrità assicurandoti che sia presente un segno di spunta nella scheda Attivatori.

gcloud

  1. Esegui il deployment del servizio Cloud Run utilizzando container o da sorgente.

  2. Esegui il comando seguente per creare un attivatore che filtra gli eventi:

    gcloud eventarc triggers create TRIGGER_NAME  \
    --location=EVENTARC_TRIGGER_LOCATION \
    --destination-run-service=SERVICE  \
    --destination-run-region=REGION \
    --event-filters="type=google.cloud.pubsub.topic.v1.messagePublished" \
    --transport-topic=projects/PROJECT_ID/topics/TOPIC_ID \
    --service-account=PROJECT_NUMBER-compute@developer.gserviceaccount.com

    Sostituisci:

    • TRIGGER_NAME con il nome dell'attivatore.

    • EVENTARC_TRIGGER_LOCATION con la posizione per l'trigger Eventarc. In generale, la posizione di un trigger Eventarc deve corrispondere alla posizione della risorsa Google Cloud che vuoi monitorare per rilevare gli eventi. Nella maggior parte dei casi, devi anche eseguire il deployment del servizio nella stessa regione. Per ulteriori informazioni, consulta Località Eventarc.

    • SERVICE con il nome del servizio che stai implementando.

    • REGION con la regione Cloud Run del servizio.

    • PROJECT_NUMBER con il numero del tuo progetto Google Cloud. Gli attivatori Eventarc sono collegati agli account di servizio da utilizzare come identità quando viene invocato il servizio. L'account di servizio dell'attivatore Eventarc deve disporre dell'autorizzazione per richiamare il servizio. Per impostazione predefinita, Cloud Run utilizza l'account di servizio Compute predefinito.

    • Il flag event-filters specifica i filtri eventi monitorati dall'attivatore. Un evento che corrisponde a tutti i filtri event-filters attiva le chiamate al tuo servizio. Ogni attivatore deve avere un tipo di evento supportato. Non puoi modificare il tipo di filtro evento dopo la creazione. Per modificare il tipo di filtro eventi, devi creare un nuovo attivatore ed eliminare quello precedente. Se vuoi, puoi ripetere il flag --event-filters con un filtro supportato nel modulo ATTRIBUTE=VALUE per aggiungere altri filtri.

Creare un trigger per le funzioni

Fai clic sulla scheda per le istruzioni relative allo strumento che preferisci.

Console

Quando utilizzi la console Google Cloud per creare una funzione, puoi anche aggiungere un trigger. Per creare un attivatore per la funzione:

  1. Nella console Google Cloud, vai a Cloud Run:

    Vai a Cloud Run

  2. Fai clic su Scrivi una funzione e inserisci i dettagli della funzione. Per ulteriori informazioni sulla configurazione delle funzioni durante il deployment, consulta Eseguire il deployment delle funzioni.

  3. Nella sezione Attivazione, fai clic su Aggiungi attivatore.

  4. Seleziona Trigger Pub/Sub.

  5. Nel riquadro Trigger Eventarc, modifica i dettagli dell'attivatore come segue:

    1. Inserisci un nome per l'attivatore nel campo Nome trigger o utilizza il nome predefinito.

    2. Seleziona un Tipo di attivatore dall'elenco per specificare uno dei seguenti tipi di attivatore:

      • Origini Google per specificare gli trigger per Pub/Sub, Cloud Storage, Firestore e altri fornitori di eventi Google.

      • Di terze parti per l'integrazione con fornitori non Google che offrono un'origine Eventarc. Per ulteriori informazioni, consulta Eventi di terze parti in Eventarc.

    3. Seleziona Pub/Sub dall'elenco Fornitore di eventi per selezionare un prodotto che fornisca il tipo di evento per attivare la funzione. Per l'elenco dei fornitori di eventi, consulta Fornitori e destinazioni di eventi.

    4. Seleziona google.cloud.pubsub.topic.v1.messagePublished dall'elenco Tipo di evento. La configurazione dell'attivatore varia a seconda del tipo di evento supportato. Per saperne di più, consulta Tipi di eventi.

    5. Nel campo Seleziona un argomento Cloud Pub/Sub, scegli un argomento da monitorare per l'attivatore. I messaggi pubblicati in questo argomento attivano le chiamate alla funzione.

    6. Se il campo Regione è attivato, seleziona una località per l'attivatore Eventarc. In generale, la posizione di un trigger Eventarc deve corrispondere alla posizione della risorsa Google Cloud per la quale vuoi monitorare gli eventi. Nella maggior parte degli scenari, devi anche eseguire il deployment della funzione nella stessa regione. Consulta la sezione Informazioni sulle località Eventarc per ulteriori dettagli sulle località dei trigger Eventarc.

    7. Nel campo Account di servizio, seleziona un account di servizio. Gli attivatori Eventarc sono collegati agli account di servizio da usare come identità quando viene invocata la funzione. L'account di servizio dell'attivatore Eventarc deve disporre dell'autorizzazione per richiamare la funzione. Per impostazione predefinita, Cloud Run utilizza l'account di servizio predefinito di Compute Engine.

    8. Se vuoi, specifica il percorso dell'URL del servizio a cui inviare la richiesta in arrivo. Si tratta del percorso relativo nel servizio di destinazione a cui devono essere inviati gli eventi per l'attivatore. Ad esempio: /, /route, route e route/subroute.

  6. Dopo aver compilato i campi obbligatori, fai clic su Salva trigger.

gcloud

Quando crei una funzione utilizzando gcloud CLI, devi prima deploy e poi creare un attivatore. Per creare un attivatore per la funzione:

  1. Esegui il seguente comando nella directory contenente il codice campione per eseguire il deployment della funzione:

    gcloud beta run deploy FUNCTION \
        --source . \
        --function FUNCTION_ENTRYPOINT \
        --base-image BASE_IMAGE_ID \
        --region REGION

    Sostituisci:

    • FUNCTION con il nome della funzione di cui stai eseguendo il deployment. Puoi omettere del tutto questo parametro, ma se lo fai ti verrà chiesto il nome.

    • FUNCTION_ENTRYPOINT con il punto di ingresso della funzione nel codice sorgente. Questo è il codice che Cloud Run esegue quando viene eseguita la funzione. Il valore di questo flag deve essere un nome di funzione o un nome di classe completamente qualificato esistente nel codice sorgente.

    • BASE_IMAGE_ID con l'ambiente dell'immagine di base per la funzione. Per ulteriori dettagli sulle immagini di base e sui pacchetti inclusi in ogni immagine, consulta Immagini di base dei runtime.

    • REGION con la regione Google Cloud in cui vuoi eseguire il deployment della funzione. Ad esempio: us-central1.

  2. Esegui il comando seguente per creare un attivatore che filtra gli eventi:

    gcloud eventarc triggers create TRIGGER_NAME  \
    --location=EVENTARC_TRIGGER_LOCATION \
    --destination-run-service=FUNCTION  \
    --destination-run-region=REGION \
    --event-filters="type=google.cloud.pubsub.topic.v1.messagePublished" \
    --transport-topic=projects/PROJECT_ID/topics/TOPIC_ID \
    --service-account=PROJECT_NUMBER-compute@developer.gserviceaccount.com

    Sostituisci:

    • TRIGGER_NAME con il nome dell'attivatore.

    • EVENTARC_TRIGGER_LOCATION con la posizione per l'trigger Eventarc. In generale, la posizione di un trigger Eventarc deve corrispondere alla posizione della risorsa Google Cloud che vuoi monitorare per rilevare gli eventi. Nella maggior parte dei casi, devi anche eseguire il deployment della funzione nella stessa regione. Per ulteriori informazioni, consulta Località Eventarc.

    • FUNCTION con il nome della funzione di cui stai eseguendo il deployment.

    • REGION con la regione Cloud Run della funzione.

    • PROJECT_NUMBER con il numero del tuo progetto Google Cloud. Gli attivatori Eventarc sono collegati agli account di servizio da utilizzare come identità quando viene invocata la funzione. L'account di servizio dell'attivatore Eventarc deve disporre dell'autorizzazione per richiamare la funzione. Per impostazione predefinita, Cloud Run utilizza l'account di servizio Compute predefinito.

    • Il flag event-filters specifica i filtri eventi monitorati dall'attivatore. Un evento che corrisponde a tutti i filtri event-filters attiva le chiamate alla funzione. Ogni attivatore deve avere un tipo di evento supportato. Non puoi modificare il tipo di filtro evento dopo la creazione. Per modificare il tipo di filtro eventi, devi creare un nuovo attivatore ed eliminare quello precedente. Se vuoi, puoi ripetere il flag --event-filters con un filtro supportato nel modulo ATTRIBUTE=VALUE per aggiungere altri filtri.

Passaggi successivi