Crea trigger con Eventarc

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

Eventarc è un Google Cloudservizio 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 il trigger e configurando il routing dell'evento, inclusi l'origine 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 richiamato automaticamente in risposta agli eventi. Un servizio che utilizza i trigger di Eventarc è chiamato servizio basato sugli eventi. Gli eventi inviati al servizio Cloud Run vengono ricevuti sotto forma di richieste HTTP.

I seguenti tipi di eventi possono attivare richieste al tuo servizio:

Posizione del trigger

Quando crei un trigger Eventarc, devi specificare una posizione. Questo dovrebbe corrispondere alla posizione della risorsa Google Cloud che si desidera monitorare per gli eventi. Nella maggior parte degli scenari, devi anche eseguire il deployment del servizio Cloud Run basato su eventi nella stessa regione. Per saperne di più, consulta Informazioni sulle località Eventarc.

Identità del trigger

Quando crei un trigger Eventarc, specifichi un service account IAM (Identity and Access Management). Il trigger utilizza questo account di servizio come identità predefinita. Si consiglia di specificare un account di servizio gestito dall'utente e di concedergli le autorizzazioni minime necessarie.

Prima di iniziare

  1. Configura il tuo ambiente Cloud Run.

  2. Abilita le API Artifact Registry, Cloud Build, API Cloud Run Admin ed Eventarc:

    Abilita le API

  3. Concedi i ruoli e le autorizzazioni IAM richiesti.

Crea un trigger per i servizi

Dopo aver distribuito un servizio, è possibile configurare un trigger utilizzando la console Google Cloud , Google Cloud CLI o Terraform.

