Cloud Storage-Abos erstellen

In diesem Dokument wird beschrieben, wie Sie ein Cloud Storage-Abo erstellen. Sie können ein Cloud Storage-Abo über die Google Cloud -Konsole, die Google Cloud CLI, die Clientbibliothek oder die Pub/Sub API erstellen.

Hinweis

Bevor Sie dieses Dokument lesen, sollten Sie mit Folgendem vertraut sein:

So funktioniert ein Cloud Storage-Abo.
Wie Cloud Storage funktioniert und wie Sie Cloud Storage-Buckets erstellen und verwalten.
So konfigurieren Sie ein Thema für unzustellbare Nachrichten, um Nachrichtenfehler zu behandeln.

Erforderliche Rollen und Berechtigungen

Bitten Sie Ihren Administrator, Ihnen die IAM-Rolle Pub/Sub-Bearbeiter (roles/pubsub.editor) für das Projekt zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Erstellen eines Cloud Storage-Abos benötigen. Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

Diese vordefinierte Rolle enthält die Berechtigungen, die zum Erstellen eines Cloud Storage-Abos erforderlich sind. Maximieren Sie den Abschnitt Erforderliche Berechtigungen, um die notwendigen Berechtigungen anzuzeigen:

Erforderliche Berechtigungen

Die folgenden Berechtigungen sind zum Erstellen eines Cloud Storage-Abos erforderlich:

pubsub.subscriptions.create für das Projekt
pubsub.topics.attachSubscription zum Thema

Sie können diese Berechtigungen auch mit benutzerdefinierten Rollen oder anderen vordefinierten Rollen erhalten.

Projektübergreifende Abos

Wenn Sie ein Abo in einem Projekt für ein Thema in einem anderen Projekt erstellen, benötigen Sie die Berechtigung pubsub.subscriptions.create für das Projekt, in dem Sie das Abo erstellen, und die Berechtigung pubsub.topics.attachSubscription für das Thema.

Dienstkonto IAM-Rollen zuweisen

Pub/Sub verwendet ein IAM-Dienstkonto (Identity and Access Management), um auf Google Cloud -Ressourcen zuzugreifen. Standardmäßig wird der Pub/Sub-Dienst-Agent (service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com) verwendet.

Damit Pub/Sub in Cloud Storage schreiben kann, sind für das Dienstkonto die folgenden Rollen erforderlich:

Storage-Objekt-Ersteller (roles/storage.objectCreator)
Leser von Legacy-Storage-Buckets (roles/storage.legacyBucketReader)

Sie können dem Dienstkonto Berechtigungen für das Projekt oder den Cloud Storage-Bucket erteilen:

Projekt

Rufen Sie in der Google Cloud Console die Seite Buckets auf.

Buckets aufrufen
Wählen Sie Von Google bereitgestellte Rollenzuweisungen einschließen aus.
Suchen Sie die Zeile für das Cloud Pub/Sub-Dienstkonto und klicken Sie auf Hauptkonto bearbeiten.
Klicken Sie auf Weitere Rolle hinzufügen und wählen Sie die Rolle Storage-Objekt-Ersteller aus. Wiederholen Sie diesen Schritt für die Rolle Storage Legacy Bucket Reader.

Weitere Informationen finden Sie unter IAM-Rolle über die Console zuweisen.

Cloud Storage-Bucket

Rufen Sie in der Google Cloud -Console Buckets auf.

Buckets aufrufen
Klicken Sie auf den Namen des Cloud Storage-Bucket, für den Sie eine Berechtigung erteilen möchten.
Klicken Sie auf der Seite Bucket-Details auf den Tab Berechtigungen.
Klicken Sie im Bereich Berechtigungen auf den Tab Nach Hauptkonten ansehen.
Klicken Sie auf Zugriff erlauben.
Geben Sie im Feld Neue Hauptkonten die Dienstkonto-ID im folgenden Format ein:

service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com.
Wählen Sie in der Liste Rollen zuweisen die Option Storage Object Creator aus.
Klicken Sie auf Weitere Rolle hinzufügen und wählen Sie Storage Legacy Bucket Reader aus.
Klicken Sie auf Speichern. Dem Hauptkonto werden die Rollen für die Ressource zugewiesen.

Benutzerdefiniertes Dienstkonto verwenden

Wenn Sie dem Cloud Pub/Sub-Dienstkonto die Rollen Storage Object Creator und Storage Legacy Bucket Reader zuweisen, kann jeder Nutzer, der die Berechtigung zum Erstellen eines Abos in Ihrem Projekt hat, in den Cloud Storage-Bucket schreiben. Wenn Sie detailliertere Berechtigungen benötigen, konfigurieren Sie stattdessen ein nutzerverwaltetes Dienstkonto.

Die folgenden Berechtigungen sind erforderlich, um ein vom Nutzer verwaltetes Dienstkonto für das Schreiben in Cloud Storage zu konfigurieren:

Das vom Nutzer verwaltete Dienstkonto muss die Rollen Storage-Objekt-Ersteller und Storage Legacy Bucket Reader haben.
Das Cloud Pub/Sub-Dienstkonto muss die Berechtigung iam.serviceAccounts.getAccessToken für das vom Nutzer verwaltete Dienstkonto haben.
Der Nutzer, der das Abo erstellt, muss die Berechtigung iam.serviceAccounts.actAs für das vom Nutzer verwaltete Dienstkonto haben.

