Abo-Attribute

Pub/Sub-Abo-Attribute 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 Abonnementeigenschaften beschrieben, die Sie für ein Abo festlegen können.

Hinweise

Allgemeine Abo-Eigenschaften

Wenn Sie ein Abo erstellen, müssen Sie eine Reihe von Optionen angeben, um das Abo einzurichten. Einige dieser Eigenschaften sind für alle Arten von Abos gleich und werden in den nächsten Abschnitten erläutert.

Aufbewahrungsdauer für Nachrichten

Mit der Option Nachrichtenaufbewahrungsdauer wird angegeben, wie lange Pub/Sub Nachrichten nach der Veröffentlichung aufbewahrt. Nach Ablauf der Aufbewahrungsdauer der Nachricht kann Pub/Sub die Nachricht unabhängig vom Bestätigungsstatus verwerfen. Wie Sie bestätigte Nachrichten für die Aufbewahrungsdauer aufbewahren, erfahren Sie unter Nachrichten wiedergeben und verwerfen.

Folgende Werte sind für die Option Aufbewahrungsdauer von Nachrichten verfügbar:

  • Standardwert = 7 Tage
  • Mindestwert = 10 Minuten
  • Der Höchstwert beträgt 31 Tage.

Nicht bestätigte Nachrichten können durch inaktive Abos, Sicherungsanforderungen oder langsame Verarbeitung entstehen. Wenn Sie die Nachrichten innerhalb von 24 Stunden verarbeiten können, fallen keine zusätzlichen Gebühren an. So können Sie neue Gebühren vermeiden:

  • Inaktive Abos: Inaktive Abos löschen, um Gebühren für die Aufbewahrung von Abonnachrichten zu vermeiden.

  • Sicherungsspeicher Wenn Sie die Abo-Aufbewahrung 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 für alle Abos verfügbar, damit sie bei Bedarf abgerufen werden können.

  • 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 eine Aufbewahrungsdauer für Nachrichten angeben, können Sie auch festlegen, ob bestätigte Nachrichten aufbewahrt werden sollen.

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

Ablauffrist

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

Abos ohne Abonnentenaktivität oder Änderungen an den Abo-Attributen laufen ab. Erkennt Pub/Sub Aktivitäten von Abonnenten oder aktualisieren Sie eine der Aboeigenschaften, wird die Zeit bis zum Löschen des Abos wieder zurückgesetzt. Beispiele für Abonnentenaktivitäten sind offene Verbindungen, aktive Pull- oder erfolgreiche Push-Vorgänge.

Wenn Sie den Ablaufzeitraum angeben, muss der Wert mindestens so lang sein wie die Aufbewahrungsdauer für Nachrichten, die in der Option Aufbewahrungsdauer für Nachrichten angegeben ist.

Folgende Werte sind für die Option Ablaufzeitraum möglich:

  • Standardwert = 31 Tage
  • Mindestwert = 1 Tag

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

Bestätigungsfrist

Mit der Option Bestätigungsfrist wird die erste Frist festgelegt, nach der eine unbestätigte Nachricht noch einmal gesendet wird. Sie können die Bestätigungsfrist für jede Nachricht einzeln verlängern, indem Sie nachfolgende ModifyAckDeadline-Anfragen senden.

Folgende Werte sind für die Option Bestätigungsfrist möglich:

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

In einigen Fällen können Pub/Sub-Clientbibliotheken die Zustellungsrate steuern und die Bestätigungsfrist dynamisch ändern. In diesem Fall wird die Nachricht möglicherweise vor der von Ihnen festgelegten Bestätigungsfrist noch einmal zugestellt. Um dieses Verhalten zu überschreiben, verwenden Sie minDurationPerAckExtension und maxDurationPerAckExtension. Weitere Informationen zur Verwendung dieser Werte finden Sie unter Unterstützung für die Exactly-Once-Zustellung in Clientbibliotheken.

Single Message Transforms (SMTs)

SMTs ermöglichen einfache Änderungen an Nachrichtenattributen und Daten direkt in Pub/Sub. Mit dieser Funktion können Daten bereinigt, gefiltert oder in ein anderes Format konvertiert werden, bevor die Nachrichten an einen Abonnentenclient gesendet werden.

Weitere Informationen finden Sie unter SMTs – Übersicht und Abo mit SMTs erstellen.

Abo-Filter

