Creare trigger con Eventarc

Questa pagina mostra come creare un trigger Eventarc in modo che un servizio Cloud Run possa ricevere eventi da un altro servizio Google Cloud.

Eventarc è un servizio Google Cloud che ti consente di creare architetture basate su eventi senza dover implementare, personalizzare o gestire l'infrastruttura sottostante.

Puoi creare un trigger Eventarc specificando i filtri per l'trigger e configurando il routing dell'evento, inclusa l'origine dell'evento e il servizio Cloud Run di destinazione. Quando l'evento o l'insieme di eventi specificato corrisponde ai filtri, il servizio Cloud Run viene invocato automaticamente in risposta agli eventi. Un servizio che utilizza gli trigger Eventarc è chiamato servizio basato su eventi. Gli eventi inviati al servizio Cloud Run vengono ricevuti sotto forma di richieste HTTP.

I seguenti tipi di eventi attivano richieste al tuo servizio:

Puoi anche creare un trigger Eventarc utilizzando Google Cloud CLI o la pagina della console Eventarc. Per istruzioni su come creare un attivatore per un provider, un tipo di evento e una destinazione specifici, filtra l'elenco per scoprire di più su Fornitori e destinazioni di eventi di Eventarc.

Posizione dell'attivatore

Quando crei un trigger Eventarc, devi specificarne una posizione. Deve corrispondere alla località della risorsa Google Cloud per cui vuoi monitorare gli eventi. Nella maggior parte degli scenari, devi anche eseguire il deployment del servizio Cloud Run basato su eventi nella stessa regione. Per ulteriori informazioni, consulta Informazioni sulle località Eventarc.

Id trigger

L'account di servizio dell'attivatore Eventarc deve disporre dell'autorizzazione per richiamare il servizio. Potresti dover verificare che l'account di servizio Compute predefinito disponga delle autorizzazioni corrette per richiamare il tuo servizio. Per ulteriori informazioni, consulta Ruoli richiesti.

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 ed Eventarc:

    Abilita le API

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 relativa alla 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 Eventarc, 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 sono richiamabili solo dai proprietari, dagli editor e dagli amministratori e dagli 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 un'opzione.

  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 un fornitore di eventi dall'elenco Fornitore 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 un tipo di evento 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. 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.

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

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

    8. 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=REGION \
    --destination-run-service=SERVICE  \
    --destination-run-region=REGION \
    --event-filters="EVENT_FILTER" \
    --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 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 evento, devi creare un nuovo attivatore ed eliminare quello precedente. Se vuoi, puoi ripetere il flag --event-filters con un filtro supportato nel formato 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 un'opzione.

  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 un fornitore di eventi 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 un tipo di evento 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. 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.

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

    7. 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 eseguirne il deployment 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=REGION \
    --destination-run-service=FUNCTION  \
    --destination-run-region=REGION \
    --event-filters="EVENT_FILTER" \
    --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 degli scenari, 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 evento, devi creare un nuovo attivatore ed eliminare quello precedente. Se vuoi, puoi ripetere il flag --event-filters con un filtro supportato nel formato ATTRIBUTE=VALUE per aggiungere altri filtri.

Passaggi successivi