Abo-Properties

Pub/Sub-Aboattribute sind die Merkmale eines Abos. Sie können beim Erstellen oder Aktualisieren eines Abos Attribute für das Abo festlegen.

In diesem Dokument werden die verschiedenen Aboeigenschaften beschrieben, die Sie für ein Abo festlegen können.

Hinweise

• Weitere Informationen zu Abos

• Machen Sie sich mit dem Workflow für das Abo vertraut, das Sie erstellen möchten: Pull, Push oder BigQuery.

Allgemeine Aboeigenschaften

Wenn Sie ein Abo erstellen, müssen Sie eine Reihe von Optionen zum Einrichten des Abos angeben. Einige dieser Eigenschaften sind bei allen Abotypen gleich und werden in den nächsten Abschnitten erläutert.

Aufbewahrungsdauer für Nachrichten

Die Option Nachrichtenaufbewahrungsdauer gibt an, wie lange Pub/Sub Nachrichten nach der Veröffentlichung aufbewahrt. Nach Ablauf der Nachrichtenaufbewahrungsdauer verwirft Pub/Sub die Nachricht möglicherweise unabhängig vom Bestätigungsstatus der Nachricht. Informationen zum Aufbewahren bestätigter Nachrichten für die Dauer der Nachrichtenaufbewahrungsdauer finden Sie unter Nachrichten wiedergeben und verwerfen.

Im Folgenden finden Sie die Werte für die Option Nachrichtenaufbewahrungsdauer:

• Standardwert = 7 Tage
• Mindestwert = 10 Minuten
• Höchstwert = 7 Tage

Hinweis :Ab dem 30. Juni 2024 fallen Gebühren an, wenn unbestätigte Nachrichten mit Abos länger als 24 Stunden aufbewahrt werden.

Nicht bestätigte Nachrichten können durch inaktive Abos, Sicherungsanforderungen oder eine langsame Verarbeitung verursacht werden. Wenn Sie die Nachrichten innerhalb von 24 Stunden verarbeiten können, fallen keine zusätzlichen Kosten an. Neue Gebühren können Sie vermeiden, indem Sie diese Szenarien so verwalten:

• Inaktive Abos: Löschen Sie inaktive Abos, damit keine Gebühren für die Aufbewahrung von Abonachrichten anfallen.

• Sicherungsspeicher. Wenn Sie die Aboaufbewahrung als Sicherungsspeicher verwenden, können Sie zu einer anderen Speicheroption wechseln, z. B. zur Aufbewahrung von Themennachrichten oder zur Aufbewahrung bestätigter Nachrichten. Bei der Aufbewahrung von Themennachrichten werden Nachrichten nur einmal auf Themenebene gespeichert und bleiben bei Bedarf für alle Abos verfügbar.

• Verarbeitungsverzögerungen. Fügen Sie nach Möglichkeit weitere Abonnenten hinzu, damit die Nachrichten innerhalb eines Tages verarbeitet werden können.

Bestätigte Nachrichten speichern

Wenn Sie die Aufbewahrungsdauer für Nachrichten festlegen, können Sie auch angeben, ob bestätigte Nachrichten aufbewahrt werden sollen.

Mit der Option Bestätigte Nachrichten aufbewahren können Sie bestätigte Nachrichten für die angegebene Nachrichtenaufbewahrungsdauer aufbewahren. Diese Option erhöht die Gebühren für die Speicherung von Nachrichten. Weitere Informationen finden Sie unter Speicherkosten.

Ablauffrist

Mit der Option Ablaufzeitraum können Sie die Ablauffrist Ihres Abos verlängern.

Abos ohne Aktivitäten von Abonnenten oder Änderungen an den Aboeigenschaften laufen ab. Wenn Pub/Sub Abonnentenaktivität erkennt oder Sie eines der Aboattribute aktualisieren, wird die Zeit für das Löschen des Abos neu gestartet. Beispiele für Abonnentenaktivitäten sind offene Verbindungen, aktive Pull- und erfolgreiche Push-Vorgänge.

Wenn Sie eine Ablauffrist festlegen, muss der Wert länger sein als die in der Option Nachrichtenaufbewahrungsdauer angegebene Aufbewahrungsdauer.

Für die Option Ablaufzeitraum gelten folgende Werte:

• Standardwert = 31 Tage
• Mindestwert = 1 Tag

Um zu verhindern, dass ein Abo abläuft, legen Sie die Ablaufzeit auf never expire fest.

Bestätigungsfrist

Die Option Bestätigungsfrist gibt die ursprüngliche Frist an, nach der eine nicht bestätigte Nachricht noch einmal gesendet wird. Sie können die Bestätigungsfrist für einzelne Nachrichten verlängern, indem Sie nachfolgende ModifyAckDeadline-Anfragen senden.

Für die Option Bestätigungsfrist gibt es folgende Werte:

• Standardwert = 10 Sekunden
• Mindestwert = 10 Sekunden
• Höchstwert = 600 Sekunden

In einigen Fällen können Pub/Sub-Clientbibliotheken die Übermittlungsrate steuern und das Bestätigungsfrist dynamisch ändern. Dadurch wird die Nachricht möglicherweise vor der von Ihnen festgelegten Bestätigungsfrist noch einmal gesendet. Verwenden Sie minDurationPerAckExtension und maxDurationPerAckExtension, um dieses Verhalten zu überschreiben. Weitere Informationen zur Verwendung dieser Werte finden Sie unter Unterstützung der genau einmaligen Zustellung in Clientbibliotheken.

Abofilter

Verwenden Sie die Option Abofilter, um einen String mit einem Filterausdruck anzugeben. Wenn ein Abo einen Filter hat, sendet das Abo nur die Nachrichten, die dem Filter entsprechen. Der Pub/Sub-Dienst bestätigt automatisch die Nachrichten, die nicht mit dem Filter übereinstimmen.

• Sie können Nachrichten nach ihren Attributen filtern, aber nicht nach den Daten in der Nachricht.

• Wenn kein Wert angegeben ist, filtert das Abo Nachrichten nicht und Abonnenten erhalten alle Nachrichten.

• Filter können nach dem Anwenden nicht mehr geändert oder entfernt werden.

Wenn Sie Nachrichten aus einem Abo mit einem Filter erhalten, fallen keine Gebühren für ausgehenden Traffic für die von Pub/Sub angegebenen Nachrichten an. Für diese Nachrichten fallen Gebühren für die Nachrichtenzustellung und suchbezogene Speichergebühren an.

Weitere Informationen finden Sie unter Nachrichten aus einem Abo filtern.

Nachrichtenreihenfolge

Wenn für ein Abo die Nachrichtenreihenfolge aktiviert ist, empfangen die Abonnentenclients Nachrichten, die in derselben Region mit demselben Reihenfolgeschlüssel veröffentlicht wurden, in der Reihenfolge, in der die Nachrichten vom Dienst empfangen wurden.

Bei der geordneten Zustellung werden Bestätigungen für spätere Nachrichten erst verarbeitet, wenn Bestätigungen für frühere Nachrichten verarbeitet wurden.

Die Publisher müssen Nachrichten mit einem Reihenfolgeschlüssel senden, damit Pub/Sub die Nachrichten der Reihe nach übermitteln kann.

Wenn die Richtlinie nicht konfiguriert ist, liefert Pub/Sub Nachrichten möglicherweise nicht der Reihe nach, selbst wenn sie einen Reihenfolgeschlüssel haben.

Thema für unzustellbare Nachrichten

Wenn eine Nachricht nach einer bestimmten Anzahl von Zustellversuchen nicht zugestellt werden kann oder ein Abonnent die Nachricht nicht bestätigen kann, können Sie ein Thema für unzustellbare Nachrichten konfigurieren, in dem diese Nachrichten noch einmal veröffentlicht werden können.

Wenn Sie ein Thema für unzustellbare Nachrichten festlegen, können Sie auch die maximale Anzahl der Zustellungsversuche angeben. Im Folgenden finden Sie die Werte für die maximale Anzahl von Zustellungsversuchen für das Thema für unzustellbare Nachrichten:

• Standardwert = 5 Zustellversuche
• Mindestwert = 5 Zustellversuche
• Höchstwert = 100 Zustellversuche

Wenn sich das Thema für unzustellbare Nachrichten in einem anderen Projekt als das Abo befindet, müssen Sie auch die Projekt-ID mit dem Thema für unzustellbare Nachrichten angeben.

