Eventi di ripetizione

Eventarc Standard supporta la consegna degli eventi "at-least-once". Ciò significa che se una destinazione non riesce a riconoscere un evento, Eventarc tenterà automaticamente di riconsegnarlo.

Le caratteristiche di ripetizione di Eventarc Standard corrispondono a quelle del livello di trasporto, Cloud Pub/Sub, che gestisce gli errori di elaborazione utilizzando una policy di ripetizione della sottoscrizione.

Come funzionano i nuovi tentativi

Quando crei un trigger Eventarc, l'argomento e la sottoscrizione di trasporto Pub/Sub vengono creati automaticamente. (Gli eventi provenienti da origini Pub/Sub possono utilizzare un argomento Pub/Sub esistente.) Qualsiasi ID sottoscrizione creato automaticamente da Eventarc avrà un formato che inizia con eventarc-REGION-.

Per impostazione predefinita, quando una destinazione non riesce a riconoscere un messaggio, Pub/Sub lo invia di nuovo con un ritardo di backoff esponenziale. Un backoff esponenziale ti consente di aggiungere ritardi progressivamente più lunghi tra i nuovi tentativi. Il ritardo predefinito inizia con un minimo di 10 secondi e aumenta con ogni errore successivo, fino a un massimo di 600 secondi. Eventarc imposta la durata predefinita di conservazione dei messaggi su 24 ore.

Per saperne di più su come Pub/Sub gestisce i nuovi tentativi, consulta Gestire gli errori dei messaggi e le richieste di nuovi tentativi.

Best practice per la gestione dei nuovi tentativi

Se un messaggio di evento non può essere consegnato correttamente entro la finestra di conservazione dei messaggi, viene eliminato, a meno che non sia configurato un argomento messaggi non recapitabili. Un argomento messaggi non recapitabili ti consente di archiviare e analizzare gli errori persistenti. In questo documento, consulta Argomenti messaggi non recapitabili.

A causa della consegna "at-least-once", il gestore di eventi potrebbe ricevere eventi duplicati. Una best practice consiste nel progettare i gestori in modo che siano idempotenti. In questo documento, consulta Gestori di eventi idempotenti.

Nuovi tentativi per le destinazioni Cloud Run

Facoltativamente, per le destinazioni Cloud Run (incluse Cloud Run Functions), puoi configurare un singolo tentativo di consegna senza nuovi tentativi. Quando crei un trigger Eventarc nella Google Cloud console dalla pagina Cloud Run, questa è la configurazione predefinita. In caso contrario, quando crei un trigger utilizzando Google Cloud CLI, Terraform o nella Google Cloud console dalla pagina Eventarc, i nuovi tentativi sono abilitati per impostazione predefinita.

Ti consigliamo di disabilitare i nuovi tentativi durante lo sviluppo o il test del codice per evitare tentativi di nuovi tentativi incontrollati che possono comportare un aumento dei costi e dell'utilizzo delle risorse. Al contrario, ti consigliamo di abilitare i nuovi tentativi quando il codice è in produzione e di seguire le best practice per la gestione dei nuovi tentativi in modo che ogni messaggio venga elaborato come previsto. Ad esempio, puoi inoltrare i messaggi non consegnati a un argomento messaggi non recapitabili (noto anche come coda messaggi non recapitabili) che ti consente di archiviare e analizzare gli errori persistenti.

Per saperne di più, consulta le seguenti guide di Cloud Run: Configurare i nuovi tentativi di Cloud Run Functions e Creare trigger con Eventarc.

Configurare i nuovi tentativi

Potresti voler personalizzare il comportamento predefinito dei nuovi tentativi. Tutte le impostazioni di nuovi tentativi e conservazione vengono configurate tramite la policy di nuovi tentativi della sottoscrizione Pub/Sub associata al trigger Eventarc.

Per modificare la policy di nuovi tentativi della sottoscrizione, identifica prima la sottoscrizione Pub/Sub associata al trigger Eventarc. Quindi, aggiorna la sottoscrizione stessa.

Per saperne di più sulle proprietà delle sottoscrizioni, consulta Proprietà delle sottoscrizioni. Per informazioni sui limiti delle sottoscrizioni, consulta Limiti delle risorse Pub/Sub.

Identificare la sottoscrizione

Per identificare la sottoscrizione Pub/Sub associata al trigger Eventarc:

Console

  1. Nella Google Cloud console, vai alla pagina Trigger di Eventarc.

    Vai ai trigger

  2. Nell'elenco dei trigger, fai clic sul trigger di cui vuoi conoscere i dettagli.

  3. Fai clic sul nome dell'argomento.

  4. Per visualizzare l'ID sottoscrizione, fai clic sulla scheda Sottoscrizioni.

gcloud

Puoi utilizzare il gcloud eventarc triggers describe comando per recuperare l'ID sottoscrizione.

gcloud eventarc triggers describe TRIGGER_NAME \
    --location=LOCATION

Sostituisci quanto segue:

  • TRIGGER_NAME: il nome del trigger o un identificatore completo.
  • LOCATION: la località del trigger Eventarc.

Questo comando restituisce informazioni sul trigger simili alle seguenti e che includono l'ID sottoscrizione:

  createTime: '2023-03-16T13:40:44.889670204Z'
  destination:
    cloudRun:
      path: /
      region: us-central1
      service: hello
  eventDataContentType: application/protobuf
  eventFilters:
  ...
  transport:
    pubsub:
      subscription: projects/PROJECT_ID/subscriptions/SUBSCRIPTION_ID
      topic: projects/PROJECT_ID/topics/TOPIC_ID

Terraform

Per descrivere una google_eventarc_trigger risorsa Terraform, puoi utilizzare il comando state show.

terraform state show google_eventarc_trigger.default

Il comando state show restituisce informazioni sul trigger che includono l'ID sottoscrizione. Ad esempio:

# google_eventarc_trigger.default:
resource "google_eventarc_trigger" "default" {
    conditions              = {}
    create_time             = "2025-07-14T17:29:22.575033822Z"
    effective_labels        = {
        "goog-terraform-provisioned" = "true"
    }
    ...
    transport {
        pubsub {
            subscription = "projects/PROJECT_ID/subscriptions/SUBSCRIPTION_ID"
            topic        = "projects/PROJECT_ID/topics/TOPIC_ID"
        }
    }
}

Per saperne di più sull'utilizzo di Terraform, consulta la documentazione di Google Cloud Terraform.

REST

Per descrivere un trigger in un determinato progetto e in una determinata località, utilizza il projects.locations.triggers.get metodo.

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

  • TRIGGER_NAME: il nome del trigger che vuoi descrivere.
  • PROJECT_ID: il tuo Google Cloud ID progetto.
  • LOCATION: la regione in cui viene creato il trigger, ad esempio us-central1.

Per inviare la richiesta, espandi una di queste opzioni:

In caso di esito positivo, il corpo della risposta contiene un'istanza di Trigger simile alla seguente: 

{
  "name": "projects/PROJECT_ID/locations/LOCATION/triggers/TRIGGER_NAME",
  "uid": "d700773a-698b-47b2-a712-2ee10b690062",
  "createTime": "2022-12-06T22:44:04.744001514Z",
  "updateTime": "2022-12-06T22:44:09.116459550Z",
  "eventFilters": [
    {
      "attribute": "type",
      "value": "google.cloud.pubsub.topic.v1.messagePublished"
    }
  ],
  "serviceAccount": "SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com",
  "destination": {
    "workflow": "projects/PROJECT_ID/locations/LOCATION/workflows/WORKFLOW_NAME"
  },
  "transport": {
    "pubsub": {
      "topic": "projects/PROJECT_ID/topics/TOPIC_ID",
      "subscription": "projects/PROJECT_ID/subscriptions/SUBSCRIPTION_ID"
    }
  }
}

Aggiornare la sottoscrizione

Per aggiornare la policy di nuovi tentativi della sottoscrizione Pub/Sub associata al trigger Eventarc:

Console

  1. Nella Google Cloud console, vai alla pagina Trigger di Eventarc.

    Vai ai trigger

  2. Nell'elenco dei trigger, fai clic sul trigger di cui vuoi conoscere i dettagli.

  3. Fai clic sul nome dell'argomento.

  4. Per visualizzare l'ID sottoscrizione, fai clic sulla scheda Sottoscrizioni.

  5. Fai clic sull'ID sottoscrizione e poi su Modifica.

  6. Nella sezione Policy di nuovi tentativi, seleziona Riprova immediatamente.

    In alternativa, per riprovare dopo un ritardo di backoff esponenziale, inserisci i seguenti valori in secondi:

    • Backoff minimo: il ritardo minimo in secondi tra le consegne consecutive di un determinato messaggio. Il valore predefinito è 10 secondi e deve essere compreso tra 0 e 600.

    • Backoff massimo: il ritardo massimo in secondi tra le consegne consecutive di un determinato messaggio. Il valore predefinito è 600 secondi e deve essere compreso tra 0 e 600.

    Per saperne di più, consulta Policy di nuovi tentativi.

  7. Fai clic su Aggiorna.

