In diesem Dokument wird beschrieben, wie Sie ein Cloud Storage-Abo erstellen. Sie können die Google Cloud Console, die Google Cloud CLI, die Clientbibliothek oder die Pub/Sub API verwenden, um ein Cloud Storage-Abo zu erstellen.
Hinweise
Machen Sie sich vor dem Lesen dieses Dokuments mit Folgendem vertraut:
- Funktionsweise von Cloud Storage-Abos
- Funktionsweise von Cloud Storage und Erstellen und Verwalten von Cloud Storage-Buckets
- Thema für unzustellbare Nachrichten konfigurieren, um Nachrichtenfehler zu verarbeiten
Erforderliche Rollen und Berechtigungen
Im Folgenden finden Sie eine Liste mit Richtlinien in Bezug auf Rollen und Berechtigungen:
Zum Erstellen eines Abos müssen Sie die Zugriffssteuerung auf Projektebene konfigurieren.
Außerdem benötigen Sie Berechtigungen auf Ressourcenebene, wenn sich Ihre Abos und Themen in verschiedenen Projekten befinden. Dies wird weiter unten in diesem Abschnitt erläutert.
Zum Erstellen eines Cloud Storage-Abos muss das Pub/Sub-Dienstkonto die Berechtigung zum Schreiben in den entsprechenden Cloud Storage-Bucket und zum Lesen der Bucket-Metadaten haben. Weitere Informationen zum Gewähren dieser Berechtigungen finden Sie im nächsten Abschnitt dieses Dokuments.
Bitten Sie Ihren Administrator, Ihnen die IAM-Rolle Pub/Sub Editor (roles/pubsub.editor
) für das Projekt zu gewähren, damit Sie die Berechtigungen erhalten, die Sie zum Erstellen von Cloud Storage-Abos benötigen.
Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff verwalten.
Diese vordefinierte Rolle enthält die Berechtigungen, die zum Erstellen von Cloud Storage-Abos erforderlich sind. Erweitern Sie den Abschnitt Erforderliche Berechtigungen, um die erforderlichen Berechtigungen anzuzeigen:
Erforderliche Berechtigungen
Die folgenden Berechtigungen sind erforderlich, um Cloud Storage-Abos zu erstellen:
-
Abo erstellen:
pubsub.subscriptions.create
-
Verknüpfen Sie ein Abo mit einem Thema:
pubsub.topics.attachSubscription
-
Aus einem Abo abrufen:
pubsub.subscriptions.consume
-
Abo abschließen:
pubsub.subscriptions.get
-
Abo auflisten:
pubsub.subscriptions.list
-
Abo aktualisieren:
pubsub.subscriptions.update
-
Abo löschen:
pubsub.subscriptions.delete
-
IAM-Richtlinie für ein Abo abrufen:
pubsub.subscriptions.getIamPolicy
-
Konfigurieren Sie die IAM-Richtlinie für ein Abo:
pubsub.subscriptions.setIamPolicy
Möglicherweise können Sie diese Berechtigungen auch mit benutzerdefinierten Rollen oder anderen vordefinierten Rollen erhalten.
Wenn Sie in einem Projekt Cloud Storage-Abos erstellen müssen, die mit einem Thema in einem anderen Projekt verknüpft sind, bitten Sie Ihren Themenadministrator, Ihnen auch die IAM-Rolle (roles/pubsub.editor)
des Pub/Sub-Editors für dieses Thema zu gewähren.
Cloud Storage-Rollen dem Pub/Sub-Dienstkonto zuweisen
Einige Google Cloud-Dienste haben von Google Cloud verwaltete Dienstkonten, über die die Dienste auf Ihre Ressourcen zugreifen können. Diese Dienstkonten werden als Dienst-Agents bezeichnet. Pub/Sub erstellt und verwaltet für jedes Projekt ein Dienstkonto im Format service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com
.
Zum Erstellen eines Cloud Storage-Abos muss das Pub/Sub-Dienstkonto die Berechtigung zum Schreiben in den jeweiligen Cloud Storage-Bucket und zum Lesen der Bucket-Metadaten haben. Wählen Sie eines der folgenden Verfahren aus:
Berechtigungen auf Bucket-Ebene gewähren Weisen Sie dem Pub/Sub-Dienstkonto im jeweiligen Cloud Storage-Bucket die Rollen Storage Object Creator (
roles/storage.objectCreator
) und Storage Legacy Bucket Reader (roles/storage.legacyBucketReader
) zu.Wenn Sie Rollen auf Projektebene zuweisen müssen, können Sie stattdessen die Rolle „Storage-Administrator“ (
roles/storage.admin
) für das Projekt zuweisen, das den Cloud Storage-Bucket enthält. Weisen Sie dem Pub/Sub-Dienstkonto diese Rolle zu.
Bucket-Berechtigungen
Führen Sie die folgenden Schritte aus, um die Rollen „Storage Object Creator“ (roles/storage.objectCreator
) und „Storage Legacy Bucket Reader“ (roles/storage.legacyBucketReader
) auf Bucket-Ebene zu gewähren:
Wechseln Sie in der Google Cloud Console zur Seite Cloud Storage.
Klicken Sie auf den Cloud Storage-Bucket, in den Sie Nachrichten schreiben möchten.
Die Seite Bucket-Details wird geöffnet.
Klicken Sie auf der Seite mit den Bucket-Details auf den Tab Berechtigungen.
Klicken Sie auf dem Tab Berechtigungen > Nach Hauptkonten ansehen auf Zugriff gewähren.
Die Seite Zugriff gewähren wird geöffnet.
Geben Sie im Abschnitt Hauptkonten hinzufügen den Namen Ihres Pub/Sub-Dienstkontos ein.
Das Format des Dienstkontos ist
service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com
. Bei einem Projekt mit PROJECT_NUMBER=112233445566
hat das Dienstkonto beispielsweise das Formatservice-112233445566@gcp-sa-pubsub.iam.gserviceaccount.com
.Geben Sie im Drop-down-Menü Rollen zuweisen > Rolle auswählen den Wert
Creator
ein und wählen Sie die Rolle Storage-Objekt-Ersteller aus.Klicken Sie auf Weitere Rolle hinzufügen.
Geben Sie im Drop-down-Menü Rolle auswählen den Wert
Bucket Reader
ein und wählen Sie die Rolle Leser alter Storage-Buckets aus.Klicken Sie auf Speichern.
Projektberechtigungen
Führen Sie die folgenden Schritte aus, um die Rolle „Storage-Administrator“ (roles/storage.admin
) auf Projektebene zu gewähren:
Öffnen Sie in der Google Cloud Console die Seite IAM.
Klicken Sie auf dem Tab Berechtigungen > Nach Hauptkonten ansehen auf Zugriff gewähren.
Die Seite Zugriff gewähren wird geöffnet.
Geben Sie im Abschnitt Hauptkonten hinzufügen den Namen Ihres Pub/Sub-Dienstkontos ein.
Das Format des Dienstkontos ist
service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com
. Bei einem Projekt mit PROJECT_NUMBER=112233445566
hat das Dienstkonto beispielsweise das Formatservice-112233445566@gcp-sa-pubsub.iam.gserviceaccount.com
.Geben Sie im Drop-down-Menü Rollen zuweisen > Rolle auswählen den Wert
Storage Admin
ein und wählen Sie die Rolle Storage-Administrator aus.Klicken Sie auf Speichern.
Weitere Informationen zu Cloud Storage-IAM finden Sie unter Cloud Storage-Identitäts- und Zugriffsverwaltung.
Attribute von Cloud Storage-Abos
Wenn Sie ein Cloud Storage-Abo konfigurieren, müssen Sie die allgemeinen Attribute aller Abotypen sowie einige zusätzliche abospezifische Attribute von Cloud Storage angeben.
Häufige Aboeigenschaften
Hier erfährst du mehr über die allgemeinen Aboattribute, die du für alle Abos festlegen kannst.
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 Anforderer bezahlt deaktiviert sein.
Informationen zum Erstellen eines Cloud Storage-Bucket finden Sie unter Buckets erstellen.
Präfix für Dateinamen, Suffix und Datum/Uhrzeit
Die vom Cloud Storage-Abo 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 anpassbaren Feldern:
<file-prefix>
ist das benutzerdefinierte Präfix des Dateinamens. Dieses Feld ist optional.<UTC-date-time>
ist ein anpassbarer, automatisch generierter String, der auf dem Erstellungsdatum des Objekts 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 Dateinamenpräfixes beispielsweise
prod_
und der Wert des Suffixes des Dateinamens_archive
lautet, ist ein Beispielobjektnameprod_2023-09-25T04:10:00+00:00_uN1QuE_archive
.Wenn Sie kein Präfix und Suffix des Dateinamens 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 Präfixe und Suffixe von Dateinamen. Weitere Informationen finden Sie unter Informationen zu Cloud Storage-Objekten.
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
oderYY
), Monat (MM
), Tag (DD
), Stunde (hh
), Minute (mm
), Sekunde (ss
). Beispielsweise istYY-YYYY
oderMMM
ungültig.Optionale Abgleicher, die Sie nur einmal verwenden können: Datum/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-/Uhrzeitformats beispielsweise
YYYY-MM-DD/hh_mm_ssZ
ist, lautet der Name eines Beispielobjektsprod_2023-09-25/04_10_00Z_uNiQuE_archive
.Wenn das Datum/Uhrzeit-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 Datums-/Uhrzeitformats beispielsweiseYYYY-MM-DDThh_mm_ss-
ist, lautet der Name eines Beispielobjektsprod_2023-09-25T04_10_00-uNiQuE_archive
.
Batch-Verarbeitung 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. Für die Batchverarbeitung von Cloud Storage gelten folgende Bedingungen:
Maximale Speicher-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 keinen Wert angeben, wird ein Standardwert von 5 Minuten angewendet. Die folgenden Werte sind für die maximale Dauer gültig:
- Mindestwert = 1 Minute
- Standardwert = 5 Minuten
- Maximalwert = 10 Minuten
Max. Storage-Batchbyte. Diese Einstellung ist optional. Das Cloud Storage-Abo schreibt eine neue Ausgabedatei, wenn der angegebene Wert für die maximale Bytezahl überschritten wird. Im Folgenden sind die gültigen Werte für die maximale Anzahl von Byte aufgeführt:
- Mindestwert = 1 KB
- Maximalwert = 10 GiB
Beispielsweise können Sie die maximale Dauer mit 6 Minuten und die maximalen Byte mit 2 GB konfigurieren. Wenn die Ausgabedatei in der vierten Minute eine Dateigröße von 2 GB erreicht, schließt Pub/Sub die vorherige Datei ab und beginnt mit dem Schreiben in eine neue Datei.
Ein Cloud Storage-Abo kann gleichzeitig in mehrere Dateien in einem Cloud Storage-Bucket schreiben. Wenn Sie Ihr Abo so konfiguriert haben, dass alle sechs Minuten eine neue Datei erstellt wird, werden möglicherweise mehrere Cloud Storage-Dateien alle sechs Minuten erstellt.
Es kann vorkommen, dass Pub/Sub schon früher in eine neue Datei schreibt als in den Bedingungen für die Datei-Batchverarbeitung. Eine Datei kann auch den Wert für „Max. Byte“ überschreiten, wenn das Abo Nachrichten empfängt, die größer als der Wert „Max. 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 im Nur-Text-Format gespeichert. Durch ein Zeilenumbruchzeichen wird eine Nachricht von der vorherigen Nachricht in der Datei getrennt. Es werden nur Nachrichtennutzlasten gespeichert, keine Attribute oder andere Metadaten.
Avro: Die Nachrichten werden im Apache Avro-Binärformat gespeichert.
Wenn Sie Avro auswählen, können Sie zusätzlich die Option Metadaten schreiben aktivieren. Mit dieser Option können Sie die Metadaten der Nachricht zusammen mit der Nachricht speichern.
Metadaten wie
subscription_name
,message_id
,publish_time
und Attributfelder werden in Felder der obersten Ebene im Avro-Ausgabeobjekt geschrieben, während alle anderen Nachrichtenattribute mit Ausnahme von Daten (z. B. ein Sortierungsschlüssel, falls vorhanden) als Einträge der Attributzuordnung hinzugefügt werden.Wenn Write metadata (Metadaten schreiben) deaktiviert ist, wird nur die Nachrichtennutzlast in das Avro-Ausgabeobjekt geschrieben.
Hier ist das Avro-Schema für die Ausgabenachrichten, für das Metadaten schreiben nicht aktiviert ist:
{ "type": "record", "namespace": "com.google.pubsub", "name": "PubsubMessage", "fields": [ { "name": "data", "type": "bytes" } ] }
Hier ist das Avro-Schema für die Ausgabenachrichten, für die Metadaten schreiben aktiviert ist:
{ "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" } ] }
Cloud Storage-Abo erstellen
Console
-
Rufen Sie in der Google Cloud Console die Seite Abos auf.
-
Klicken Sie auf Abo erstellen.
-
Geben Sie im Feld Abo-ID einen Namen ein.
Informationen zum Benennen eines Abos findest du unter Richtlinien zum Benennen von Themen oder Abos.
-
Wählen Sie im Drop-down-Menü ein Thema aus oder erstellen Sie ein Thema.
Das Abo erhält Nachrichten aus dem Thema.
Informationen zum Erstellen eines Themas finden Sie unter Themen erstellen und verwalten.
-
Wählen Sie für Zustellungstyp die Option In Cloud Storage schreiben aus.
-
Klicken Sie neben dem Cloud Storage-Bucket auf Durchsuchen.
-
Sie können einen vorhandenen Bucket aus einem geeigneten Projekt auswählen.
-
Sie können auch auf das Symbol „Erstellen“ klicken und der Anleitung auf dem Bildschirm folgen, um einen neuen Bucket zu erstellen.
Wählen Sie den Bucket für das Cloud Storage-Abo aus, nachdem Sie ihn erstellt haben.
Weitere Informationen zum Erstellen eines Buckets finden Sie unter Buckets erstellen.
Wenn Sie den Bucket angeben, sucht Pub/Sub im Bucket nach den entsprechenden Berechtigungen für das Pub/Sub-Dienstkonto. Wenn es Berechtigungsprobleme gibt, wird eine Meldung wie die folgende angezeigt:
Unable to verify if the Pub/Sub service agent has write permissions on this bucket. You may be lacking permissions to view or set permissions
. -
-
Wenn Berechtigungsprobleme auftreten, klicken Sie auf Berechtigung festlegen und folgen Sie der Anleitung auf dem Bildschirm.
Alternativ können Sie der Anleitung unter Dem Pub/Sub-Dienstkonto Cloud Storage-Rollen zuweisen folgen.
-
Wählen Sie als Dateiformat die Option Text oder Avro aus.
Wenn Sie Avro auswählen, können Sie auch angeben, ob die Metadaten der Nachrichten in der Ausgabe gespeichert werden sollen.
Weitere Informationen zu den beiden Optionen, einschließlich der Option für Nachrichtenmetadaten für das Avro-Format, finden Sie unter Dateiformat.
-
Optional: Sie können das Präfix und Suffix des Dateinamens für alle Dateien angeben, die in den Cloud Storage-Bucket geschrieben werden sollen. Eine Datei wird als Objekt im Bucket gespeichert.
Weitere Informationen zum Festlegen des Dateipräfix und Dateisuffixes finden Sie unter Dateipräfix und ‐suffix.
-
Geben Sie unter Datei-Batching eine maximale Zeitspanne an, bevor eine neue Datei erstellt wird.
Sie können auch die maximale Dateigröße für die Dateien festlegen.
Weitere Informationen zu den beiden Optionen für die Datei-Batchverarbeitung finden Sie unter Datei-Batching.
-
Wir empfehlen dringend, für den Umgang mit Nachrichtenfehlern die Option Unzustellbare Nachrichten zu aktivieren.
Weitere Informationen finden Sie unter Unzustellbare Nachrichten.
-
Sie können die anderen Einstellungen als Standardeinstellungen beibehalten und auf Erstellen klicken.
gcloud
-
Aktivieren Sie Cloud Shell in der Google Cloud Console.
Unten in der Google Cloud Console wird eine Cloud Shell-Sitzung gestartet und eine Eingabeaufforderung angezeigt. Cloud Shell ist eine Shell-Umgebung, in der das Google Cloud CLI bereits installiert ist und Werte für Ihr aktuelles Projekt bereits festgelegt sind. Das Initialisieren der Sitzung kann einige Sekunden dauern.
- Führen Sie den Befehl
gcloud pubsub subscriptions create
aus, um ein Cloud Storage-Abo zu erstellen.gcloud pubsub subscriptions create SUBSCRIPTION_ID \ --topic=TOPIC_ID \ --cloud-storage-bucket=BUCKET_NAME \ --cloud-storage-file-prefix=CLOUD_STORAGE_FILE_PREFIX \ --cloud-storage-file-suffix=CLOUD_STORAGE_FILE_SUFFIX \ --cloud-storage-max-bytes=CLOUD_STORAGE_MAX_BYTES \ --cloud-storage-max-duration=CLOUD_STORAGE_MAX_DURATION \ --cloud-storage-output-format=CLOUD_STORAGE_OUTPUT_FORMAT \ --cloud-storage-write-metadata
Im Befehl sind nur
SUBSCRIPTION_ID
, das Flag--topic
und das Flag--cloud-storage-bucket
erforderlich. Die verbleibenden Flags sind optional und können weggelassen werden.Ersetzen Sie Folgendes:
SUBSCRIPTION_ID
: Der Name oder die ID Ihres neuen Cloud Storage-Abos.TOPIC_ID
: Der Name oder die ID Ihres Themas.BUCKET_NAME
: Gibt den Namen eines vorhandenen Buckets an. Beispiel:prod_bucket
. Der Bucket-Name darf die Projekt-ID nicht enthalten. Informationen zum Erstellen eines Buckets finden Sie unter Buckets erstellen.CLOUD_STORAGE_FILE_PREFIX
: Gibt das Präfix für den Cloud Storage-Dateinamen an. Beispiel:log_events_
.CLOUD_STORAGE_FILE_SUFFIX
: gibt das Suffix für den Cloud Storage-Dateinamen an. Beispiel:.txt
.CLOUD_STORAGE_MAX_BYTES
: Die maximalen Byte, die in eine Cloud Storage-Datei geschrieben werden können, bevor eine neue Datei erstellt wird. Der Wert muss zwischen 1 KB und 10 GB liegen. Beispiel:20MB
.CLOUD_STORAGE_MAX_DURATION
: Die maximale Dauer, die verstreichen kann, bevor eine neue Cloud Storage-Datei erstellt wird. Der Wert muss zwischen 1 m und 10 m liegen. Beispiel:5m
.CLOUD_STORAGE_OUTPUT_FORMAT
: Das Ausgabeformat für Daten, die in Cloud Storage geschrieben werden. Mögliche Werte:text
: Nachrichten werden im Rohtext geschrieben und durch einen Zeilenumbruch getrennt.avro
: Nachrichten werden als Avro-Binärprogramm geschrieben.--cloud-storage-write-metadata
wirkt sich nur auf Abos mit dem Ausgabeformatavro
aus.
C++
Folgen Sie der Einrichtungsanleitung für C++ in der Pub/Sub-Kurzanleitung zur Verwendung von Clientbibliotheken, bevor Sie dieses Beispiel ausprobieren. Weitere Informationen finden Sie in der Referenzdokumentation zur Pub/Sub C++ API.
Richten Sie Standardanmeldedaten für Anwendungen ein, um sich bei Pub/Sub zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten.
Go
Folgen Sie der Einrichtungsanleitung für Go in der Pub/Sub-Kurzanleitung zur Verwendung von Clientbibliotheken, bevor Sie dieses Beispiel ausprobieren. Weitere Informationen finden Sie in der Referenzdokumentation zur Pub/Sub Go API.
Richten Sie Standardanmeldedaten für Anwendungen ein, um sich bei Pub/Sub zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten.
Java
Folgen Sie der Einrichtungsanleitung für Java in der Pub/Sub-Kurzanleitung zur Verwendung von Clientbibliotheken, bevor Sie dieses Beispiel ausprobieren. Weitere Informationen finden Sie in der Referenzdokumentation zur Pub/Sub Java API.
Richten Sie Standardanmeldedaten für Anwendungen ein, um sich bei Pub/Sub zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten.
Abos im Blick behalten
Cloud Monitoring bietet eine Reihe von Messwerten zum Überwachen von Abos.
Sie können Abos auch in Pub/Sub überwachen.
Nächste Schritte
Probleme mit einem Cloud Storage-Abo beheben
Hier finden Sie Informationen zu den Preisen für Pub/Sub, einschließlich des Cloud Storage-Abos.