Geben Sie beim Erstellen des Abos das vom Nutzer verwaltete Dienstkonto als Abo-Dienstkonto an.

Cloud Storage-Abo-Eigenschaften

Cloud Storage-Abos unterstützen alle gemeinsamen Abo-Attribute. In den folgenden Abschnitten werden Attribute beschrieben, die speziell für Cloud Storage-Abos gelten.

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 Dateinamensprä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-/Zeit-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 Beispielobjektname 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 Beispielobjektname 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 Cloud Storage-Batchvorgänge:

Maximale Storage-Batchdauer Diese Einstellung ist erforderlich. Pub/Sub schreibt eine neue Ausgabedatei, wenn der angegebene Wert für „maxDuration“ überschritten wird. Die Dauer wird ab dem Zeitpunkt gemessen, an dem Pub/Sub mit dem Schreiben in eine neue Datei beginnt, bis die Datei finalisiert wird. Wenn Sie die maximale Dauer beispielsweise auf 5 Minuten festlegen, schließt Pub/Sub die Datei spätestens 5 Minuten nach Beginn des Schreibvorgangs ab. Eine neue Datei kann erstellt werden, bevor die maximale Dauer abgelaufen ist. Wenn Sie den Wert nicht angeben, wird der Standardwert von 5 Minuten angewendet. Die folgenden Werte sind für die maximale Dauer anwendbar:
- 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 Properties 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 Möglichkeiten, Nachrichten in einen Cloud Storage-Bucket zu schreiben:

Konfigurieren Sie ein benutzerdefiniertes Dienstkonto, damit nur Nutzer mit der Berechtigung iam.serviceAccounts.actAs für das Dienstkonto ein Abo erstellen können, das in das Bucket schreibt. Ein Beispiel für eine Rolle, die die Berechtigung iam.serviceAccounts.actAs enthält, ist die Rolle Dienstkontonutzer (roles/iam.serviceAccountUser).
Verwenden Sie den Standard-Pub/Sub-Dienst-Agent, mit dem jeder Nutzer, der Abos im Projekt erstellen kann, ein Abo erstellen kann, das in den Bucket schreibt. Der Pub/Sub-Dienst-Agent ist die Standardeinstellung, wenn Sie kein benutzerdefiniertes Dienstkonto angeben.

Cloud Storage-Abo erstellen

Console

Rufen Sie in der Google Cloud Console die Seite Abos auf.

Zu den Abos
Klicken Sie auf Abo erstellen.
Geben Sie im Feld Abo-ID einen Namen ein.

Informationen zum Benennen eines Abos finden Sie unter Richtlinien für die Benennung eines Themas 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 als Zustellungstyp die Option In Cloud Storage schreiben aus.
Klicken Sie für den Cloud Storage-Bucket auf Durchsuchen.
- Sie können einen vorhandenen Bucket aus einem beliebigen geeigneten Projekt auswählen.
- Sie können auch auf das Symbol zum Erstellen klicken und der Anleitung auf dem Bildschirm folgen, um einen neuen Bucket zu erstellen.
  
  Nachdem Sie den Bucket erstellt haben, wählen Sie ihn für das Cloud Storage-Abo aus.
  
  Weitere Informationen zum Erstellen eines Buckets finden Sie unter Buckets erstellen.
Wenn Sie den Bucket angeben, prüft Pub/Sub, ob der Pub/Sub-Dienst-Agent die entsprechenden Berechtigungen für den Bucket hat. Wenn es Probleme mit Berechtigungen 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 Cloud Storage-Rollen dem Pub/Sub-Dienst-Agent zuweisen folgen.
Wählen Sie als Dateiformat die Option Text oder Avro aus.

Wenn Sie Avro auswählen, können Sie optional auch angeben, ob die Metadaten der Nachricht in der Ausgabe gespeichert werden sollen.

Weitere Informationen zu den beiden Optionen, einschließlich der Option für Metadaten von Nachrichten für das Avro-Format, finden Sie unter Dateiformat.
Optional: Sie können das Dateinamenpräfix, das Suffix und das Datum/die Uhrzeit 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äfixes, ‑suffixes und ‑datums/-uhrzeit finden Sie unter Dateipräfix, ‑suffix und ‑datum/-uhrzeit.
Geben Sie für Dateibatchverarbeitung eine maximale Zeit an, die vergehen darf, bevor eine neue Datei erstellt wird.

Sie können optional auch die maximale Dateigröße oder die maximale Anzahl von Nachrichten für die Dateien festlegen.

Weitere Informationen zu beiden Optionen für die Batchverarbeitung von Dateien finden Sie unter Batchverarbeitung von Dateien.
Wir empfehlen dringend, Dead Lettering zu aktivieren, um Nachrichtenfehler zu beheben.

Weitere Informationen finden Sie unter Thema für unzustellbare Nachrichten.
Die anderen Einstellungen können Sie beibehalten und auf Erstellen klicken.