Eventi di ripetizione

Eventarc Standard supporta la distribuzione degli eventi "at-least-once". Ciò significa che se una destinazione non conferma la ricezione di un evento, Eventarc tenterà automaticamente di inviarlo di nuovo.

Le caratteristiche dei nuovi tentativi di Eventarc Standard corrispondono a quelle del suo livello di trasporto, Cloud Pub/Sub, che gestisce gli errori di elaborazione utilizzando un criterio di nuovi tentativi di sottoscrizione.

Come funzionano i 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 abbonamento creato automaticamente da Eventarc avrà un formato che inizia con eventarc-REGION-.

Per impostazione predefinita, quando una destinazione non può confermare la ricezione di 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 da un minimo di 10 secondi e aumenta a ogni errore successivo, fino a un massimo di 600 secondi. Eventarc imposta la durata predefinita di conservazione dei messaggi su 24 ore.

Per ulteriori informazioni su come Pub/Sub gestisce i tentativi, vedi Gestire gli errori dei messaggi e Tentativi di richiesta.

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 permanenti. In questo documento, vedi Argomenti non recapitabili.

A causa della distribuzione almeno una volta, il gestore eventi potrebbe ricevere eventi duplicati. Una best practice consiste nel progettare i gestori in modo che siano idempotenti. In questo documento, vedi Gestori di eventi idempotenti.

Configura i tentativi

Potresti voler personalizzare il comportamento di ripetizione predefinito. Tutte le impostazioni di nuovi tentativi e conservazione vengono configurate tramite il criterio di nuovi tentativi di sottoscrizione Pub/Sub associato al trigger Eventarc.

Per modificare la policy di nuovi tentativi di sottoscrizione, identifica prima la sottoscrizione Pub/Sub associata al trigger Eventarc. Poi, aggiorna l'abbonamento.

Per ulteriori informazioni sulle proprietà delle sottoscrizioni, consulta Proprietà delle sottoscrizioni. Per informazioni sui limiti di sottoscrizione, consulta Limiti delle risorse Pub/Sub.

Identificare l'abbonamento

Per identificare la sottoscrizione Pub/Sub associata al tuo trigger Eventarc, segui questi passaggi:

gcloud eventarc triggers describe TRIGGER_NAME \
    --location=LOCATION

  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 state show google_eventarc_trigger.default

# 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"
        }
    }
}

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://eventarc.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/triggers/TRIGGER_NAME"

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://eventarc.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/triggers/TRIGGER_NAME" | Select-Object -Expand Content

{
  "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 l'abbonamento

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

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

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]
  }
}

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

cat > request.json << 'EOF'
{
  "subscription": {
    "retryPolicy": {
      "minimumBackoff": "MIN_RETRY_DELAYs",
      "maximumBackoff": "MAX_RETRY_DELAYs"
    }
  },
  "updateMask": "retry_policy.maximum_backoff,retry_policy.minimum_backoff"
}
EOF

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://pubsub.googleapis.com/v1/projects/PROJECT_ID/subscriptions/SUBSCRIPTION_ID"

@'
{
  "subscription": {
    "retryPolicy": {
      "minimumBackoff": "MIN_RETRY_DELAYs",
      "maximumBackoff": "MAX_RETRY_DELAYs"
    }
  },
  "updateMask": "retry_policy.maximum_backoff,retry_policy.minimum_backoff"
}
'@  | Out-File -FilePath request.json -Encoding utf8

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://pubsub.googleapis.com/v1/projects/PROJECT_ID/subscriptions/SUBSCRIPTION_ID" | Select-Object -Expand Content

{
  "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 tentativi

Tieni presente le seguenti considerazioni quando gestisci gli errori di elaborazione o l'inoltro dei messaggi non recapitati.

Rinvii push

Se un sottoscrittore push invia troppi riconoscimenti negativi, Pub/Sub potrebbe iniziare a recapitare i messaggi utilizzando un backoff push. Quando Pub/Sub utilizza un backoff push, interrompe il recapito dei messaggi per un periodo di tempo predeterminato. Questo intervallo di tempo può variare da 100 millisecondi a 60 secondi. Trascorso il periodo di tempo, Pub/Sub inizia di nuovo a recapitare i messaggi. Per maggiori informazioni, consulta Rinvio push.

Argomenti messaggi non recapitabili

Se la destinazione non riceve il messaggio, puoi inoltrare i messaggi non recapitati 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 può riconoscere. Devi impostare unargomento messaggi non recapitabilir 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 dead letter.

Errori che non giustificano i nuovi tentativi

Quando le applicazioni utilizzano Pub/Sub come origine eventi e l'evento non viene recapitato, viene ritentato automaticamente, ad eccezione degli errori che non giustificano i nuovi tentativi. Gli eventi a una destinazione Workflows da qualsiasi origine non verranno ritentati 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 non va a buon fine, i tentativi di esecuzione non vengono ripetuti. Per risolvere questi problemi del servizio, devi gestire gli errori e i tentativi all'interno del flusso di lavoro.

Duplicare gli eventi

Gli eventi duplicati potrebbero essere inviati 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. Come best practice generale, devi implementare i gestori di eventi idempotenti.

Gestori di eventi idempotenti

I gestori di eventi che possono essere riprovati devono essere idempotenti e seguire 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 sicuro il nuovo tentativo. Pertanto, una best practice generale per scrivere codice affidabile è combinare l'idempotenza con i tentativi.
• Assicurati che il codice sia idempotente internamente. Ad esempio:
  • Assicurati che le mutazioni possano verificarsi più di una volta senza modificare il risultato.
  • Esegui query sullo stato del database in una transazione prima di modificarlo.
  • Assicurati che tutti gli effetti collaterali siano idempotenti.
• Imponi un controllo transazionale al di fuori del tuo servizio, indipendentemente dal codice. Ad esempio, mantieni lo stato in un punto in cui viene registrato che un determinato ID evento è già stato elaborato.
• Gestisci le chiamate duplicate fuori banda. Ad esempio, esegui un processo di pulizia separato che pulisce dopo le chiamate duplicate.