Verwenden Sie die Option Abo-Filter, um einen String mit einem Filterausdruck anzugeben. Wenn ein Abo einen Filter hat, liefert 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.

  • Falls nicht anders angegeben, filtert das Abo die Nachrichten nicht und alle Abonnenten erhalten alle Nachrichten.

  • Filter können nach ihrer Anwendung 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 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 Verwendung 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 Sortierschlüssel senden, damit Pub/Sub die Nachrichten in der richtigen Reihenfolge bereitstellen kann.

Wenn dies nicht festgelegt ist, stellt Pub/Sub Nachrichten möglicherweise nicht in der richtigen Reihenfolge zu, auch wenn sie einen Sortierungsschlüssel haben.

Thema für unzustellbare Nachrichten

Wenn eine Nachricht nach einer festgelegten 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. Die folgenden Werte sind für die maximale Anzahl von Zustellungsversuchen für das Thema für unzustellbare Nachrichten verfügbar:

  • Standardwert = 5 Zustellungsversuche
  • 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 Zustellversuch wird als Wiederholungsrichtlinie für das Abo bezeichnet.

Standardmäßig ist die Wiederholungsrichtlinie für ein Abo auf Sofort wiederholen festgelegt. Bei 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 verspätetem exponentiellem Backoff festlegen. In diesem Fall müssen Sie die maximalen und minimalen Backoff-Werte angeben.

Hier sind einige Richtlinien zum Festlegen der Werte für die maximalen und minimalen Backoff-Werte:

  • Wenn Sie den Höchstwert 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.

Richtlinie für Wiederholungsversuche und Batch-Nachrichten

Wenn sich Nachrichten in einem Batch befinden, startet Pub/Sub den exponentiellen Backoff, wenn eine der folgenden Situationen 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.

Pull-Abo-Attribute abrufen

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

Genau einmalige Zustellung

Genau einmalige Zustellung: Wenn festgelegt, erfüllt Pub/Sub die genau einmalige Zustellung. Falls nicht anders angegeben, unterstützt das Abo die mindestens einmalige Zustellung für jede Nachricht.

Attribute für Push-Abos

Wenn Sie ein Push-Abo konfigurieren, können Sie die folgenden Eigenschaften angeben.

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 wurde. 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.

  • Wenn Abonnenten eine Firewall verwenden, können sie keine Push-Anfragen empfangen. Um Push-Anfragen zu erhalten, müssen Sie die Firewall deaktivieren und das in der Anfrage verwendete JSON Web Token (JWT) prüfen. Wenn ein Abonnent eine Firewall hat, erhalten Sie möglicherweise den Fehler 403 permission denied.

  • Für Pub/Sub ist kein Eigentumsnachweis für Domains für Push-Abos mehr erforderlich. Wenn Ihre Domain unerwartete POST-Anfragen von Pub/Sub erhält, können Sie einen mutmaßlichen Missbrauch melden.

Authentifizierung

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

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

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

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

Voraussetzungen für die Aktivierung der Authentifizierung

Das nutzerverwaltete Dienstkonto ist das Dienstkonto, das dem Push-Abo zugeordnet ist. Dieses Konto wird als email-Anspruch des generierten JSON-Web-Tokens (JWT) verwendet. Hier finden Sie eine Liste der Anforderungen an das Dienstkonto:

  • Dieses nutzerverwaltete 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 vom Nutzer verwaltete Dienstkonto haben, um das Dienstkonto an das Push-Abo anzuhängen. Weitere Informationen finden Sie unter Dienstkonten an Ressourcen anhängen.

  • Erforderliche Berechtigungen: Diesem Dienstkonto muss die Berechtigung iam.serviceAccounts.getOpenIdToken (in der Rolle roles/iam.serviceAccountTokenCreator enthalten) gewährt werden, damit Pub/Sub JWT-Tokens für das angegebene Dienstkonto erstellen kann, um Push-Anfragen zu authentifizieren.

Entpacken der Nutzlast

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

Sie können auch die Option Metadaten schreiben aktivieren. Mit der Option Metadaten schreiben werden zuvor entfernte Nachrichtenmetadaten wieder in den Anfrageheader eingefügt.

BigQuery-Properties

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

Schema des Themas verwenden

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

Wenn Sie diese Option verwenden, müssen Sie die folgenden zusätzlichen Anforderungen erfüllen:

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

  • Alle optionalen Felder im Schema des Themas müssen auch im BigQuery-Schema optional sein.

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

  • Wenn es BigQuery-Felder gibt, die nicht im Themenschema vorhanden sind, müssen diese BigQuery-Felder den Modus NULLABLE haben.

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

  • Sie können nur eine der Abo-Eigenschaften auswählen: Themenschema 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 haben. Pub/Sub schreibt die Nachricht in diese BigQuery-Spalte.