Weitere Informationen finden Sie unter An Themen für unzustellbare Nachrichten weiterleiten.

Wiederholungsrichtlinie

Wenn die Bestätigungsfrist abläuft oder ein Abonnent mit einer negativen Bestätigung antwortet, kann Pub/Sub die Nachricht noch einmal senden. Dieser erneute Übermittlungsversuch wird als Wiederholungsrichtlinie des Abos bezeichnet.

Standardmäßig ist die Wiederholungsrichtlinie für ein Abo auf Sofort wiederholen festgelegt. Mit dieser Option sendet Pub/Sub die Nachricht noch einmal, wenn die Bestätigungsfrist abläuft oder ein Abonnent mit einer negativen Bestätigung antwortet.

Sie können den Wert auch auf Wiederholung nach exponentieller Backoff-Verzögerung setzen. In diesem Fall müssen Sie die maximalen und minimalen Backoff-Werte angeben.

Im Folgenden finden Sie einige Richtlinien zum Festlegen der Werte für maximale und minimale Backoff-Werte:

• Wenn Sie den Maximalwert für die Backoff-Dauer festlegen, beträgt der Standardwert für die minimale Backoff-Dauer 10 Sekunden.

• Wenn Sie den Mindestwert für die Backoff-Dauer festlegen, beträgt der Standardwert für die maximale Backoff-Dauer 600 Sekunden.

• Sie können maximal 600 Sekunden festlegen.

Wiederholungsrichtlinie und Batch-Nachrichten

Wenn sich Nachrichten in einem Batch befinden, startet Pub/Sub den exponentiellen Backoff, wenn eines der folgenden Ereignisse eintritt:

• Der Abonnent sendet für jede Nachricht im Batch eine negative Bestätigung.

• Die Bestätigungsfrist läuft ab.

Wiederholungsrichtlinie und Push-Abo

Wenn Sie Nachrichten von einem Push-Abo erhalten, sendet Pub/Sub Nachrichten nach dem Push-Backoff und nicht nach der exponentiellen Backoff-Dauer noch einmal. Wenn der Push-Backoff länger als die exponentielle Backoff-Dauer ist, sendet Pub/Sub nicht bestätigte Nachrichten nach dem Push-Backoff noch einmal.

Hinweis: Wenn Sie die Nachrichtenaufbewahrungsdauer oder die Richtlinie zum Aboablauf ändern, muss die Ablaufzeit auf einen Wert festgelegt werden, der größer als die Nachrichtenaufbewahrungsdauer ist. Die standardmäßige Nachrichtenaufbewahrungsdauer für Nachrichten beträgt 7 Tage und die standardmäßige Ablaufzeit beträgt 31 Tage.

Pull-Aboattribute

Wenn Sie ein Pull-Abo konfigurieren, können Sie die folgenden Attribute angeben.

Genau einmalige Zustellung

Genau einmalige Zustellung. Wenn dies festgelegt ist, erfüllt Pub/Sub die Garantie für eine genau einmalige Zustellung. Wenn keine Angabe gemacht wird, unterstützt das Abo für jede Nachricht die mindestens einmalige Zustellung.

Push-Aboeigenschaften

Wenn Sie ein Push-Abo konfigurieren, können Sie die folgenden Attribute festlegen.

Endpunkte

Endpunkt-URL (erforderlich): Eine öffentlich zugängliche HTTPS-Adresse. Der Server für den Push-Endpunkt muss ein gültiges SSL-Zertifikat haben, das von einer Zertifizierungsstelle signiert ist. Der Pub/Sub-Dienst sendet Nachrichten an Push-Endpunkte aus derselben Google Cloud-Region, in der der Pub/Sub-Dienst die Nachrichten speichert. Der Pub/Sub-Dienst sendet Nachrichten aus derselben Google Cloud-Region auf Best-Effort-Basis.

Pub/Sub erfordert für URL-Domains von Push-Abos keinen Nachweis der Inhaberschaft mehr. Wenn Ihre Domain unerwartete POST-Anfragen von Pub/Sub erhält, können Sie verdächtigen Missbrauch melden.

Authentifizierung

