Wiederholungsereignisse

Eventarc Standard unterstützt die „Mindestens einmal“-Ereignisübermittlung. Wenn ein Ziel ein Ereignis nicht bestätigt, versucht Eventarc automatisch, es noch einmal zu senden.

Die Wiederholungsmerkmale von Eventarc Standard entsprechen denen der Transportebene, Cloud Pub/Sub, die Verarbeitungsfehler mithilfe einer Wiederholungsrichtlinie für Abos behandelt.

So funktionieren Wiederholungsversuche

Wenn Sie einen Eventarc-Trigger erstellen, werden das Pub/Sub-Transportthema und das Abo automatisch für Sie erstellt. Ereignisse aus Pub/Sub-Quellen können ein vorhandenes Pub/Sub-Thema verwenden. Alle von Eventarc automatisch erstellten Abo-IDs haben ein Format, das mit eventarc-REGION- beginnt.

Wenn ein Ziel eine Nachricht nicht bestätigen kann, sendet Pub/Sub die Nachricht standardmäßig noch einmal mit einer exponentiellen Backoff-Verzögerung. Mit einem exponentiellen Backoff können Sie zwischen Wiederholungsversuchen schrittweise längere Verzögerungen hinzufügen. Die Standardverzögerung beginnt bei mindestens 10 Sekunden und erhöht sich mit jedem nachfolgenden Fehler auf maximal 600 Sekunden. Eventarc legt die standardmäßige Aufbewahrungsdauer für Nachrichten auf 24 Stunden fest.

Weitere Informationen dazu, wie Pub/Sub Wiederholungsversuche handhabt, finden Sie unter Umgang mit Nachrichtenfehlern und Anfragen wiederholen.

Best Practices für die Verarbeitung von Wiederholungsversuchen

Wenn eine Ereignisnachricht innerhalb des Aufbewahrungszeitraums für Nachrichten nicht zugestellt werden kann, wird sie verworfen, sofern kein Thema für unzustellbare Nachrichten konfiguriert ist. In einem Thema für unzustellbare Nachrichten können Sie dauerhafte Fehler speichern und analysieren. Weitere Informationen finden Sie in diesem Dokument unter Themen für unzustellbare Nachrichten.

Aufgrund der „at-least-once“-Zustellung kann Ihr Event-Handler doppelte Ereignisse empfangen. Es empfiehlt sich, Ihre Handler so zu gestalten, dass sie idempotent sind. Weitere Informationen finden Sie in diesem Dokument unter Idempotente Event-Handler.

Wiederholungsversuche konfigurieren

Möglicherweise möchten Sie das Standardverhalten bei Wiederholungsversuchen anpassen. Alle Einstellungen für Wiederholungen und Aufbewahrung werden über die Pub/Sub-Abo-Wiederholungsrichtlinie konfiguriert, die Ihrem Eventarc-Trigger zugeordnet ist.

Wenn Sie die Wiederholungsrichtlinie für das Abo ändern möchten, müssen Sie zuerst das Pub/Sub-Abo ermitteln, das mit Ihrem Eventarc-Trigger verknüpft ist. Aktualisieren Sie dann das Abo.

Weitere Informationen zu Abo-Attributen finden Sie unter Abo-Attribute. Informationen zu Abolimits finden Sie unter Pub/Sub-Ressourcenlimits.

Abo identifizieren

So ermitteln Sie das Pub/Sub-Abo, das mit Ihrem Eventarc-Trigger verknüpft ist:

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

Abo aktualisieren

So aktualisieren Sie die Wiederholungsrichtlinie für das Pub/Sub-Abo, das Ihrem Eventarc-Trigger zugeordnet ist:

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

Weitere Überlegungen zu Wiederholungsversuchen

Bei der Verarbeitung von Fehlern oder der Weiterleitung nicht zugestellter Nachrichten sollten Sie die folgenden Aspekte beachten.

Push-Backoffs

