Creare trigger dagli eventi 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. Di conseguenza, il servizio viene chiamato ogni volta che pubblichi un messaggio nell'argomento specificato.

Il repository Google Eventi 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, API Cloud Run Admin, Eventarc, Cloud Logging e API Pub/Sub:

    Abilita le API

Imposta i ruoli obbligatori

Tu o il tuo amministratore dovete concedere all'account del deployer, all'identità del trigger e, facoltativamente, all'agente di servizio Pub/Sub i seguenti ruoli IAM.

Ruoli obbligatori per l'account del deployer

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

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

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

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

Ruoli obbligatori per l'identità del trigger

  1. Prendi nota del service account predefinito di Compute Engine, in quanto lo collegherai a un trigger Eventarc per rappresentare l'identità del trigger a scopo di test. Questo account di servizio viene creato automaticamente dopo aver abilitato o utilizzato un Google Cloud servizio che utilizza Compute Engine e con il seguente formato email:

    PROJECT_NUMBER-compute@developer.gserviceaccount.com

    Sostituisci PROJECT_NUMBER con il Google Cloud numero del tuo progetto. Puoi trovare il numero di progetto nella pagina di benvenuto della Google Cloud console 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 service account e di concedergli uno o più ruoli IAM che contengano le autorizzazioni minime richieste e di seguire il principio del privilegio minimo.

  2. Per impostazione predefinita, i servizi Cloud Run sono richiamabili solo dai proprietari del progetto, dagli editor del progetto e dagli amministratori e dagli invoker di Cloud Run. Puoi controllare l'accesso per ogni servizio; tuttavia, a scopo di test, concedi il ruolo Invoker di Cloud Run (run.invoker) nel Google Cloud progetto al account di servizio Compute Engine. In questo modo, il ruolo viene concesso a tutti i servizi e i job Cloud Run in 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, il trigger viene creato correttamente ed è attivo. Tuttavia, il trigger 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.
  3. Concedi il ruolo Eventarc Event Receiver (roles/eventarc.eventReceiver) nel progetto al account di servizio predefinito di Compute Engine in modo che il trigger Eventarc possa ricevere eventi dai provider di eventi. 
    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
    --role=roles/eventarc.eventReceiver

Ruolo facoltativo per l'agente di servizio Pub/Sub

  • 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 il ruolo Service Account Token Creator (roles/iam.serviceAccountTokenCreator) all'agente di servizio. 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

Crea un trigger 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 i container o dal codice sorgente.

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

    Vai a Cloud Run

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

  4. Nella pagina dei dettagli del servizio, vai alla scheda Trigger.

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

  6. Nel riquadro Trigger Eventarc, modifica i dettagli del trigger come segue:

    1. Nel campo Nome trigger , inserisci un nome per il trigger o utilizza il nome predefinito.

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

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

      • Terze parti per l'integrazione con provider non Google che offrono un'origine Eventarc. Per saperne di più, vedi Eventi di terze parti in Eventarc.

    3. Seleziona Pub/Sub dall'elenco Provider di eventi per selezionare un prodotto che fornisce il tipo di evento per l'attivazione del servizio. Per l'elenco dei provider di eventi, vedi Provider e destinazioni di eventi.

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

    5. Nel campo dell'argomento Seleziona un argomento Cloud Pub/Sub, scegli un argomento che il trigger deve monitorare. I messaggi che pubblichi in questo argomento attivano chiamate alla tua funzione.

    6. Se il campo Regione è abilitato, seleziona una località per il trigger Eventarc. In generale, la località di un trigger Eventarc deve corrispondere alla località della Google Cloud risorsa che vuoi monitorare per gli eventi. Nella maggior parte degli scenari, devi anche eseguire il deployment del servizio nella stessa regione. Per maggiori dettagli sulle località dei trigger Eventarc, vedi Informazioni sulle località Eventarc.

    7. Nel campo Service account, seleziona un account di servizio. I trigger Eventarc sono collegati ai service account da utilizzare come identità quando richiami il servizio. Il account di servizio del trigger Eventarc deve disporre dell'autorizzazione per richiamare il servizio. Per impostazione predefinita, Cloud Run utilizza il service account predefinito di Compute Engine.

    8. Se vuoi, specifica il percorso dell'URL del servizio a cui inviare la richiesta in entrata. Questo è il percorso relativo del servizio di destinazione a cui devono essere inviati gli eventi per il trigger. Ad esempio: /, /route, route e route/subroute.

    9. Una volta compilati i campi obbligatori, fai clic su Salva trigger.

  7. Dopo aver creato il trigger, verifica il suo stato assicurandoti che sia presente un segno di spunta nella scheda Trigger.

gcloud

  1. Esegui il deployment del servizio Cloud Run utilizzando i container o dal codice sorgente.

  2. Esegui il comando seguente per creare un trigger che filtri 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 del trigger.

    • EVENTARC_TRIGGER_LOCATION con la località per il trigger Eventarc. In generale, la località di un trigger Eventarc deve corrispondere alla località della Google Cloud risorsa che vuoi monitorare per gli eventi. Nella maggior parte degli scenari, devi anche eseguire il deployment del servizio nella stessa regione. Per saperne di più, vedi Località Eventarc.

    • SERVICE con il nome del servizio di cui stai eseguendo il deployment.

    • REGION con la regione Cloud Run del servizio. Ad esempio, europe-west1.

    • PROJECT_NUMBER con il numero del tuo Google Cloud progetto. I trigger Eventarc sono collegati ai service account da utilizzare come identità quando richiami il servizio. Il account di servizio del trigger Eventarc deve disporre dell'autorizzazione per richiamare il servizio. Per impostazione predefinita, Cloud Run utilizza il account di servizio Compute predefinito.

    Ogni flag event-filters specifica un tipo di evento, con la funzione che si attiva solo quando un evento soddisfa tutti i criteri specificati nei relativi flag event-filters. Ogni trigger deve avere un flag event-filters che specifica un tipo di evento supportato, ad esempio un nuovo documento scritto in Firestore o un file caricato in Cloud Storage. Non puoi modificare il tipo di filtro eventi dopo la creazione. Per modificare il tipo di filtro eventi, devi creare un nuovo trigger ed eliminare quello precedente. Se vuoi, puoi ripetere il flag --event-filters con un filtro supportato nel formato ATTRIBUTE=VALUE per aggiungere altri filtri.