Änderungen am Schema des Pub/Sub-Themas oder der BigQuery-Tabelle werden möglicherweise nicht sofort in Nachrichten übernommen, die 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 auch nach dem Hinzufügen zum BigQuery-Schema nicht. Schließlich werden die Schemas synchronisiert und nachfolgende Nachrichten enthalten das Feld.

Wenn Sie die Option Themenschema verwenden für Ihr BigQuery-Abo verwenden, können Sie auch BigQuery Change Data Capture (CDC) nutzen. CDC aktualisiert Ihre BigQuery-Tabellen durch Verarbeitung und Anwendung von Änderungen auf vorhandene Zeilen.

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 BigQuery Change Data Capture.

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. Wenn Sie diese Option verwenden, müssen Sie die folgenden zusätzlichen Anforderungen erfüllen:

  • Die Namen der einzelnen Spalten in der BigQuery-Tabelle dürfen nur Buchstaben (a–z, A–Z), Ziffern (0–9) und Unterstriche (_) enthalten.

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

  • Die folgenden JSON-Konvertierungen werden unterstützt:

    JSON-Typ BigQuery-Datentyp
    string NUMERIC, BIGNUMERIC, DATE, TIME, DATETIME oder TIMESTAMP
    number NUMERIC, BIGNUMERIC, DATE, TIME, DATETIME oder TIMESTAMP
    • Wenn Sie number für DATE-, DATETIME-, TIME- oder TIMESTAMP-Conversions verwenden, muss die Zahl den unterstützten Darstellungen entsprechen.
    • Bei der Konvertierung von number in NUMERIC oder BIGNUMERIC sind die Genauigkeit und der Wertebereich auf die Werte beschränkt, die vom IEEE 754-Standard für Gleitkommaarithmetik akzeptiert werden. Wenn Sie eine hohe Genauigkeit oder einen größeren Wertebereich benötigen, verwenden Sie stattdessen string- bis NUMERIC- oder BIGNUMERIC-Conversions.
    • Wenn Sie string- in NUMERIC- oder BIGNUMERIC-Conversions verwenden, geht Pub/Sub davon aus, dass der String eine für Menschen lesbare Zahl ist (z.B. "123.124"). Wenn die Verarbeitung des Strings als für Menschen lesbare Zahl fehlschlägt, behandelt Pub/Sub den String als Byte, die mit dem BigDecimalByteStringEncoder codiert wurden.
  • Wenn dem Thema des Abos ein Schema zugeordnet ist, muss die Eigenschaft für die Nachrichtencodierung auf JSON festgelegt werden.

  • Wenn BigQuery-Felder vorhanden sind, die nicht in den Nachrichten enthalten sind, müssen diese BigQuery-Felder den Modus NULLABLE haben.

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

  • Sie können nur eine der Abo-Eigenschaften auswählen: Themenschema 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 haben. Pub/Sub schreibt die Nachricht in diese BigQuery-Spalte.

Änderungen am BigQuery-Tabellenschema werden möglicherweise nicht sofort auf Nachrichten angewendet, die 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 auch nach dem Hinzufügen zum BigQuery-Schema nicht. 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 BigQuery Change Data Capture (CDC) nutzen. CDC aktualisiert Ihre BigQuery-Tabellen durch Verarbeitung und Anwendung von Änderungen auf vorhandene Zeilen.

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 BigQuery Change Data Capture.

Unbekannte Felder löschen

Diese Option wird mit der Option Schema des Themas verwenden oder Schema der Tabelle verwenden verwendet. Wenn diese Option aktiviert ist, kann Pub/Sub alle Felder löschen, die im Schema des Themas oder in der Nachricht, aber nicht im BigQuery-Schema vorhanden sind. Die Felder, die nicht Teil des BigQuery-Schemas sind, werden beim Schreiben der Nachricht in die BigQuery-Tabelle gelöscht.

Wenn Unbekannte Felder löschen nicht festgelegt ist, werden Nachrichten mit zusätzlichen Feldern nicht in BigQuery geschrieben und verbleiben im Rückstand des Abos, sofern Sie kein Thema für unzustellbare Nachrichten konfigurieren.