Authentifizierung aktivieren. Wenn diese Option aktiviert ist, enthalten Nachrichten, die von Pub/Sub an den Push-Endpunkt gesendet werden, einen Autorisierungsheader, mit dem der Endpunkt die Anfrage authentifizieren kann. Automatische Authentifizierungs- und Autorisierungsmechanismen sind für App Engine Standard- und Cloud Functions-Endpunkte verfügbar, die im selben Projekt wie das Abo gehostet werden.

Die Authentifizierungskonfiguration für ein authentifiziertes Push-Abo besteht aus einem vom Nutzer verwalteten Dienstkonto und den Zielgruppenparametern, die in einem create-, patch- oder ModifyPushConfig-Aufruf angegeben werden. Sie müssen einem Dienst-Agent auch eine bestimmte Rolle zuweisen, wie im nächsten Abschnitt beschrieben.

• Nutzerverwaltetes Dienstkonto (erforderlich). Das Dienstkonto, das dem Push-Abo zugeordnet ist. Dieses Konto wird als email-Anforderung des generierten JSON-Webtokens (JWT) verwendet. Im Folgenden finden Sie eine Liste der Anforderungen für das Dienstkonto:

  • Dieses Dienstkonto muss sich im selben Projekt wie das Push-Abo befinden.

  • Das Hauptkonto, das das Push-Abo erstellt oder ändert, muss die Berechtigung iam.serviceAccounts.actAs für das Dienstkonto haben. Sie können entweder eine Rolle mit dieser Berechtigung für das Projekt, den Ordner oder die Organisation zuweisen, damit der Aufrufer die Identität mehrerer Dienstkonten übernehmen kann. Alternativ können Sie eine Rolle mit dieser Berechtigung für das Dienstkonto zuweisen, damit der Aufrufer nur die Identität dieses Dienstkontos übernehmen kann.

• Zielgruppe: Ein einzelner String ohne Berücksichtigung der Groß- und Kleinschreibung, mit dem der Webhook die beabsichtigte Zielgruppe dieses bestimmten Tokens validiert.

• Dienst-Agent (erforderlich).

  • Pub/Sub erstellt automatisch ein Dienstkonto im Format service-{PROJECT_NUMBER}@gcp-sa-pubsub.iam.gserviceaccount.com.

  • Diesem Dienst-Agent muss die Berechtigung iam.serviceAccounts.getOpenIdToken (in der Rolle roles/iam.serviceAccountTokenCreator enthalten) gewährt werden, damit Pub/Sub JWT-Tokens für authentifizierte Push-Anfragen erstellen kann.

Entpacken der Nutzlast

Mit der Option Entpacken der Nutzlast aktivieren werden alle Metadaten der Nachrichten mit Ausnahme der Nachrichtendaten aus Pub/Sub-Nachrichten entfernt. Beim Entpacken der Nutzlast werden die Nachrichtendaten direkt als HTTP-Text gesendet.

• Metadaten schreiben Fügt zuvor entfernte Nachrichtenmetadaten wieder in den Anfrageheader ein.

BigQuery-Attribute

Wenn Sie In BigQuery schreiben als Abo-Übermittlungstyp auswählen, können Sie die folgenden zusätzlichen Attribute angeben.

Schema des Themas verwenden

Mit dieser Option kann Pub/Sub das Schema des Pub/Sub-Themas verwenden, mit dem das Abo verknüpft ist. Außerdem schreibt Pub/Sub die Felder in Nachrichten in die entsprechenden Spalten der BigQuery-Tabelle.

Achtung :Das Löschen eines Schemas oder einer Schemaversion kann nicht rückgängig gemacht werden. Nachrichten, die zum Zeitpunkt der Veröffentlichung anhand einer gelöschten Schemaversion validiert wurden, können nicht mit einem BigQuery-Abo in BigQuery geschrieben werden, wenn Schema des Themas verwenden aktiviert ist. Statt ein Schema oder eine Version zu löschen, können Sie auch ein Rollback eines Schemas durchführen.

Beachten Sie bei Verwendung dieser Option die folgenden zusätzlichen Anforderungen:

• Die Felder im Schema des Themas und im BigQuery-Schema müssen dieselben Namen haben und ihre Typen müssen miteinander kompatibel sein.

• Jedes optionale Feld im Schema des Themas muss auch im BigQuery-Schema optional sein.

• Pflichtfelder im Schema des Themas müssen im BigQuery-Schema nicht erforderlich sein.