Wenn ein Push-Abonnent zu viele negative Bestätigungen sendet, stellt Pub/Sub Nachrichten möglicherweise mit einem Push-Backoff zu. Wenn Pub/Sub einen Push-Backoff verwendet, werden keine Nachrichten mehr für einen bestimmten Zeitraum zugestellt. Dieser Zeitraum kann zwischen 100 Millisekunden und 60 Sekunden liegen. Nach Ablauf der Zeit beginnt Pub/Sub wieder mit der Zustellung von Nachrichten. Weitere Informationen finden Sie unter Push-Backoff.

Themen für unzustellbare Nachrichten

Wenn das Ziel die Nachricht nicht empfängt, können Sie nicht zugestellte Nachrichten an ein Thema für unzustellbare Nachrichten weiterleiten (auch als Dead-Letter-Warteschlange bezeichnet). In einem Thema für unzustellbare Nachrichten können Nachrichten gespeichert werden, die vom Ziel nicht bestätigt werden können. Sie müssen ein Thema für unzustellbare Nachrichten festlegen, wenn Sie ein Pub/Sub-Abo erstellen oder aktualisieren, und nicht, wenn Sie ein Pub/Sub-Thema erstellen oder wenn Eventarc ein Pub/Sub-Thema erstellt. Weitere Informationen finden Sie unter Thema für unzustellbare Nachrichten konfigurieren.

Fehler, die keine Wiederholungen rechtfertigen

Wenn Anwendungen Pub/Sub als Ereignisquelle verwenden und das Ereignis nicht zugestellt wird, wird das Ereignis automatisch wiederholt, außer bei Fehlern, die keine Wiederholungen rechtfertigen. Ereignisse für ein Workflows-Ziel von einer beliebigen Quelle werden nicht wiederholt, wenn der Workflow nicht ausgeführt wird. Beachten Sie, dass Workflows Ereignisse bestätigen, sobald die Workflowausführung beginnt. Wenn die Workflowausführung beginnt, aber später fehlschlägt, werden die Ausführungen nicht wiederholt. Zum Beheben dieser Dienstprobleme sollten Sie Fehler und Wiederholungsversuche innerhalb des Workflows beheben.

Duplizierte Termine

Ereignis-Duplikate werden möglicherweise an Event-Handler gesendet. Gemäß der CloudEvents-Spezifikation wird die Kombination der Attribute source und id als eindeutig angesehen und daher werden alle Ereignisse mit derselben Kombination als Duplikate betrachtet. Sie sollten idempotente Event-Handler als allgemeine Best Practice implementieren.

Idempotente Event-Handler

Event-Handler, für die Wiederholungsversuche gemacht werden können, sollten gemäß den folgenden allgemeinen Richtlinien idempotent sein:

• Bei vielen externen APIs können Sie einen Idempotenzschlüssel als Parameter bereitstellen. Wenn Sie eine solche API verwenden, sollten Sie die Ereignis-ID als Idempotenzschlüssel verwenden.
• Idempotenz funktioniert gut bei mindestens einmaliger Übermittlung, weil Wiederholungsversuche dadurch problemlos erfolgen können. Eine allgemeine Best Practice für das Schreiben von zuverlässigem Code ist also, Idempotenz mit Wiederholungsversuchen zu kombinieren.
• Achten Sie darauf, dass der Code intern idempotent ist. Beispiele:
  • Sorgen Sie dafür, dass Mutationen mehr als einmal passieren können, ohne das Ergebnis zu verändern.
  • Fragen Sie den Datenbankstatus in einer Transaktion ab, bevor der Status mutiert wird.
  • Stellen Sie sicher, dass alle Nebenwirkungen selbst idempotent sind.
• Erzwingen Sie eine Transaktionsprüfung außerhalb des Dienstes und unabhängig vom Code. Beispiel: Zustand an einem Punkt persistent machen, um aufzuzeichnen, dass eine bestimmte Ereignis-ID bereits verarbeitet wurde.
• Nutzen Sie ein Verfahren für doppelte Aufrufe "out of band". Verwenden Sie beispielsweise einen separaten Bereinigungsprozess, der nach doppelten Aufrufen eine Bereinigung durchführt.