Terraform

Per creare un trigger Eventarc per un servizio Cloud Run, vedi Creare un trigger utilizzando Terraform.

Crea un trigger per le funzioni

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

Console

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

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

    Vai a Cloud Run

  2. Fai clic su Scrivi una funzione e inserisci i dettagli della funzione. Per saperne di più sulla configurazione delle funzioni durante il deployment, vedi Eseguire il deployment delle funzioni.

  3. Nella sezione Trigger, fai clic su Aggiungi trigger.

  4. Seleziona Trigger Pub/Sub.

  5. Nel riquadro Trigger Eventarc, modifica i dettagli del trigger come segue:

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

    2. Seleziona un Tipo di trigger dall'elenco:

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

      • Terze parti per l'integrazione con provider non Google che offrono un'origine Eventarc. Per saperne di più, vedi Eventi di terze parti in Eventarc.

    3. Seleziona Pub/Sub dall'elenco Provider di eventi per selezionare un prodotto che fornisce il tipo di evento per l'attivazione della funzione. Per l'elenco dei provider di eventi, vedi Provider e destinazioni di eventi.

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

    5. Nel campo dell'argomento Seleziona un argomento Cloud Pub/Sub, scegli un argomento che il trigger deve monitorare. I messaggi che pubblichi in questo argomento attivano chiamate alla tua funzione.

    6. Se il campo Regione è abilitato, seleziona una località per il trigger Eventarc. In generale, la località di un trigger Eventarc deve corrispondere alla località della Google Cloud risorsa che vuoi monitorare per gli eventi. Nella maggior parte degli scenari, devi anche eseguire il deployment della funzione nella stessa regione. Per maggiori dettagli sulle località dei trigger Eventarc, vedi Informazioni sulle località Eventarc.

    7. Nel campo Service account, seleziona un account di servizio. I trigger Eventarc sono collegati ai service account da utilizzare come identità quando richiami la funzione. Il account di servizio del trigger Eventarc deve disporre dell'autorizzazione per richiamare la funzione. Per impostazione predefinita, Cloud Run utilizza il service account predefinito di Compute Engine.

    8. Se vuoi, specifica il percorso dell'URL del servizio a cui inviare la richiesta in entrata. Questo è il percorso relativo del servizio di destinazione a cui devono essere inviati gli eventi per il trigger. Ad esempio: /, /route, route e route/subroute.

  6. Una volta compilati i campi obbligatori, fai clic su Salva trigger.

  7. Fai clic su Crea.

  8. Nella scheda Origine , modifica il codice sorgente, se necessario, quindi seleziona Salva ed esegui di nuovo il deployment.

gcloud

Quando crei una funzione utilizzando gcloud CLI, devi prima eseguirne il deployment, quindi creare un trigger. Per creare un trigger per la funzione:

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

    gcloud 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 completamente questo parametro, ma ti verrà chiesto il nome se lo ometti.

    • FUNCTION_ENTRYPOINT con l'entry point 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 completo esistente nel codice sorgente.

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

    • REGION con la Google Cloud regione in cui vuoi eseguire il deployment della funzione. Ad esempio, europe-west1.

  2. Esegui il comando seguente per creare un trigger che filtri 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 del trigger.

    • EVENTARC_TRIGGER_LOCATION con la località per il trigger Eventarc. In generale, la località di un trigger Eventarc deve corrispondere alla località della Google Cloud risorsa che vuoi monitorare per gli eventi. Nella maggior parte degli scenari, devi anche eseguire il deployment della funzione nella stessa regione. Per saperne di più, vedi 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 Google Cloud progetto. I trigger Eventarc sono collegati ai service account da utilizzare come identità quando richiami la funzione. Il account di servizio del trigger Eventarc deve disporre dell'autorizzazione per richiamare la funzione. Per impostazione predefinita, Cloud Run utilizza il account di servizio Compute predefinito.

    Ogni flag event-filters specifica un tipo di evento, con la funzione che si attiva solo quando un evento soddisfa tutti i criteri specificati nei relativi flag event-filters. Ogni trigger deve avere un flag event-filters che specifica un tipo di evento supportato, ad esempio un nuovo documento scritto in Firestore o un file caricato in Cloud Storage. Non puoi modificare il tipo di filtro eventi dopo la creazione. Per modificare il tipo di filtro eventi, devi creare un nuovo trigger ed eliminare quello precedente. Se vuoi, puoi ripetere il flag --event-filters con un filtro supportato nel formato ATTRIBUTE=VALUE per aggiungere altri filtri.

Terraform

Per creare un trigger Eventarc per una funzione Cloud Run, vedi Creare un trigger utilizzando Terraform.

Passaggi successivi