Console

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

  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 un'opzione.

  6. Nel riquadro Eventarc trigger, modificare 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 integrarsi con fornitori non Google che offrono una sorgente Eventarc. Per saperne di più, vedi Eventi di terze parti in Eventarc.

    3. Seleziona un provider di eventi 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, vedi Fornitori e destinazioni di eventi.

    4. Seleziona un tipo di evento dall'elenco Tipo di evento. La configurazione del trigger varia a seconda del tipo di evento supportato. Per saperne di più, consulta Tipi di eventi.

    5. Se il campo Region è abilitato, seleziona una location per il trigger Eventarc. In generale, la località di un trigger Eventarc deve corrispondere a quella della Google Cloud risorsa che vuoi monitorare per gli eventi. Nella maggior parte degli scenari, devi anche deployare il servizio nella stessa regione. Per maggiori dettagli sulle località dei trigger Eventarc, consulta Informazioni sulle località Eventarc.

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

    7. (Facoltativo) Specifica il percorso dell'URL del servizio a cui inviare la richiesta in entrata. Questo è il percorso relativo nel servizio di destinazione a cui devono essere inviati gli eventi per il trigger. Ad esempio: /, /route, route e route/subroute.

    8. (Facoltativo) Per abilitare i nuovi tentativi se il tentativo di consegna non va a buon fine, seleziona la casella di controllo Abilita ripetizione dei tentativi in caso di errore; in caso contrario, il comportamento predefinito è un singolo tentativo di consegna senza ripetizioni. Per ulteriori informazioni, vedere Eventi di riprova.

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

  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 container o da origine.

  2. Esegui questo comando per creare un trigger che filtri ed esegua il routing degli eventi:

    gcloud eventarc triggers create TRIGGER_NAME  \
    --location=LOCATION \
    --destination-run-service=DESTINATION_RUN_SERVICE  \
    --destination-run-region=DESTINATION_RUN_REGION \
    --event-filters="type=EVENT_FILTER_TYPE" \
    --max-retry-attempts=1 \
    --service-account=SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com

    Sostituisci quanto segue:

    • TRIGGER_NAME: l'ID del trigger o un identificatore completo.
    • LOCATION: la posizione del trigger Eventarc. In alternativa, è possibile impostare la proprietà eventarc/location; ad esempio, gcloud config set eventarc/location us-central1.

      Per evitare problemi di prestazioni e residenza dei dati, la località deve corrispondere a quella del Google Cloud servizio che genera eventi. Per saperne di più, consulta Località Eventarc.

    • DESTINATION_RUN_SERVICE: il nome del servizio Cloud Run che riceve gli eventi per il trigger. Il servizio può trovarsi in una qualsiasi delle località supportate da Cloud Run e non deve trovarsi nella stessa località del trigger. Tuttavia, il servizio deve trovarsi nello stesso progetto del trigger e riceverà gli eventi come richieste HTTP POST inviate al percorso dell'URL principale (/), ogni volta che l'evento viene generato.
    • DESTINATION_RUN_REGION: (facoltativo) la posizione di Cloud Run in cui si trova il servizio Cloud Run di destinazione. Se non specificato, si presume che il servizio si trovi nella stessa regione del trigger.
    • EVENT_FILTER_TYPE: l'identificatore dell'evento. Viene generato un evento quando una chiamata API per il metodo ha esito positivo. Per le operazioni a lunga esecuzione, l'evento viene generato solo al termine dell'operazione e solo se l'azione viene eseguita correttamente. Per un elenco dei tipi di eventi supportati, consulta Tipi di eventi Google supportati da Eventarc.
    • SERVICE_ACCOUNT_NAME: il nome del tuo account di servizio gestito dall'utente.
    • PROJECT_ID: il tuo ID progetto Google Cloud .

    Note:

    • Il flag --event-filters="type=EVENT_FILTER_TYPE" è obbligatorio. Se non è impostato alcun altro filtro eventi, vengono abbinati gli eventi per tutte le risorse.
    • EVENT_FILTER_TYPE non può essere modificato dopo la creazione. Per modificare EVENT_FILTER_TYPE, crea un nuovo trigger ed elimina quello precedente.
    • Ogni attivatore può avere più filtri evento, separati da virgole in un unico --event-filters=[ATTRIBUTE=VALUE,...] flag oppure puoi ripetere il flag per aggiungere altri filtri. Solo gli eventi che corrispondono a tutti i filtri vengono inviati alla destinazione. I caratteri jolly e le espressioni regolari non sono supportati. Tuttavia, quando utilizzi il flag --event-filters-path-pattern, puoi definire un pattern di percorso della risorsa.
    • (Facoltativo) Per specificare un singolo tentativo di invio di eventi senza ripetizioni, utilizza il flag --max-retry-attempts. L'unico valore valido è 1. Se si omette il flag, si applica il comportamento standard di ritentativo. Per saperne di più, vedi Nuovi tentativi per gli eventi.
    • Sono disponibili altri flag. Per saperne di più, vedi gcloud eventarc triggers create.

Terraform

Per creare un trigger Eventarc per un servizio Cloud Run, consulta Crea un trigger utilizzando Terraform.

Crea un trigger per le funzioni

Dopo aver distribuito una funzione, è possibile configurare un trigger utilizzando la console Google Cloud , Google Cloud CLI o Terraform.

Console

Quando utilizzi la console Google Cloud per creare una funzione, puoi anche aggiungere un trigger alla tua funzione. Per creare un attivatore per la tua 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 Esegui il deployment delle funzioni.

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

  4. Seleziona un'opzione.

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

    1. Inserisci un nome per il trigger nel campo Nome del trigger oppure usa il nome predefinito.

    2. Seleziona un tipo di trigger Tipo dall'elenco:

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

      • Terze parti per integrarsi con fornitori non Google che offrono una sorgente Eventarc. Per saperne di più, vedi 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, vedi Fornitori e destinazioni di eventi.

    4. Seleziona un tipo di evento dall'elenco Tipo di evento. La configurazione del trigger varia a seconda del tipo di evento supportato. Per saperne di più, consulta Tipi di eventi.

    5. Se il campo Region è abilitato, seleziona una location per il trigger Eventarc. In generale, la posizione di un trigger Eventarc dovrebbe corrispondere alla posizione della risorsaGoogle Cloud che si desidera monitorare per gli eventi. Nella maggior parte degli scenari, devi anche eseguire il deployment della funzione nella stessa regione. Per ulteriori dettagli sulle posizioni dei trigger di Eventarc, consultare la sezione Informazioni sulle posizioni di Eventarc.

    6. Nel campo Service account, seleziona un account di servizio. I trigger di Eventarc sono collegati agli account di servizio da utilizzare come identità durante l'invocazione della funzione. L'account di servizio del trigger Eventarc deve disporre dell'autorizzazione per richiamare la funzione. Per impostazione predefinita, Cloud Run utilizza l'account di servizio predefinito di Compute Engine.

    7. (Facoltativo) Specifica il percorso dell'URL del servizio a cui inviare la richiesta in entrata. Questo è il percorso relativo nel servizio di destinazione a cui devono essere inviati gli eventi per il trigger. Ad esempio: /, /route, route e route/subroute.

    8. (Facoltativo) Per abilitare i nuovi tentativi se il tentativo di consegna non va a buon fine, seleziona la casella di controllo Abilita ripetizione dei tentativi in caso di errore; in caso contrario, il comportamento predefinito è un singolo tentativo di consegna senza ripetizioni. Per ulteriori informazioni, vedere Eventi di riprova.

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

  7. Fai clic su Crea.

  8. Nella scheda Source, modifica il codice sorgente se necessario, quindi seleziona Salva e ridistribuisci.