• Wenn BigQuery-Felder vorhanden sind, die im Schema des Themas nicht vorhanden sind, müssen diese BigQuery-Felder im Modus NULLABLE sein.

• Wenn das Themenschema zusätzliche Felder enthält, die im BigQuery-Schema nicht vorhanden sind, und diese Felder entfernt werden können, wählen Sie die Option Unbekannte Felder löschen aus.

• Sie können nur eine der Aboattribute auswählen: Schema des Themas verwenden oder Tabellenschema verwenden.

Wenn Sie die Option Schema des Themas verwenden oder Tabellenschema verwenden nicht auswählen, muss die BigQuery-Tabelle eine Spalte namens data vom Typ BYTES, STRING oder JSON enthalten. Pub/Sub schreibt die Nachricht in diese BigQuery-Spalte.

Änderungen am Pub/Sub-Themenschema oder BigQuery-Tabellenschema werden möglicherweise nicht sofort wirksam, wenn Nachrichten in die BigQuery-Tabelle geschrieben werden. Wenn beispielsweise die Option Unbekannte Felder löschen aktiviert ist und ein Feld im Pub/Sub-Schema, aber nicht im BigQuery-Schema vorhanden ist, enthalten Nachrichten, die in die BigQuery-Tabelle geschrieben werden, das Feld möglicherweise trotzdem nicht, nachdem es dem BigQuery-Schema hinzugefügt wurde. Schließlich werden die Schemas synchronisiert und nachfolgende Nachrichten enthalten das Feld.

Wenn Sie die Option Schema des Themas verwenden für Ihr BigQuery-Abo verwenden, können Sie auch die Change Data Capture (CDC) von BigQuery nutzen. CDC aktualisiert Ihre BigQuery-Tabellen, indem es Änderungen verarbeitet und auf vorhandene Zeilen anwendet.

Weitere Informationen zu dieser Funktion finden Sie unter Tabellenaktualisierungen mit Change Data Capture streamen.

Informationen zur Verwendung dieses Features mit BigQuery-Abos finden Sie unter Änderungsdatenerfassung in BigQuery.

Schema der Tabelle verwenden

Mit dieser Option kann Pub/Sub das Schema der BigQuery-Tabelle verwenden, um die Felder einer JSON-Nachricht in die entsprechenden Spalten zu schreiben. Beachten Sie bei Verwendung dieser Option die folgenden zusätzlichen Anforderungen:

• Veröffentlichte Nachrichten müssen im JSON-Format vorliegen.

• Wenn dem Thema des Abos ein Schema zugeordnet ist, muss das Attribut für die Nachrichtencodierung auf JSON festgelegt werden.

• Wenn BigQuery-Felder in den Nachrichten nicht vorhanden sind, müssen diese BigQuery-Felder im Modus NULLABLE sein.

• Wenn die Nachrichten zusätzliche Felder enthalten, die im BigQuery-Schema nicht vorhanden sind, und diese Felder gelöscht werden können, wählen Sie die Option Unbekannte Felder löschen aus.

• In der JSON-Nachricht müssen die Werte für DATE, DATETIME, TIME und TIMESTAMP Ganzzahlen sein, die den unterstützten Darstellungen entsprechen.

• In der JSON-Nachricht müssen NUMERIC- und BIGNUMERIC-Werte mit BigDecimalByteStringEncoder in Byte codiert sein.

• Sie können nur eine der Aboattribute auswählen: Schema des Themas verwenden oder Tabellenschema verwenden.

Wenn Sie die Option Schema des Themas verwenden oder Tabellenschema verwenden nicht auswählen, muss die BigQuery-Tabelle eine Spalte namens data vom Typ BYTES, STRING oder JSON enthalten. Pub/Sub schreibt die Nachricht in diese BigQuery-Spalte.

Änderungen am BigQuery-Tabellenschema werden möglicherweise nicht sofort wirksam, wenn Nachrichten in die BigQuery-Tabelle geschrieben werden. Wenn beispielsweise die Option Unbekannte Felder löschen aktiviert ist und ein Feld in den Nachrichten, aber nicht im BigQuery-Schema vorhanden ist, enthalten Nachrichten, die in die BigQuery-Tabelle geschrieben werden, das Feld möglicherweise trotzdem nicht, nachdem es dem BigQuery-Schema hinzugefügt wurde. Schließlich wird das Schema synchronisiert und nachfolgende Nachrichten enthalten das Feld.