gcloud

Puoi utilizzare il gcloud pubsub subscriptions update comando per aggiornare la policy di nuovi tentativi della sottoscrizione.

gcloud pubsub subscriptions update SUBSCRIPTION_ID \
    --min-retry-delay=MIN_RETRY_DELAY \
    --max-retry-delay=MAX_RETRY_DELAY

Sostituisci quanto segue:

  • SUBSCRIPTION_ID: l'ID della sottoscrizione o un identificatore completo.

  • Devi specificare entrambi i seguenti flag per riprovare dopo un ritardo di backoff esponenziale; in caso contrario, qualsiasi flag omesso torna al valore predefinito:

    • MIN_RETRY_DELAY: il ritardo minimo in secondi tra le consegne consecutive di un determinato messaggio. Il valore predefinito è 10 secondi e deve essere compreso tra 0 e 600.
    • MAX_RETRY_DELAY: il ritardo massimo in secondi tra le consegne consecutive di un determinato messaggio. Il valore predefinito è 600 secondi e deve essere compreso tra 0 e 600.

Facoltativamente, puoi utilizzare il flag --clear-retry-policy per cancellare la policy di nuovi tentativi e impostare la sottoscrizione in modo che riprovi immediatamente.

Terraform

Puoi aggiornare una policy di nuovi tentativi della sottoscrizione Pub/Sub by configuring the google_pubsub_subscription risorsa Terraform. Utilizza il import blocco per importare la sottoscrizione esistente in modo che Terraform possa monitorare la risorsa nel file di stato. Puoi quindi gestire la risorsa importata come qualsiasi altra, utilizzando ignore_changes per specificare gli attributi che Terraform deve ignorare durante l'aggiornamento della risorsa.

Ad esempio:

import {
  to = google_pubsub_subscription.default
  id = "SUBSCRIPTION_ID"
}

resource "google_pubsub_subscription" "default" {
  name  = "SUBSCRIPTION_ID"
  topic = "TOPIC_ID"
  retry_policy {
    minimum_backoff = "MIN_RETRY_DELAYs"
    maximum_backoff = "MAX_RETRY_DELAYs"
  }
  lifecycle {
    # Ignore push delivery configuration which is managed by Eventarc
    ignore_changes = [push_config]
  }
}

Sostituisci quanto segue:

  • SUBSCRIPTION_ID: l'ID della sottoscrizione.
  • TOPIC_ID: l'ID dell'argomento.
  • MIN_RETRY_DELAY: il ritardo minimo in secondi tra le consegne consecutive di un determinato messaggio. Il valore predefinito è 10 secondi e deve essere compreso tra 0 e 600.
  • MAX_RETRY_DELAY: il ritardo massimo in secondi tra le consegne consecutive di un determinato messaggio. Il valore predefinito è 600 secondi e deve essere compreso tra 0 e 600.

REST

Per aggiornare la policy di nuovi tentativi per una sottoscrizione in un determinato progetto, utilizza il projects.subscriptions.patch metodo.

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

  • MIN_RETRY_DELAY: il ritardo minimo in secondi tra le consegne consecutive di un determinato messaggio. Il valore predefinito è 10 secondi e deve essere compreso tra 0 e 600.
  • MAX_RETRY_DELAY: il ritardo massimo in secondi tra le consegne consecutive di un determinato messaggio. Il valore predefinito è 600 secondi e deve essere compreso tra 0 e 600.
  • PROJECT_ID: il tuo Google Cloud ID progetto.
  • SUBSCRIPTION_ID: l'ID della sottoscrizione Pub/Sub che stai aggiornando.

Corpo JSON della richiesta: 

{
  "subscription": {
    "retryPolicy": {
      "minimumBackoff": "MIN_RETRY_DELAYs",
      "maximumBackoff": "MAX_RETRY_DELAYs"
    }
  },
  "updateMask": "retry_policy.maximum_backoff,retry_policy.minimum_backoff"
}

