Ein Cloud Storage-Senken-Connector streamt Daten von Managed Service for Apache Kafka zu Cloud Storage, sodass Sie große Datenmengen kostengünstig und skalierbar speichern und verarbeiten können.
Typische Anwendungsfälle für diesen Connector:
Data-Lake-Aufnahme. Kafka-Daten in einem Data Lake für die langfristige Archivierung und Batchverarbeitung speichern.
Daten archivieren, um gesetzliche Anforderungen zu erfüllen
Hinweis
Bevor Sie einen Cloud Storage-Senken-Connector erstellen, benötigen Sie Folgendes:
Erstellen Sie einen Managed Service for Apache Kafka-Cluster für Ihren Connect-Cluster. Dies ist der primäre Kafka-Cluster, der mit dem Connect-Cluster verknüpft ist. Dies ist auch der Quellcluster, der ein Ende der Connector-Pipeline bildet.
Erstellen Sie einen Connect-Cluster, um Ihren Cloud Storage-Senken-Connector zu hosten.
Erstellen Sie einen Cloud Storage-Bucket, um die von Kafka gestreamten Daten zu speichern.
Erstellen und konfigurieren Sie ein Kafka-Thema im Quellcluster. Daten werden von diesem Kafka-Thema in den Cloud Storage-Ziel-Bucket verschoben.
Erforderliche Rollen und Berechtigungen
Bitten Sie Ihren Administrator, Ihnen die IAM-Rolle Managed Kafka Connector Editor (roles/managedkafka.connectorEditor) für Ihr Projekt zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Erstellen eines Connectors 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 Connectors erforderlich sind. Maximieren Sie den Abschnitt Erforderliche Berechtigungen, um die notwendigen Berechtigungen anzuzeigen:
Erforderliche Berechtigungen
Die folgenden Berechtigungen sind zum Erstellen eines Connectors erforderlich:
-
Connector erstellen:
managedkafka.connectors.create
Sie können diese Berechtigungen auch mit benutzerdefinierten Rollen oder anderen vordefinierten Rollen erhalten.
Berechtigungen zum Schreiben in den Cloud Storage-Bucket gewähren
Der Managed Kafka-Dienst-Agent muss die folgenden Berechtigungen haben, um Nachrichten in den Cloud Storage-Bucket zu schreiben:
storage.objects.createstorage.objects.delete
Weisen Sie dem Dienst-Agenten die Rolle „Storage-Objekt-Nutzer“ (roles/storage.objectUser) für das Projekt zu, das den Cloud Storage-Bucket enthält, um diese Berechtigungen zu erteilen.
Wenn sich Ihr Connect-Cluster in einem anderen Projekt als Ihr Managed Service for Apache Kafka-Cluster befindet, lesen Sie den Abschnitt Connect-Cluster in einem anderen Projekt erstellen.
Cloud Storage-Senken-Connector erstellen
So erstellen Sie einen Cloud Storage-Senken-Connector:
Console
Rufen Sie in der Google Cloud Console die Seite Cluster verbinden auf.
Klicken Sie auf den Connect-Cluster, in dem Sie den Connector erstellen möchten.
Klicken Sie auf Connector erstellen.
Geben Sie im Feld Connector-Name einen Namen für den Connector ein.
Wählen Sie in der Liste Connector-Plug-in die Option Cloud Storage-Senke aus.
Geben Sie im Abschnitt Themen an, aus welchen Kafka-Themen der Connector liest. Sie können einzelne Themen auswählen oder einen regulären Ausdruck verwenden.
-
So wählen Sie einzelne Themen aus:
- Klicken Sie auf Liste mit Kafka-Themen auswählen.
- Wählen Sie ein oder mehrere Themen aus.
- Klicken Sie auf OK.
-
So verwenden Sie einen regulären Ausdruck:
- Klicken Sie auf Thema-Regex verwenden.
- Geben Sie im Feld Regulärer Ausdruck für Thema einen regulären Ausdruck ein. Der Connector liest aus jedem Thema, das mit dem Ausdruck übereinstimmt.
-
Geben Sie im Feld GCS-Bucket den Pfad zu einem Cloud Storage-Bucket ein, in den der Connector Daten schreibt, oder klicken Sie auf Durchsuchen, um den Bucket auszuwählen.
Optional: Fügen Sie im Feld Konfigurationen Konfigurationsattribute hinzu oder bearbeiten Sie die Standardattribute. Weitere Informationen finden Sie unter Connector konfigurieren.
Optional: Wählen Sie unter Richtlinie für Task-Neustart die Richtlinie für den Task-Neustart des Connectors aus. Weitere Informationen finden Sie unter Richtlinie für den Neustart von Aufgaben.
Klicken Sie auf Erstellen.
gcloud
Führen Sie den Befehl gcloud
managed-kafka connectors create aus:
gcloud managed-kafka connectors create CONNECTOR_ID \
--connect-cluster=CONNECT_CLUSTER_ID \
--location=LOCATION \
--config-file=CONFIG_FILE
Ersetzen Sie Folgendes:
CONNECTOR_ID: Die ID oder der Name des Connectors.CONNECT_CLUSTER_ID: Die ID des Connect-Clusters, in dem der Connector erstellt wird.LOCATION: Der Standort des Connect-Clusters.CONFIG_FILE: Der Pfad zu einer lokalen YAML- oder JSON-Konfigurationsdatei.
Hier ist ein Beispiel für eine Konfigurationsdatei für den Cloud Storage-Senken-Connector:
connector.class: "io.aiven.kafka.connect.gcs.GcsSinkConnector"
gcs.bucket.name: "BUCKET_NAME"
gcs.credentials.default: "true"
format.output.type: "json"
key.converter: "org.apache.kafka.connect.storage.StringConverter"
value.converter: "org.apache.kafka.connect.json.JsonConverter"
value.converter.schemas.enable: "false"
topics: "TOPIC_LIST"
tasks.max: "3"
Ersetzen Sie Folgendes:
BUCKET_NAME: Der Name des Cloud Storage-Bucket, in den geschrieben werden soll.TOPIC_LIST: Eine durch Kommas getrennte Liste von Kafka-Themen, aus denen gelesen werden soll. Die Liste kann auch reguläre Ausdrücke enthalten.
Terraform
Sie können eine Terraform-Ressource verwenden, um einen Connector zu erstellen.
Informationen zum Anwenden oder Entfernen einer Terraform-Konfiguration finden Sie unter Grundlegende Terraform-Befehle.
Go
Bevor Sie dieses Beispiel ausprobieren, folgen Sie der Einrichtungsanleitung für Go unter Clientbibliotheken installieren. Weitere Informationen finden Sie in der Go API-Referenzdokumentation für Managed Service for Apache Kafka.
Richten Sie zur Authentifizierung bei Managed Service for Apache Kafka Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC) ein. Weitere Informationen finden Sie unter ADC für eine lokale Entwicklungsumgebung einrichten.
Java
Bevor Sie dieses Beispiel ausprobieren, folgen Sie der Anleitung zur Einrichtung von Java unter Clientbibliotheken installieren. Weitere Informationen finden Sie in der Referenzdokumentation zur Managed Service for Apache Kafka Java API.
Richten Sie die Standardanmeldedaten für Anwendungen ein, um sich bei Managed Service for Apache Kafka zu authentifizieren. Weitere Informationen finden Sie unter Standardanmeldedaten für Anwendungen für eine lokale Entwicklungsumgebung einrichten.
Python
Bevor Sie dieses Beispiel ausprobieren, folgen Sie der Einrichtungsanleitung für Python unter Clientbibliotheken installieren. Weitere Informationen finden Sie in der Referenzdokumentation zur Managed Service for Apache Kafka Python API.
Richten Sie die Standardanmeldedaten für Anwendungen ein, um sich bei Managed Service for Apache Kafka zu authentifizieren. Weitere Informationen finden Sie unter ADC für eine lokale Entwicklungsumgebung einrichten.
Connector konfigurieren
Eine vollständige Liste der Attribute, die für diesen Connector spezifisch sind, finden Sie in der Dokumentation zum Cloud Storage-Senken-Connector unter Konfiguration.
Ausgabefelder
Standardmäßig schreibt der Connector nur den Datensatzwert aus jedem Kafka-Datensatz.
Wenn Sie Datensatzschlüssel oder Header einbeziehen möchten, legen Sie für das Attribut format.output.fields eine durch Kommas getrennte Liste der einzuschließenden Felder fest. Die unterstützten Felder sind key, value, headers und timestamp. Beispiel:
format.output.fields=key,value,headers
Ausgabeformate
Der Connector unterstützt das Schreiben von Kafka-Datensätzen im CSV-, JSON- und Parquet-Format. In den folgenden Abschnitten wird beschrieben, wie Sie das Ausgabeformat konfigurieren.
CSV-Format
Legen Sie format.output.type=csv fest, um CSV-Dateien in Cloud Storage zu schreiben.
Verwenden Sie die folgenden Konverter:
Schlüsselkonverter:
org.apache.kafka.connect.storage.StringConverteroderorg.apache.kafka.connect.json.JsonConverterWertkonverter:
org.apache.kafka.connect.converters.ByteArrayConverter
JSON-Format
Wenn Sie JSON-formatierte Dateien in Cloud Storage schreiben möchten, legen Sie für format.output.type einen der folgenden Werte fest:
json: Jede Ausgabedatei enthält ein einzelnes Array von JSON-Objekten, wobei jedes JSON-Objekt einen Kafka-Eintrag darstellt.jsonl: Der Connector schreibt jeden Kafka-Eintrag als JSON-Objekt in eine separate Zeile.
Das folgende Beispiel zeigt, wie der Connector einen Kafka-Eintrag im JSON-Format schreibt:
{"headers":[{"key":"k1","value":"v1"},{"key":"k2","value":"v2"}],"value":"Hello world","key":"my-key"}
Wenn Sie den Schlüssel- oder Wertkonverter auf org.apache.kafka.connect.converters.ByteArrayConverter festlegen, schreibt der Connector dieses Feld als base64-codierten Wert.
Der Connector enthält kein JSON-Schema in der Ausgabe, auch wenn value.converter.schemas.enable den Wert true hat.
Parquet-Format
Wenn Sie Parquet-Dateien in Cloud Storage schreiben möchten, legen Sie format.output.type=parquet fest.
Wenn der Schlüssel- oder Wertkonverter org.apache.kafka.connect.json.JsonConverter ist, müssen die JSON-Daten ein Schema enthalten. Legen Sie das Attribut schemas.enable des Konverters auf true fest.
Bei JSON-Daten schreibt der Connector die Daten als struct-Typ in die Parquet-Datei. Wenn der Kafka-Datensatzwert beispielsweise ein Feld mit dem Namen userid enthält, schreibt der Connector eine Spalte mit dem Namen value.userid. Legen Sie format.output.envelope=false fest, um die Spaltennamen zu vereinfachen. Wenn format.output.envelope false ist, muss format.output.fields ein einzelnes Ausgabefeld angeben.
Cloud Storage-Dateieinstellungen
Mit den folgenden Einstellungen wird gesteuert, wie der Connector Dateien in Cloud Storage schreibt.
gcs.bucket.name: erforderlich. Gibt den Namen des Cloud Storage-Buckets an, in den der Connector Daten schreibt.file.compression.type: Gibt den Komprimierungstyp für die Ausgabedateien an. Beispiele sindgzip,snappy,zstdundnone. Der Standardwert istnone.file.name.prefix: Gibt ein Präfix an, das dem Namen jeder Datei hinzugefügt werden soll. Der Standardwert ist leer ("").file.name.template: Gibt eine Vorlage für den Dateinamen an. Der Connector unterstützt Platzhaltervariablen für die Vorlage, z. B.{{topic}}für den Themennamen und{{partition}}für die Partitionsnummer. Weitere Informationen finden Sie in der Dokumentation zum Cloud Storage-Senken-Connector.file.max.records: Die maximale Anzahl von Datensätzen, die in eine einzelne Datei geschrieben werden sollen. Wenn der Wert 0 ist, gibt es kein bestimmtes Maximum. Der Standardwert ist 0.file.max.bytes: Die maximale Dateigröße in Byte, die geschrieben werden soll. Wenn der Wert 0 ist, gibt es kein bestimmtes Maximum. Der Standardwert ist 0.
Datensatzgruppierung
Wenn der Cloud Storage-Senken-Connector Kafka-Einträge schreibt, werden die Einträge standardmäßig nach Thema und Partition gruppiert. Beispielsweise werden Datensätze aus Partition 0 des Topics my-topic in Dateien mit dem Namen my-topic-0-OFFSET geschrieben, wobei OFFSET der Startoffset ist.
Wenn der Parameter file.name.template die Platzhaltervariable {{key}} enthält, gruppiert der Connector die Datensätze nach Schlüssel. In diesem Modus schreibt der Connector für jeden Datensatzschlüssel eine separate Datei. Der Connector überschreibt jede Datei mit dem neuesten Datensatz für diesen Schlüssel.
Anmeldedaten
Das Attribut gcs.credentials.default muss auf true festgelegt sein. Mit dieser Einstellung kann der Connector automatisch nach Google Cloud -Anmeldedaten suchen.