Wenn Sie die Option Tabellenschema verwenden für Ihr BigQuery-Abo verwenden, können Sie auch die Change Data Capture (CDC) von BigQuery nutzen. CDC aktualisiert Ihre BigQuery-Tabellen, indem es Änderungen verarbeitet und auf vorhandene Zeilen anwendet.

Weitere Informationen zu dieser Funktion finden Sie unter Tabellenaktualisierungen mit Change Data Capture streamen.

Informationen zur Verwendung dieser Funktion mit BigQuery-Abos finden Sie unter Änderungsdatenerfassung in BigQuery.

Unbekannte Felder löschen

Diese Option wird mit der Option Schema des Themas verwenden oder Tabellenschema verwenden verwendet. Mit dieser Option kann Pub/Sub jedes Feld löschen, das im Schema oder in der Nachricht des Themas, aber nicht im BigQuery-Schema vorhanden ist. Wenn Unbekannte Felder löschen festgelegt ist, werden Nachrichten mit zusätzlichen Feldern nicht in BigQuery geschrieben und verbleiben im Rückstand des Abos. Das Abo hat dann einen Fehlerstatus.

Metadaten schreiben

Mit dieser Option kann Pub/Sub die Metadaten jeder Nachricht in zusätzliche Spalten der BigQuery-Tabelle schreiben. Andernfalls werden die Metadaten nicht in die BigQuery-Tabelle geschrieben.

Wenn Sie die Option Metadaten schreiben auswählen, muss die BigQuery-Tabelle die in der folgenden Tabelle beschriebenen Felder enthalten.

Wenn Sie die Option Metadaten schreiben nicht auswählen, benötigt die BigQuery-Tabelle nur das Feld data, sofern nicht use_topic_schema auf „true“ gesetzt ist. Wenn Sie sowohl die Option Metadaten schreiben als auch die Option Schema des Themas verwenden auswählen, darf das Schema des Themas keine Felder mit Namen enthalten, die mit den Namen der Metadatenparameter übereinstimmen. Diese Einschränkung gilt auch für Camelcase-Versionen dieser Snake-Case-Parameter.

Parameter
subscription_name	STRING Name eines Abos.
message_id	STRING ID einer Nachricht
publish_time	TIMESTAMP Der Zeitpunkt der Veröffentlichung einer Nachricht.
data	BYTES, STRING oder JSON Der Nachrichtentext. Das Feld data ist für alle BigQuery-Zieltabellen erforderlich, für die nicht Themenschema verwenden oder Tabellenschema verwenden ausgewählt ist. Wenn das Feld vom Typ JSON ist, muss der Nachrichtentext ein gültiges JSON-Format haben.
attributes	STRING oder JSON Ein JSON-Objekt, das alle Nachrichtenattribute enthält. Außerdem enthält er zusätzliche Felder, die Teil der Pub/Sub-Nachricht sind, einschließlich des Reihenfolgeschlüssels, falls vorhanden.

Cloud Storage-Attribute

Wenn Sie einen Abo-Übermittlungstyp als In Cloud Storage schreiben auswählen, können Sie die folgenden zusätzlichen Attribute angeben.

Bucket-Name

Ein Cloud Storage-Bucket muss bereits vorhanden sein, bevor Sie ein Cloud Storage-Abo erstellen.

Die Nachrichten werden in Batches gesendet und im Cloud Storage-Bucket gespeichert. Ein einzelner Batch oder eine einzelne Datei wird als Objekt im Bucket gespeichert.

Für den Cloud Storage-Bucket muss Anforderer bezahlt deaktiviert sein.

Informationen zum Erstellen eines Cloud Storage-Bucket finden Sie unter Buckets erstellen.

Präfix des Dateinamens, Suffix und Datum/Uhrzeit

Die im Rahmen des Cloud Storage-Abos generierten Cloud Storage-Ausgabedateien werden als Objekte im Cloud Storage-Bucket gespeichert. Der Name des im Cloud Storage-Bucket gespeicherten Objekts hat das folgende Format: <file-prefix><UTC-date-time>_<uuid><file-suffix>.