gcloud

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

  1. Esegui questo comando 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 quanto segue:

    • FUNCTION: 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: 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: l'ambiente dell'immagine di base per la funzione. Per maggiori dettagli sulle immagini di base e sui pacchetti inclusi in ogni immagine, consulta Immagini di base dei runtime.

    • REGION: la regione Google Cloudin cui vuoi eseguire il deployment della funzione. Ad esempio: europe-west1.

  2. Esegui il seguente comando per creare un trigger che filtra e instrada gli eventi:

    gcloud eventarc triggers create TRIGGER_NAME \
    --location=LOCATION \
    --destination-run-service=FUNCTION \
    --destination-run-region=DESTINATION_RUN_REGION \
    --event-filters="type=EVENT_FILTER_TYPE" \
    --max-retry-attempts=1 \
    --service-account=SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com

    Sostituisci quanto segue:

    • TRIGGER_NAME: l'ID del trigger o un identificatore completo.
    • LOCATION: la posizione del trigger Eventarc. In alternativa, è possibile impostare la proprietà eventarc/location; ad esempio, gcloud config set eventarc/location us-central1.

      Per evitare problemi di prestazioni e residenza dei dati, la località deve corrispondere a quella del Google Cloud servizio che genera eventi. Per saperne di più, consulta Località Eventarc.

    • FUNCTION: il nome della funzione Cloud Run di cui è stato eseguito il deployment che riceve gli eventi per il trigger.
    • DESTINATION_RUN_REGION: (facoltativo) la posizione di Cloud Run in cui si trova la funzione Cloud Run di destinazione. Se non specificato, si presume che la funzione si trovi nella stessa regione del trigger.
    • EVENT_FILTER_TYPE: l'identificatore dell'evento. Viene generato un evento quando una chiamata API per il metodo ha esito positivo. Per le operazioni a lunga esecuzione, l'evento viene generato solo al termine dell'operazione e solo se l'azione viene eseguita correttamente. Per un elenco dei tipi di eventi supportati, consulta Tipi di eventi Google supportati da Eventarc.
    • SERVICE_ACCOUNT_NAME: il nome del account di servizio gestito dall'utente.
    • PROJECT_ID: il tuo ID progetto Google Cloud .

    Note:

    • Il flag --event-filters="type=EVENT_FILTER_TYPE" è obbligatorio. Se non è impostato alcun altro filtro eventi, vengono abbinati gli eventi per tutte le risorse.
    • EVENT_FILTER_TYPE non può essere modificato dopo la creazione. Per modificare EVENT_FILTER_TYPE, crea un nuovo trigger ed elimina quello precedente.
    • Ogni attivatore può avere più filtri evento, separati da virgole in un unico --event-filters=[ATTRIBUTE=VALUE,...] flag oppure puoi ripetere il flag per aggiungere altri filtri. Solo gli eventi che corrispondono a tutti i filtri vengono inviati alla destinazione. I caratteri jolly e le espressioni regolari non sono supportati. Tuttavia, quando utilizzi il flag --event-filters-path-pattern, puoi definire un pattern di percorso della risorsa.
    • (Facoltativo) Per specificare un singolo tentativo di invio di eventi senza ripetizioni, utilizza il flag --max-retry-attempts. L'unico valore valido è 1. Se si omette il flag, si applica il comportamento standard di ritentativo. Per saperne di più, vedi Nuovi tentativi per gli eventi.
    • Sono disponibili altri flag. Per saperne di più, vedi gcloud eventarc triggers create.