Die Einstellung Unbekannte Felder verwerfen hat keine Auswirkungen auf Felder, die weder im Pub/Sub-Themaschema noch im BigQuery-Tabellenschema definiert sind. In diesem Fall wird eine gültige Pub/Sub-Nachricht an das Abo gesendet. Da in BigQuery jedoch keine Spalten für diese zusätzlichen Felder definiert sind, werden sie während des BigQuery-Schreibvorgangs verworfen. Um dieses Verhalten zu verhindern, muss jedes Feld, das in der Pub/Sub-Nachricht enthalten ist, auch im BigQuery-Tabellenschema enthalten sein.

Das Verhalten in Bezug auf zusätzliche Felder kann auch vom jeweiligen Schematyp (Avro, Protocol Buffer) und der verwendeten Codierung (JSON, Binär) abhängen. Informationen dazu, wie sich diese Faktoren auf die Verarbeitung zusätzlicher Felder auswirken, finden Sie in der Dokumentation zu Ihrem spezifischen Schematyp und Ihrer spezifischen Codierung.

Metadaten schreiben

Mit dieser Option kann Pub/Sub die Metadaten jeder Nachricht in zusätzliche Spalten in 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, ist für die BigQuery-Tabelle nur das Feld data erforderlich, es sei denn, use_topic_schema ist wahr. Wenn Sie sowohl die Option Metadaten schreiben als auch Themaschema verwenden auswählen, darf das Schema des Themas keine Felder mit Namen enthalten, die mit denen der Metadatenparameter übereinstimmen. Diese Einschränkung gilt auch für CamelCase-Versionen dieser SnakeCase-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 Inhalt der Nachricht.

Das Feld data ist für alle BigQuery-Zieltabelle erforderlich, für die nicht Schema des Themas verwenden oder Tabellenschema verwenden ausgewählt ist. Wenn das Feld vom Typ JSON ist, muss der Nachrichtentext gültiges JSON sein.

attributes

STRING oder JSON

Ein JSON-Objekt mit allen Nachrichtenattributen. Sie enthält auch zusätzliche Felder, die Teil der Pub/Sub-Nachricht sind, einschließlich des Sortierschlüssels, sofern vorhanden.

Cloud Storage-Eigenschaften

Wenn Sie In Cloud Storage schreiben als Abo-Zustellungstyp 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 als 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 Anfragender bezahlt deaktiviert sein.

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

Präfix, Suffix und Datum/Uhrzeit für Dateinamen

Die von der Cloud Storage-Aboversion 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 der Erstellungszeit des Objekts basiert.

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

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

  • Sie können das Dateinamenpräfix und ‑suffix ändern:

    • Wenn der Wert des Dateinamenpräfixes beispielsweise prod_ und der Wert des Dateinamensuffixes _archive ist, lautet ein Beispielobjektname prod_2023-09-25T04:10:00+00:00_uN1QuE_archive.

    • Wenn Sie das Dateinamenpräfix und ‑suffix 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 Cloud Storage-Objekte.

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

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

    • Optionale Matcher, die Sie nur einmal verwenden können: Datums-/Uhrzeit-Trennzeichen (T) und Zeitzonenversatz (Z oder +00:00).

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

    • Wenn der Wert des Datums-/Zeitformats für den Dateinamen beispielsweise YYYY-MM-DD/hh_mm_ssZ ist, lautet ein Beispiel für einen Objektnamen prod_2023-09-25/04_10_00Z_uNiQuE_archive.

    • Wenn das Datums-/Zeitformat des Dateinamens mit einem Zeichen endet, das kein Platzhalter ist, wird dieses Zeichen durch das Trennzeichen zwischen <UTC-date-time> und <uuid> ersetzt. Wenn der Wert des Datums-/Zeitformats für den Dateinamen beispielsweise YYYY-MM-DDThh_mm_ss- ist, lautet ein Beispiel für einen Objektnamen prod_2023-09-25T04_10_00-uNiQuE_archive.

Batchverarbeitung von Dateien

Mit Cloud Storage-Abos können Sie festlegen, wann eine neue Ausgabedatei erstellt werden soll, die als Objekt im Cloud Storage-Bucket gespeichert wird. Pub/Sub schreibt eine Ausgabedatei, wenn eine der angegebenen Batching-Bedingungen erfüllt ist. Die folgenden Bedingungen gelten für das Batching in Cloud Storage:

  • Maximale Storage-Batchdauer Diese Einstellung ist erforderlich. 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 der Standardwert von 5 Minuten angewendet. Die folgenden Werte sind für die maximale Dauer zulässig:

    • Mindestwert = 1 Minute
    • Standardwert = 5 Minuten
    • Maximalwert = 10 Minuten
  • Maximale Storage-Batchbyte: Diese Einstellung ist optional. Das Cloud Storage-Abo schreibt eine neue Ausgabedatei, wenn der angegebene Wert für „max bytes“ überschritten wird. Die folgenden Werte sind für „max_bytes“ zulässig:

    • Mindestwert = 1 KB
    • Maximalwert = 10 GiB
  • Max.Storage-Batchnachrichten: Diese Einstellung ist optional. Das Cloud Storage-Abo schreibt eine neue Ausgabedatei, wenn die angegebene maximale Anzahl von Nachrichten überschritten wird. Die folgenden Werte gelten für die maximale Anzahl von Nachrichten:

    • Mindestwert = 1.000