Die folgende Liste enthält Details zum Dateiformat und zu den Feldern, die Sie anpassen können:

• <file-prefix> ist das benutzerdefinierte Dateinamenpräfix. Dieses Feld ist optional.

• <UTC-date-time> ist ein anpassbarer, automatisch generierter String, der auf dem Zeitpunkt der Objekterstellung basiert.

• <uuid> ist ein automatisch generierter zufälliger String für das Objekt.

• <file-suffix> ist das benutzerdefinierte Suffix des Dateinamens. Dieses Feld ist optional. Das Suffix des Dateinamens darf nicht mit „/“ enden.

• Sie können das Präfix und Suffix des Dateinamens ändern:

  • Wenn der Wert des Dateinamenspräfixes beispielsweise prod_ und der Wert des Dateinamensuffixes _archive ist, ist der Name des Beispielobjekts prod_2023-09-25T04:10:00+00:00_uN1QuE_archive.

  • Wenn Sie das Präfix und Suffix des Dateinamens nicht angeben, hat der im Cloud Storage-Bucket gespeicherte Objektname das folgende Format: <UTC-date-time>_<uuid>.

  • Die Anforderungen für die Benennung von Cloud Storage-Objekten gelten auch für das Präfix und Suffix des Dateinamens. Weitere Informationen finden Sie unter Informationen zu Cloud Storage-Objekten.

• Sie können ändern, wie Datum und Uhrzeit im Dateinamen angezeigt werden:

  • Erforderliche Datetime-Matcher, die Sie nur einmal verwenden können: Jahr (YYYY oder YY), Monat (MM), Tag (DD), Stunde (hh), Minute (mm), Sekunde (ss). Beispiel: YY-YYYY oder MMM ist ungültig.

  • Optionale Matcher, die Sie nur einmal verwenden können: Trennzeichen für Datum und Uhrzeit (T) und Zeitzonenversatz (Z oder +00:00).

  • Optionale Elemente, die Sie mehrmals verwenden können: Bindestrich (-), Unterstriche (_), Doppelpunkt (:) und Schrägstrich (/).

  • Wenn der Wert des Datetime-Formats des Dateinamens beispielsweise YYYY-MM-DD/hh_mm_ssZ ist, ist ein Beispielobjektname prod_2023-09-25/04_10_00Z_uNiQuE_archive.

  • Wenn das Datetime-Format des Dateinamens mit einem Zeichen endet, das kein Matcher ist, ersetzt dieses Zeichen das Trennzeichen zwischen <UTC-date-time> und <uuid>. Wenn der Wert des Datetime-Formats des Dateinamens beispielsweise YYYY-MM-DDThh_mm_ss- ist, ist ein Beispielobjektname prod_2023-09-25T04_10_00-uNiQuE_archive.

Batchverarbeitung von Dateien

Mit Cloud Storage-Abos können Sie entscheiden, wann Sie eine neue Ausgabedatei erstellen möchten, die als Objekt im Cloud Storage-Bucket gespeichert wird. Pub/Sub schreibt eine Ausgabedatei, wenn eine der angegebenen Batchbedingungen erfüllt ist. Im Folgenden sind die Bedingungen für die Batchverarbeitung von Cloud Storage aufgeführt:

• Maximale Dauer von Storage-Batch. Dies ist eine erforderliche Einstellung. Das Cloud Storage-Abo schreibt eine neue Ausgabedatei, wenn der angegebene Wert für die maximale Dauer überschritten wird. Wenn Sie den Wert nicht angeben, wird ein Standardwert von 5 Minuten angewendet. Folgende Werte sind für die maximale Dauer zulässig:

  • Mindestwert = 1 Minute
  • Standardwert = 5 Minuten
  • Höchstwert = 10 Minuten

• Maximale Anzahl von Storage-Batchbyte. Diese Einstellung ist optional. Das Cloud Storage-Abo schreibt eine neue Ausgabedatei, wenn der angegebene Wert von max. Byte überschritten wird. Folgende Werte sind für die maximale Bytezahl zulässig:

  • Mindestwert = 1 KB
  • Maximalwert = 10 GiB