Terraform

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

Imposta la scadenza di riconoscimento Pub/Sub

Le funzioni Cloud Run basate sugli eventi vengono implementate utilizzando Eventarc in combinazione con un abbonamento Pub/Sub. Per impostazione predefinita, la scadenza di conferma (ack) di questo abbonamento Pub/Sub è di 10 secondi. Questa impostazione è insufficiente per molte funzioni e può causare esecuzioni duplicate indesiderate.

Si consiglia di impostare la scadenza ack per il servizio o la funzione al valore massimo di 600 secondi come segue:

Console

Dopo aver eseguito il deployment della funzione, segui questi passaggi per modificare la scadenza ack della funzione:

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

    Vai a Cloud Run

  2. Individua la funzione che vuoi aggiornare nell'elenco Servizi e fai clic per aprire i dettagli della funzione.

  3. Apri la scheda Trigger.

  4. Fai clic sul nome del trigger per aprire Dettagli del trigger.

  5. Fai clic sul collegamento Argomento per aprire il riquadro di modifica dell'argomento.

  6. Fai clic sul nome dell'ID abbonamento per andare al riquadro dell'abbonamento e fai clic su Modifica nella parte superiore della pagina.

  7. Imposta il valore per Scadenza per la conferma su 600 e fai clic su Aggiorna per salvare la modifica.

gcloud

Aggiorna il termine ack per trigger al valore massimo di 600 secondi. Tieni presente che i seguenti comandi fanno riferimento a variabili (TRIGGER_NAME e LOCATION) i cui valori sono stati impostati nei passaggi precedenti.

## Per Cloud Run function:

# Update Ack Deadline to max (600s)
SUBSCRIPTION_ID=$(gcloud eventarc triggers describe "$TRIGGER_NAME" --location $LOCATION --format json | jq -r '.transport.pubsub.subscription')
gcloud pubsub subscriptions update "$SUBSCRIPTION_ID" --ack-deadline=600

Eseguire un aggiornamento in blocco su tutti i trigger di servizi e funzioni per impostare le loro scadenze ack a 600 secondi:

### Match all Cloud Run service triggers and update all deadlines to 600s (max timeout)
### This will change ALL Cloud Run services and Cloud Run functions
TRIGGER_NAMES=($(gcloud eventarc triggers list | awk '/Cloud Run service/ {print $1}'))

if [ ${#TRIGGER_NAMES[@]} -eq 0 ]; then
  echo "No matching triggers found"
fi

for trigger in "${TRIGGER_NAMES[@]}"; do
echo "Updating ack deadline for trigger: $trigger"
SUBSCRIPTION_ID=$(gcloud eventarc triggers describe "$trigger" --location $LOCATION --format json | jq -r '.transport.pubsub.subscription')

if [ -z "$SUBSCRIPTION_ID" ]; then
    echo "Error: Could not retrieve subscription ID for trigger: $trigger"
    continue # Skip to the next trigger
fi
gcloud pubsub subscriptions update "$SUBSCRIPTION_ID" --ack-deadline=600
echo "Ack deadline updated for subscription: $SUBSCRIPTION_ID"
done

Visualizza l'ID e l'origine di CloudEvent

Per visualizzare l'ID e l'origine CloudEvent che hanno attivato il servizio, visualizza le seguenti risorse nei log del servizio Cloud Run:

  • LogEntry.labels.run.googleapis.com/cloud_event_id
  • LogEntry.labels.run.googleapis.com/cloud_event_source

Passaggi successivi