Ein Ereignis kann aus verschiedenen Gründen abgelehnt werden. Der Dienst für den Empfang von Ereignissen ist beispielsweise aufgrund eines Ausfalls möglicherweise vorübergehend nicht verfügbar, beim Verarbeiten eines Ereignisses kann ein Fehler auftreten oder die Dienstressourcen können erschöpft sein. Bei vorübergehenden Fehlern wie diesem kann es sich lohnen, es noch einmal zu versuchen.
Ein Ereignis kann auch nicht an den Ereignisempfänger gesendet werden. Das Ereignis entspricht beispielsweise nicht dem konfigurierten Schema oder die Vermittlung des Ereignisses schlägt fehl, bevor die Ereignisnachricht an ihr endgültiges Ziel weitergeleitet werden kann. In solchen Fällen treten persistente Fehler auf.
Vorübergehende Fehler
Mit Eventarc Advanced können Sie vorübergehende Fehler behandeln. Diese vorübergehenden Fehler können wiederholt werden und umfassen Fehler mit den folgenden Fehlercodes:
HTTP 408 Request Timeout
HTTP 409 Conflict
HTTP 429 Too Many Requests
HTTP 500 Internal Server Error
HTTP 502 Bad Gateway
HTTP 503 Service Unavailable
HTTP 504 Gateway Time-out
Permanente Fehler
Im Gegensatz zu vorübergehenden Fehlern umfassen persistente Fehler Folgendes:
Fehler, die auftreten, wenn die Anzahl der konfigurierten Wiederholungen erschöpft ist
Fehler, die auftreten, wenn ein Ereignis fehlschlägt, bevor es an sein Ziel weitergeleitet werden kann
Fehler, die zu einem Fehlercode führen, der als nicht wiederholbar gilt, z. B. Fehlercodes, die nicht für vorübergehende Fehler aufgeführt sind
Eventarc Advanced verwendet den exponentiellen Backoff mit einer Verzögerung zum Behandeln von Fehlern, für die Wiederholungsversuche möglich sind. Die Standardrichtlinie für Wiederholungsversuche beginnt mit einer Verzögerung von einer Sekunde. Die Verzögerung wird nach jedem fehlgeschlagenen Versuch verdoppelt (bis zu maximal 60 Sekunden und fünf Versuchen).
Sie können die Standardrichtlinie für Wiederholungsversuche über die Google Cloud -Konsole oder den Befehl gcloud eventarc pipelines update ändern.
Der Standard-Backoff-Faktor von 2 kann nicht geändert werden.
Console
Rufen Sie in der Google Cloud Console die Seite Eventarc>Pipelines auf.
Klicken Sie auf der Seite Pipelinedetails auf Bearbeiten.
Ändern Sie auf der Seite Pipeline bearbeiten im Bereich Wiederholungsrichtlinie die folgenden Felder:
Maximale Anzahl an Versuchen: Die Anzahl der Wiederholungsversuche. Der Standardwert ist 5 Versuche. Kann eine beliebige positive reelle Zahl sein. Wenn dieser Wert auf 1 gesetzt ist, wird keine Wiederholungsrichtlinie angewendet. Es wird nur ein Versuch unternommen, die Nachricht zuzustellen.
Min delay (seconds) (Minimale Verzögerung (Sekunden)): Die anfängliche Verzögerung in Sekunden. Der Standardwert ist 1 Sekunde. Muss zwischen 1 und 600 liegen.
Maximale Verzögerung (Sekunden): Die maximale Verzögerung in Sekunden. Der Standardwert ist 60 Sekunden. Muss zwischen 1 und 600 liegen.
Sie können einen linearen Backoff konfigurieren, indem Sie den Mindest- und Höchstwert für die Verzögerung auf denselben Wert festlegen.
PIPELINE_NAME: die ID oder voll qualifizierte Kennzeichnung der Pipeline.
MIN_DELAY: die anfängliche Verzögerung in Sekunden; der Standardwert ist 1 Sekunde. Muss zwischen 1 und 600 liegen.
MAX_DELAY: die maximale Verzögerung in Sekunden; der Standardwert ist 60 Sekunden. Muss zwischen 1 und 600 liegen.
MAX_ATTEMPTS: Die Anzahl der Wiederholungsversuche. Der Standardwert ist 5 Versuche. Kann eine beliebige positive reelle Zahl sein. Wenn dieser Wert auf 1 gesetzt ist, wird keine Wiederholungsrichtlinie angewendet. Es wird nur ein Versuch unternommen, die Nachricht zuzustellen.
Im folgenden Beispiel wird ein linearer Backoff konfiguriert, indem die Mindest- und Höchstverzögerung auf denselben Wert festgelegt werden:
Nachrichten archivieren, um dauerhafte Fehler zu beheben
Sie können Nachrichten beim Empfang in eine BigQuery-Tabelle schreiben. So können Sie dauerhafte Fehler manuell identifizieren und entsprechend reagieren.
Im Folgenden finden Sie eine Übersicht über die Schritte, die erforderlich sind, um Ihre Ereignisnachrichten zu archivieren, wiederkehrende Fehler zu identifizieren und die betroffenen Ereignisse noch einmal zu versuchen.
Erstellen Sie ein BigQuery-Abo für das Pub/Sub-Thema. Ein BigQuery-Abo ist eine Art Exportabo, das Nachrichten beim Empfang in eine vorhandene BigQuery-Tabelle schreibt. Alternativ können Sie die Tabelle beim Erstellen des BigQuery-Abos erstellen.
Erstellen Sie eine Pipeline und Registrierung, die jede Nachricht, die vom Bus empfangen wird (mit --cel-match="true"), an das Pub/Sub-Thema weiterleitet. Konfigurieren Sie eine Wiederholungsrichtlinie für die Pipeline.
Mit den folgenden Befehlen werden beispielsweise eine Pipeline und eine Registrierung erstellt:
Sie sollten jetzt zwei separate BigQuery-Datasets haben: eines, in dem alle Nachrichten gespeichert werden, die von Ihrem Eventarc Advanced-Bus empfangen werden, und eines, in dem Ihre Pipeline-Logs gespeichert werden.
Um fehlgeschlagene Nachrichten zu ermitteln, verwenden Sie eine Abfrageanweisung zum Verknüpfen der beiden BigQuery-Datasets über das Feld message_uid.
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 Ereignisquelle und ‑ID als Idempotenzschlüssel verwenden. (Produzenten müssen dafür sorgen, dass source + id für jedes einzelne Ereignis eindeutig ist.)
Außerdem können Sie das CloudEvents-Attribut xgooglemessageuid verwenden, um Idempotenz zu erreichen. Der Wert dieses Attributs entspricht dem Feld message_uid in Eventarc Advanced-Nachrichten. Sie kennzeichnet die Aktion zum Veröffentlichen eines Ereignisses eindeutig. Wenn beispielsweise dasselbe Ereignis zweimal in einem Bus veröffentlicht wird, hat jedes Ereignis einen anderen xgooglemessageuid-Wert, wenn es an einen Ereignishandler gesendet wird.
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.
[[["Leicht verständlich","easyToUnderstand","thumb-up"],["Mein Problem wurde gelöst","solvedMyProblem","thumb-up"],["Sonstiges","otherUp","thumb-up"]],[["Schwer verständlich","hardToUnderstand","thumb-down"],["Informationen oder Beispielcode falsch","incorrectInformationOrSampleCode","thumb-down"],["Benötigte Informationen/Beispiele nicht gefunden","missingTheInformationSamplesINeed","thumb-down"],["Problem mit der Übersetzung","translationIssue","thumb-down"],["Sonstiges","otherDown","thumb-down"]],["Zuletzt aktualisiert: 2025-08-18 (UTC)."],[[["\u003cp\u003eEventarc Advanced handles transient errors, such as temporary service unavailability, by automatically retrying them using an exponential backoff delay, with default settings of up to 5 attempts and a maximum 60-second delay, starting from a 1-second delay.\u003c/p\u003e\n"],["\u003cp\u003ePersistent errors, including those where retries are exhausted or events fail before routing, require manual identification and handling, and these errors can be found through error codes that are considered non-retryable.\u003c/p\u003e\n"],["\u003cp\u003eUsers can customize the retry policy for transient errors in Eventarc Advanced by adjusting the maximum attempts, minimum delay, and maximum delay through the Google Cloud console or the gcloud command-line tool.\u003c/p\u003e\n"],["\u003cp\u003eTo manage persistent errors, Eventarc Advanced allows for the archiving of event messages to a BigQuery table, where users can then identify and re-publish failed messages using the Eventarc Publishing API.\u003c/p\u003e\n"],["\u003cp\u003eEvent handlers should be designed to be idempotent, ensuring that multiple executions of the same event do not lead to unintended changes, often achievable through the use of idempotency keys or attributes like \u003ccode\u003exgooglemessageuid\u003c/code\u003e.\u003c/p\u003e\n"]]],[],null,["# Retry events\n\n[Advanced](/eventarc/advanced/docs/overview)\n\nAn event can be rejected for multiple reasons. For example, the event receiver\nservice might be temporarily unavailable due to an outage; an error might be\nencountered by the service when processing an event; or service resources\nmight become exhausted. *Transient errors* like this can be retried.\n\nAn event can also fail to be delivered to the event receiver. For example, the\nevent might not match the expected schema that is configured, or the mediation\nof the event might fail before the event message can be routed to its final\ndestination. Such cases result in *persistent errors*.\n\nTransient errors\n----------------\n\nEventarc Advanced provides you with the capability to handle\ntransient errors. These transient errors can be retried and include those with\nthe following error codes:\n\n- HTTP `408 Request Timeout`\n- HTTP `409 Conflict`\n- HTTP `429 Too Many Requests`\n- HTTP `500 Internal Server Error`\n- HTTP `502 Bad Gateway`\n- HTTP `503 Service Unavailable`\n- HTTP `504 Gateway Time-out`\n\nPersistent errors\n-----------------\n\nIn contrast to transient errors, persistent errors include the following:\n\n- Errors that occur when the number of configured retries is exhausted\n- Errors that occur when an event fails before it can be routed to its destination\n- Errors that result in an error code that is considered non-retryable; for example, error codes other than those listed for transient errors\n\nYou can [manually identify persistent errors and handle them](#handle-persistent)\nappropriately.\n\nRetry transient errors\n----------------------\n\nEventarc Advanced uses an exponential backoff delay to handle\nerrors that can be retried. The default retry policy starts with a one-second\ndelay, and the delay is doubled after each failed attempt (up to a maximum of 60\nseconds and five attempts).\n\nYou can change the default retry policy using the Google Cloud console or the\n[`gcloud eventarc pipelines update`](/sdk/gcloud/reference/eventarc/pipelines/update)\ncommand.\n\nNote that the default backoff factor of `2` can't be changed. \n\n### Console\n\n1. In the Google Cloud console, go to the **Eventarc**\n \\\u003e **Pipelines** page.\n\n\n [Go to Pipelines](https://console.cloud.google.com/eventarc/pipelines)\n\n \u003cbr /\u003e\n\n2. Click the name of the pipeline.\n\n3. In the **Pipeline details** page, click **Edit**.\n\n4. On the **Edit pipeline** page, in the **Retry policy** section, modify\n the following fields:\n\n - **Max attempts** : the number of retries; default is `5` attempts. Can be any positive real number. If set to `1`, no retry policy is applied and only one attempt is made to deliver a message.\n - **Min delay (seconds)** : the initial delay in seconds; default is `1` second. Must be between `1` and `600`.\n - **Max delay (seconds)** : the maximum delay in seconds; default is `60` seconds. Must be between `1` and `600`.\n\n You can configure a linear backoff by setting the minimum and maximum\n delays to the same value.\n5. Click **Save**.\n\n### gcloud\n\n gcloud eventarc pipelines update \u003cvar translate=\"no\"\u003ePIPELINE_NAME\u003c/var\u003e \\\n --min-retry-delay=\u003cvar translate=\"no\"\u003eMIN_DELAY\u003c/var\u003e \\\n --max-retry-delay=\u003cvar translate=\"no\"\u003eMAX_DELAY\u003c/var\u003e \\\n --max-retry-attempts=\u003cvar translate=\"no\"\u003eMAX_ATTEMPTS\u003c/var\u003e\n\nReplace the following:\n\n- \u003cvar translate=\"no\"\u003ePIPELINE_NAME\u003c/var\u003e: the ID or fully qualified identifier of the pipeline.\n- \u003cvar translate=\"no\"\u003eMIN_DELAY\u003c/var\u003e: the initial delay in seconds; default is `1` second. Must be between `1` and `600`.\n- \u003cvar translate=\"no\"\u003eMAX_DELAY\u003c/var\u003e: the maximum delay in seconds; default is `60` seconds. Must be between `1` and `600`.\n- \u003cvar translate=\"no\"\u003eMAX_ATTEMPTS\u003c/var\u003e: the number of retries; default is `5` attempts. Can be any positive real number. If set to `1`, no retry policy is applied and only one attempt is made to deliver a message.\n\nThe following example configures a linear backoff by setting the minimum and\nmaximum delays to the same value: \n\n gcloud eventarc pipelines update my-pipeline \\\n --min-retry-delay=4 \\\n --max-retry-delay=4 \\\n --max-retry-attempts=5\n\nArchive messages to handle persistent errors\n--------------------------------------------\n\nYou can write messages to a BigQuery table as they are received. This\nlets you manually identify persistent errors and handle them appropriately.\n\nThe following provides an overview of the steps required to archive your event\nmessages, identify persistent errors, and retry the affected events.\n\n1. [Create a bus](/eventarc/advanced/docs/publish-events/create-bus). Configure the bus appropriately; for example, to [publish events from Google sources](/eventarc/advanced/docs/publish-events/publish-events-google-sources).\n2. [Create a Pub/Sub topic](/pubsub/docs/create-topic). This Pub/Sub topic will be the target destination for your pipeline.\n3. [Create a BigQuery subscription](/pubsub/docs/bigquery) for the Pub/Sub topic. A BigQuery subscription is a type of export subscription that writes messages to an existing BigQuery table as they are received. Alternatively, you can create the table when you create the BigQuery subscription.\n4. [Create a pipeline and enrollment](/eventarc/advanced/docs/receive-events/create-enrollment)\n that routes every message received by the bus (using `--cel-match=\"true\"`) to\n the Pub/Sub topic. Configure a retry policy for the pipeline.\n\n For example, the following commands create a pipeline and an enrollment: \n\n gcloud eventarc pipelines create my-archive-pipeline \\\n --destinations=pubsub_topic='my-archive-topic' \\\n --min-retry-delay=1 \\\n --max-retry-delay=20 \\\n --max-retry-attempts=6 \\\n --location=us-central1\n\n gcloud eventarc enrollments create my-archive-enrollment \\\n --cel-match=\"true\" \\\n --destination-pipeline=my-archive-pipeline \\\n --message-bus=my-message-bus \\\n --message-bus-project=my-google-cloud-project \\\n --location=us-central1\n\n5. [Route your pipeline logs](/logging/docs/export/configure_export_v2) to\n another BigQuery dataset.\n\n You should now have two separate BigQuery datasets: one that\n stores every message received by your Eventarc Advanced bus and one\n that stores your pipeline logs.\n6. To identify messages that have failed, use a\n [query statement to join](/bigquery/docs/reference/standard-sql/query-syntax#join_types)\n both BigQuery datasets on the `message_uid` field.\n\n7. After identifying any failed messages, you can publish them to your bus again\n using the [Eventarc Publishing API](/eventarc/docs/reference/publishing/rest).\n For example, you can\n [deploy a Cloud Run service or job](/run/docs/overview/what-is-cloud-run)\n to read the messages from BigQuery and\n [publish them directly](/eventarc/advanced/docs/publish-events/publish-events-direct-format)\n to the Eventarc Advanced bus.\n\nMake event handlers idempotent\n------------------------------\n\nEvent handlers that can be retried should be idempotent, using the following\ngeneral guidelines:\n\n- Many external APIs let you supply an idempotency key as a parameter. If you are using such an API, you should use the event source and ID as the idempotency key. (Producers must ensure that [source + id](/eventarc/advanced/docs/receive-events/use-cel#attributes) is unique for each distinct event.)\n- Additionally, you can use a CloudEvents attribute, `xgooglemessageuid`, to provide idempotency. The value of this attribute is the same as the `message_uid` field in Eventarc Advanced messages. It uniquely identifies the action of publishing an event. For example, if the same event is published twice to a bus, each event will have a different `xgooglemessageuid` value when sent to an event handler.\n- Idempotency works well with at-least-once delivery, because it makes it safe to retry. So a general best practice for writing reliable code is to combine idempotency with retries.\n- Make sure that your code is internally idempotent. For example:\n - Make sure that mutations can happen more than once without changing the outcome.\n - Query database state in a transaction before mutating the state.\n - Make sure that all side effects are themselves idempotent.\n- Impose a transactional check outside your service, independent of the code. For example, persist state somewhere recording that a given event ID has already been processed.\n- Deal with duplicate calls out-of-band. For example, have a separate clean up process that cleans up after duplicate calls.\n\nWhat's next\n-----------\n\n- [Troubleshoot issues](/eventarc/advanced/docs/troubleshoot)\n- [View audit logs](/eventarc/advanced/docs/audit-logs)"]]