Beispielsweise können Sie die maximale Dauer mit 6 Minuten und die maximale Anzahl von Byte mit 2 GB konfigurieren. Wenn die Ausgabedatei in der 4. Minute eine Dateigröße von 2 GB erreicht, finalisiert Pub/Sub die vorherige Datei und beginnt, in eine neue Datei zu schreiben.

Ein Cloud Storage-Abo kann in mehrere Dateien in einem Cloud Storage-Bucket gleichzeitig schreiben. Wenn Sie Ihr Abo so konfiguriert haben, dass jede 6. Minute eine neue Datei erstellt wird, werden möglicherweise alle 6 Minuten mehrere Cloud Storage-Dateien erstellt.

In einigen Situationen beginnt Pub/Sub möglicherweise schon vor dem in den Batchbedingungen der Datei konfigurierten Zeitraum mit dem Schreiben in eine neue Datei. Eine Datei kann auch den Wert für die maximale Anzahl von Byte überschreiten, wenn das Abo Nachrichten empfängt, die größer als der Wert für die maximale Anzahl von Byte sind.

Dateiformat

Wenn Sie ein Cloud Storage-Abo erstellen, können Sie das Format der Ausgabedateien, die in einem Cloud Storage-Bucket gespeichert werden sollen, als Text oder Avro angeben.

• Text: Die Nachrichten werden als Nur-Text gespeichert. Ein Zeilenumbruchzeichen trennt eine Nachricht von der vorherigen Nachricht in der Datei. Es werden nur Nachrichtennutzlasten gespeichert, keine Attribute oder anderen Metadaten.

• Avro: Die Nachrichten werden im Apache Avro-Binärformat gespeichert. Wenn Sie Avro auswählen, können Sie die folgenden zusätzlichen Eigenschaften aktivieren:

  • Write metadata (Metadaten schreiben): Mit dieser Option können Sie die Metadaten der Nachricht zusammen mit der Nachricht speichern. Metadaten wie subscription_name, message_id, publish_time und attributes werden in Felder der obersten Ebene im Avro-Ausgabeobjekt geschrieben, während alle anderen Nachrichtenattribute mit Ausnahme von Daten (z. B. ein order_key, falls vorhanden) als Einträge in die attributes-Zuordnung hinzugefügt werden.

    Wenn Metadaten schreiben deaktiviert ist, wird nur die Nachrichtennutzlast in das Avro-Ausgabeobjekt geschrieben. Hier ist das Avro-Schema für die Ausgabemeldungen mit deaktiviertem Schreibmetadaten:

    {
      "type": "record",
      "namespace": "com.google.pubsub",
      "name": "PubsubMessage",
      "fields": [
        { "name": "data", "type": "bytes" }
      ]
    }
    

    Hier ist das Avro-Schema für die Ausgabemeldungen mit aktiviertem Schreibmetadaten:

    {
      "type": "record",
      "namespace": "com.google.pubsub",
      "name": "PubsubMessageWithMetadata",
      "fields": [
        { "name": "subscription_name", "type": "string" },
        { "name": "message_id", "type": "string"  },
        { "name": "publish_time", "type": {
            "type": "long",
            "logicalType": "timestamp-micros"
          }
        },
        { "name": "attributes", "type": { "type": "map", "values": "string" } },
        { "name": "data", "type": "bytes" }
      ]
    }
    

  • Schema des Themas verwenden: Mit dieser Option kann Pub/Sub beim Schreiben von Avro-Dateien das Schema des Pub/Sub-Themas verwenden, an das das Abo angehängt ist.

    Beachten Sie bei Verwendung dieser Option die folgenden zusätzlichen Anforderungen:

    • Das Schema des Themas muss im Apache Avro-Format vorliegen.

    • Wenn sowohl Themaschema verwenden als auch Metadaten schreiben aktiviert sind, muss das Schema des Themas im Stammverzeichnis ein Record-Objekt haben. Pub/Sub erweitert die Felderliste des Eintrags um die Metadatenfelder. Der Datensatz darf daher keine Felder mit demselben Namen wie die Metadatenfelder (subscription_name, message_id, publish_time oder attributes) enthalten.

Nächste Schritte

• Erstellen Sie ein Pull-Abo.
• Erstellen Sie ein Push-Abo.
• Erstellen Sie ein BigQuery-Abo.
• Erstellen Sie ein Cloud Storage-Abo.