Sie können beispielsweise eine maximale Dauer von 6 Minuten und eine maximale Größe von 2 GB konfigurieren. Wenn die Ausgabedatei nach 4 Minuten eine Dateigröße von 2 GB erreicht, schließt Pub/Sub die vorherige Datei ab und beginnt, in eine neue Datei zu schreiben.

Bei einem Cloud Storage-Abo können gleichzeitig Daten in mehrere Dateien in einem Cloud Storage-Bucket geschrieben werden. Wenn Sie Ihr Abo so konfiguriert haben, dass alle 6 Minuten eine neue Datei erstellt wird, werden möglicherweise mehrere Cloud Storage-Dateien alle 6 Minuten erstellt.

In einigen Fällen beginnt Pub/Sub möglicherweise früher als durch die Bedingungen für die Dateibatchverarbeitung konfiguriert, in eine neue Datei zu schreiben. Eine Datei kann den Wert „Max. Bytes“ auch überschreiten, wenn das Abo Nachrichten empfängt, die größer als der Wert „Max. Bytes“ 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 Nutzlasten von Nachrichten gespeichert, keine Attribute oder anderen Metadaten.

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

    • Metadaten schreiben: Mit dieser Option können Sie die Metadaten der Nachricht zusammen mit der Nachricht speichern. Metadaten wie die Felder subscription_name, message_id, publish_time und attributes werden in Felder der obersten Ebene im Avro-Ausgabeobjekt geschrieben. Alle anderen Nachrichteneigenschaften außer Daten (z. B. ein „ordering_key“, falls vorhanden) werden als Einträge in die attributes-Map eingefügt.

      Wenn Metadaten schreiben deaktiviert ist, wird nur die Nutzlast der Nachricht in das Avro-Ausgabeobjekt geschrieben. Hier ist das Avro-Schema für die Ausgabenachrichten, wenn Metadaten schreiben deaktiviert ist:

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

      Hier ist das Avro-Schema für die Ausgabenachrichten mit aktivierter Option Metadaten schreiben:

      {
        "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 das Schema des Pub/Sub-Themas verwenden, an das das Abo angehängt ist, wenn Avro-Dateien geschrieben werden.

      Wenn Sie diese Option verwenden, müssen Sie die folgenden zusätzlichen Anforderungen erfüllen:

      • Das Themenschema muss im Apache Avro-Format vorliegen.

      • Wenn sowohl Themenschema verwenden als auch Metadaten schreiben aktiviert sind, muss das Themenschema ein Record-Objekt an der Wurzel haben. Pub/Sub erweitert die Liste der Felder des Datensatzes um die Metadatenfelder. Daher darf der Datensatz keine Felder mit demselben Namen wie die Metadatenfelder (subscription_name, message_id, publish_time oder attributes) enthalten.

Dienstkonto

Sie haben die folgenden Optionen, um Nachrichten in eine BigQuery-Tabelle oder einen Cloud Storage-Bucket zu schreiben:

  • Konfigurieren Sie ein benutzerdefiniertes Dienstkonto, sodass nur Nutzer, die die Berechtigung iam.serviceAccounts.actAs für das Dienstkonto haben, ein Abo erstellen können, das in die Tabelle oder den Bucket schreibt. Ein Beispiel für eine Rolle mit der Berechtigung iam.serviceAccounts.actAs ist die Rolle Dienstkontonutzer (roles/iam.serviceAccountUser).

  • Verwenden Sie den Standard-Pub/Sub-Dienst-Agent, mit dem jeder Nutzer, der Abonnements im Projekt erstellen kann, ein Abo erstellen kann, das in die Tabelle oder den Bucket schreibt. Der Pub/Sub-Dienst-Agent ist die Standardeinstellung, wenn Sie kein benutzerdefiniertes Dienstkonto angeben.

Nächste Schritte