Per inviare la richiesta, espandi una di queste opzioni:

In caso di esito positivo, il corpo della risposta contiene un'istanza di Subscription simile alla seguente: 

{
  "name": "projects/PROJECT_ID/subscriptions/SUBSCRIPTION_ID",
  "topic": "projects/PROJECT_ID/topics/TOPIC_ID",
  ...
  "retryPolicy": {
    "minimumBackoff": "MIN_RETRY_DELAYs",
    "maximumBackoff": "MAX_RETRY_DELAYs"
  },
  "state": "ACTIVE"
}

Altre considerazioni sui nuovi tentativi

Devi tenere presente le seguenti considerazioni quando gestisci gli errori di elaborazione o inoltri i messaggi non consegnati.

Backoff push

Se un sottoscrittore push invia troppi riconoscimenti negativi, Pub/Sub potrebbe iniziare a consegnare i messaggi utilizzando un backoff push. Quando Pub/Sub utilizza un backoff push, interrompe la consegna dei messaggi per un periodo di tempo predeterminato. Questo intervallo di tempo può variare da 100 millisecondi a 60 secondi. Trascorso questo periodo di tempo, Pub/Sub riprende a consegnare i messaggi. Per saperne di più, consulta Backoff push.

Argomenti messaggi non recapitabili

Se la destinazione non riceve il messaggio, puoi inoltrare i messaggi non consegnati a un argomento messaggi non recapitabili (noto anche come coda messaggi non recapitabili). Un argomento messaggi non recapitabili può archiviare i messaggi che la destinazione non riesce a riconoscere. Devi impostare un argomento messaggi non recapitabili quando crei o aggiorni una sottoscrizione Pub/Sub, non quando crei un argomento Pub/Sub o quando Eventarc crea un argomento Pub/Sub. Per saperne di più, consulta Configurare un argomento messaggi non recapitabili.

Errori che non giustificano i nuovi tentativi

Quando le applicazioni utilizzano Pub/Sub come origine eventi e l'evento non viene consegnato, viene eseguito automaticamente un nuovo tentativo, ad eccezione degli errori che non giustificano i nuovi tentativi. Non verrà eseguito un nuovo tentativo per gli eventi inviati a una destinazione Workflows da qualsiasi origine se il workflow non viene eseguito. Tieni presente che Workflows riconosce gli eventi non appena inizia l'esecuzione del workflow. Se l'esecuzione del workflow inizia, ma in un secondo momento non va a buon fine, non vengono eseguiti nuovi tentativi. Per risolvere questi problemi di servizio, devi gestire gli errori e i nuovi tentativi all'interno del workflow.

Duplicare gli eventi

Potrebbero essere consegnati eventi duplicati ai gestori di eventi. Secondo la specifica CloudEvents, la combinazione degli attributi source e id è considerata univoca e, pertanto, tutti gli eventi con la stessa combinazione sono considerati duplicati. Una best practice generale consiste nell'implementare gestori di eventi idempotenti.

Gestori di eventi idempotenti

I gestori di eventi per cui è possibile eseguire nuovi tentativi devono essere idempotenti, utilizzando le seguenti linee guida generali:

  • Molte API esterne ti consentono di fornire una chiave di idempotenza come parametro. Se utilizzi un'API di questo tipo, devi utilizzare l'ID evento come chiave di idempotenza.
  • L'idempotenza funziona bene con la consegna "at-least-once", perché rende sicura l'esecuzione di un nuovo tentativo. Pertanto, una best practice generale per scrivere codice affidabile è combinare l'idempotenza con la ripetizione dei tentativi.
  • Assicurati che il codice sia idempotente internamente. Ad esempio:
    • Assicurati che le mutazioni possano verificarsi più di una volta senza modificare il risultato.
    • Fai query sullo stato del database in una transazione prima di mutarlo.
    • Assicurati che tutti gli effetti collaterali siano a loro volta idempotenti.
  • Imponi un controllo transazionale all'esterno del servizio, indipendente dal codice. Ad esempio, conserva da qualche parte lo stato registrando che un determinato ID evento è già stato elaborato.
  • Gestisci le chiamate duplicate fuori banda. Ad esempio, esegui un processo separato per liberare spazio dopo le chiamate duplicate.