In diesem Dokument wird beschrieben, wie Sie Apache Kafka und Pub/Sub mit dem Kafka-Connector für Pub/Sub-Gruppen.
Informationen zum Kafka-Connector für Pub/Sub-Gruppen
Apache Kafka ist eine Open-Source-Plattform zum Streamen von Ereignissen. Häufig handelt es sich die in verteilten Architekturen verwendet werden, um die Kommunikation zwischen lose verbundenen Komponenten. Pub/Sub ist ein verwalteter Dienst zum Nachrichten asynchron empfangen. Wie bei Kafka können Sie Pub/Sub für die Kommunikation zwischen Komponenten in der Cloud Architektur.
Mit dem Kafka-Connector für Pub/Sub-Gruppen können Sie diese beiden Systeme einbinden. Die folgenden Connectors sind in der Connector-JAR-Datei enthalten:
- Der Senken-Connector liest Datensätze aus einem oder mehreren Kafka-Themen und veröffentlicht sie in Pub/Sub.
- Der Quell-Connector liest Nachrichten aus einem Pub/Sub-Thema. und veröffentlicht sie in Kafka.
Hier sind einige Szenarien, in denen Sie den Kafka-Connector für Pub/Sub-Gruppen verwenden können:
- Sie migrieren eine Kafka-basierte Architektur zu Google Cloud.
- Sie haben ein Frontend-System, das Ereignisse in Kafka außerhalb von Google Cloud, aber Sie verwenden Google Cloud auch, um einen Teil Ihres Back-Ends auszuführen. die die Kafka-Ereignisse empfangen müssen.
- Sie erfassen Logs aus einer lokalen Kafka-Lösung und senden sie an Google Cloud für Datenanalysen
- Sie haben ein Front-End-System, das Google Cloud verwendet, speichern aber auch Daten. lokal mit Kafka ausgeführt werden.
Für den Connector ist Folgendes erforderlich: Kafka Connect ein Framework für das Streaming von Daten zwischen Kafka und anderen Systemen. Um Connector ausführen, müssen Sie Kafka Connect parallel zu Ihrem Kafka-Cluster ausführen.
In diesem Dokument wird davon ausgegangen, dass Sie mit Kafka und Pub/Sub Bevor Sie dieses Dokument lesen, eine der Pub/Sub-Kurzanleitungen
Der Pub/Sub-Connector unterstützt keine Integration zwischen Google Cloud IAM- und Kafka Connect-ACLs.
Erste Schritte mit dem Connector
Dieser Abschnitt führt Sie durch die folgenden Aufgaben:- Konfigurieren Sie den Kafka-Connector für die Pub/Sub-Gruppe.
- Ereignisse von Kafka an Pub/Sub senden.
- Nachrichten von Pub/Sub an Kafka senden
Vorbereitung
Kafka installieren
Folgen Sie Kurzanleitung zu Apache Kafka um ein Kafka mit einem einzelnen Knoten auf Ihrem lokalen Computer zu installieren. Führen Sie diese Schritte aus in der Kurzanleitung:
- Laden Sie die neueste Kafka-Version herunter und extrahieren Sie sie.
- Starten Sie die Kafka-Umgebung.
- Erstellen Sie ein Kafka-Thema.
Authentifizieren
Der Kafka-Connector für die Pub/Sub-Gruppe muss sich bei Pub/Sub authentifizieren, um Pub/Sub-Nachrichten senden und empfangen. So richten Sie die Authentifizierung ein: führen Sie die folgenden Schritte aus:
- Melden Sie sich bei Ihrem Google Cloud-Konto an. Wenn Sie mit Google Cloud noch nicht vertraut sind, erstellen Sie ein Konto, um die Leistungsfähigkeit unserer Produkte in der Praxis sehen und bewerten zu können. Neukunden erhalten außerdem ein Guthaben von 300 $, um Arbeitslasten auszuführen, zu testen und bereitzustellen.
- Install the Google Cloud CLI.
-
To initialize the gcloud CLI, run the following command:
gcloud init
-
Create or select a Google Cloud project.
-
Create a Google Cloud project:
gcloud projects create PROJECT_ID
Replace
PROJECT_ID
with a name for the Google Cloud project you are creating. -
Select the Google Cloud project that you created:
gcloud config set project PROJECT_ID
Replace
PROJECT_ID
with your Google Cloud project name.
-
-
Create local authentication credentials for your user account:
gcloud auth application-default login
-
Grant roles to your user account. Run the following command once for each of the following IAM roles:
roles/pubsub.admin
gcloud projects add-iam-policy-binding PROJECT_ID --member="USER_IDENTIFIER" --role=ROLE
- Replace
PROJECT_ID
with your project ID. -
Replace
USER_IDENTIFIER
with the identifier for your user account. For example,user:myemail@example.com
. - Replace
ROLE
with each individual role.
- Replace
- Install the Google Cloud CLI.
-
To initialize the gcloud CLI, run the following command:
gcloud init
-
Create or select a Google Cloud project.
-
Create a Google Cloud project:
gcloud projects create PROJECT_ID
Replace
PROJECT_ID
with a name for the Google Cloud project you are creating. -
Select the Google Cloud project that you created:
gcloud config set project PROJECT_ID
Replace
PROJECT_ID
with your Google Cloud project name.
-
-
Create local authentication credentials for your user account:
gcloud auth application-default login
-
Grant roles to your user account. Run the following command once for each of the following IAM roles:
roles/pubsub.admin
gcloud projects add-iam-policy-binding PROJECT_ID --member="USER_IDENTIFIER" --role=ROLE
- Replace
PROJECT_ID
with your project ID. -
Replace
USER_IDENTIFIER
with the identifier for your user account. For example,user:myemail@example.com
. - Replace
ROLE
with each individual role.
- Replace
Connector-JAR-Datei herunterladen
Laden Sie die Connector-JAR-Datei auf Ihren lokalen Computer herunter. Weitere Informationen finden Sie unter Connector beschaffen in der GitHub-Readme-Datei.
Connector-Konfigurationsdateien kopieren
Klonen Sie den GitHub-Repository für den Connector.
git clone https://github.com/googleapis/java-pubsub-group-kafka-connector.git cd java-pubsub-group-kafka-connector
Kopieren Sie den Inhalt des Verzeichnisses
config
in das Unterverzeichnisconfig
von Ihre Kafka-Installation.cp config/* [path to Kafka installation]/config/
Diese Dateien enthalten Konfigurationseinstellungen für den Connector.
Kafka Connect-Konfiguration aktualisieren
- Wechseln Sie zu dem Verzeichnis, das die von Ihnen verwendete Kafka Connect-Binärdatei enthält. heruntergeladen.
- Öffnen Sie im Binärverzeichnis von Kafka Connect die Datei namens
config/connect-standalone.properties
in einem Texteditor. - Wenn
plugin.path property
auskommentiert ist, entfernen Sie die Kommentarzeichen. Aktualisieren Sie
plugin.path property
, um den Pfad zur Connector-JAR-Datei anzugeben.Beispiel:
plugin.path=/home/PubSubKafkaConnector/pubsub-group-kafka-connector-1.0.0.jar
Legen Sie das Attribut
offset.storage.file.filename
auf einen lokalen Dateinamen fest. In im eigenständigen Modus verwendet wird, verwendet Kafka diese Datei zum Speichern von Offset-Daten.Beispiel:
offset.storage.file.filename=/tmp/connect.offsets
Ereignisse von Kafka an Pub/Sub weiterleiten
In diesem Abschnitt wird beschrieben, wie Sie den Senken-Connector starten, Ereignisse in Kafka veröffentlichen, und anschließend die weitergeleiteten Nachrichten aus Pub/Sub lesen.
Verwenden Sie die Google Cloud CLI, um ein Pub/Sub-Thema mit einem Abo.
gcloud pubsub topics create PUBSUB_TOPIC gcloud pubsub subscriptions create PUBSUB_SUBSCRIPTION --topic=PUBSUB_TOPIC
Ersetzen Sie Folgendes:
- PUBSUB_TOPIC: Der Name eines Pub/Sub-Themas, für das Nachrichten von Kafka empfangen.
- PUBSUB_SUBSCRIPTION: der Name eines Pub/Sub Abo für das Thema.
Öffnen Sie die Datei
/config/cps-sink-connector.properties
in einem Texteditor. Hinzufügen für die folgenden Attribute, die mit"TODO"
gekennzeichnet sind, Kommentare:topics=KAFKA_TOPICS cps.project=PROJECT_ID cps.topic=PUBSUB_TOPIC
Ersetzen Sie Folgendes:
- KAFKA_TOPICS: eine durch Kommas getrennte Liste von zu lesenden Kafka-Themen aus.
- PROJECT_ID: Das Google Cloud-Projekt, das die Datei enthält. Pub/Sub-Thema.
- PUBSUB_TOPIC: Das Pub/Sub-Thema, das die Nachricht erhalten soll. Nachrichten von Kafka gesendet.
Führen Sie im Kafka-Verzeichnis den folgenden Befehl aus:
bin/connect-standalone.sh \ config/connect-standalone.properties \ config/cps-sink-connector.properties
Folgen Sie der Anleitung in der Kurzanleitung zu Apache Kafka um einige Ereignisse in Ihr Kafka-Thema zu schreiben.
Verwenden Sie die gcloud CLI, um die Ereignisse aus Pub/Sub zu lesen.
gcloud pubsub subscriptions pull PUBSUB_SUBSCRIPTION --auto-ack
Nachrichten von Pub/Sub an Kafka weiterleiten
In diesem Abschnitt wird beschrieben, wie Sie den Quell-Connector starten, Pub/Sub und lesen Sie die weitergeleiteten Nachrichten aus Kafka.
Verwenden Sie die gcloud CLI, um ein Pub/Sub-Thema mit einem Abo.
gcloud pubsub topics create PUBSUB_TOPIC gcloud pubsub subscriptions create PUBSUB_SUBSCRIPTION --topic=PUBSUB_TOPIC
Ersetzen Sie Folgendes:
- PUBSUB_TOPIC: Der Name eines Pub/Sub-Themas.
- PUBSUB_SUBSCRIPTION: der Name eines Pub/Sub Abo.
Datei mit dem Namen
/config/cps-source-connector.properties
in einer Textdatei öffnen Editor. Fügen Sie Werte für die folgenden Attribute hinzu, die mit"TODO"
gekennzeichnet sind: die Kommentare:kafka.topic=KAFKA_TOPIC cps.project=PROJECT_ID cps.subscription=PUBSUB_SUBSCRIPTION
Ersetzen Sie Folgendes:
- KAFKA_TOPIC: Die Kafka-Themen, die den Pub/Sub-Nachrichten.
- PROJECT_ID: Das Google Cloud-Projekt, das die Datei enthält. Pub/Sub-Thema.
- PUBSUB_TOPIC: Das Pub/Sub-Thema.
Führen Sie im Kafka-Verzeichnis den folgenden Befehl aus:
bin/connect-standalone.sh \ config/connect-standalone.properties \ config/cps-source-connector.properties
Veröffentlichen Sie mit der gcloud CLI eine Nachricht in Pub/Sub.
gcloud pubsub topics publish PUBSUB_TOPIC --message="message 1"
Lesen Sie die Nachricht von Kafka. Folgen Sie der Anleitung in der Kurzanleitung zu Apache Kafka um die Nachrichten aus dem Kafka-Thema zu lesen.
SMS-Conversion
Kafka-Eintrag enthält einen Schlüssel und einen Wert, bei denen es sich um Byte-Arrays mit variabler Länge handelt. Optional kann ein Der Kafka-Eintrag kann auch Header haben, bei denen es sich um Schlüssel/Wert-Paare handelt. A Pub/Sub-Nachricht besteht aus zwei Hauptteilen: dem Nachrichtentext und null oder mehr Schlüssel/Wert-Attributen.
Kafka Connect verwendet Converter, um Schlüssel und Werte zu und von Kafka zu serialisieren. Legen Sie im Connector die folgenden Eigenschaften fest, um die Serialisierung zu steuern Konfigurationsdateien:
key.converter
: Der Converter, der zum Serialisieren von Datensatzschlüsseln verwendet wird.value.converter
: Der Converter, der zum Serialisieren von Datensatzwerten verwendet wird.
Der Text einer Pub/Sub-Nachricht ist ein ByteString
-Objekt.
ist das direkte Kopieren der Nutzlast. Aus diesem Grund
empfehlen, einen Converter zu verwenden, der primitive Datentypen (Ganzzahl, Gleitkomma,
String- oder Byte-Schemas), um eine Deserialisierung und
Nachrichtentext neu serialisieren.
Konvertierung von Kafka zu Pub/Sub
Der Senken-Connector konvertiert Kafka-Einträge in Pub/Sub-Nachrichten als folgt:
- Der Kafka-Eintragsschlüssel wird als Attribut namens
"key"
im Pub/Sub-Nachricht. - Standardmäßig löscht der Connector alle Header im Kafka-Eintrag. Wenn jedoch
legen Sie für die Konfigurationsoption
headers.publish
den Connectortrue
fest. schreibt die Header als Pub/Sub-Attribute. Der Connector überspringt alle Header, die die Pub/Sub- Beschränkungen für Nachrichtenattribute. - Bei Integer-, Float-, String- und Bytes-Schemas übergibt der Connector die Bytes des Kafka-Eintragswerts direkt in die Pub/Sub-Nachricht einfügen. Textkörper.
- Bei Strukturschemas schreibt der Connector jedes Feld als Attribut des
Pub/Sub-Nachricht. Wenn das Feld beispielsweise
{ "id"=123 }
ist, Die resultierende Pub/Sub-Nachricht hat das Attribut"id"="123"
. Die -Feldwert wird immer in einen String konvertiert. Map- und Struct-Typen sind nicht werden als Feldtypen innerhalb einer Struktur unterstützt. - Bei Kartenschemas schreibt der Connector jedes Schlüssel/Wert-Paar als Attribut
der Pub/Sub-Nachricht. Wenn die Karte zum Beispiel
{"alice"=1,"bob"=2}
hat die Pub/Sub-Nachricht zwei"alice"="1"
und"bob"="2"
. Die Schlüssel und Werte werden konvertiert. in Strings umwandeln.
Struktur- und Kartenschemas weisen einige zusätzliche Verhaltensweisen auf:
Optional können Sie ein bestimmtes Strukturfeld oder einen Zuordnungsschlüssel als Nachrichtentextes durch Festlegen des Konfigurationsattributs
messageBodyName
. Die des Felds oder Schlüssels wird alsByteString
im Nachrichtentext gespeichert. WennmessageBodyName
nicht festlegen, ist der Nachrichtentext für Struktur und Kartenschemas.Bei Arraywerten unterstützt der Connector nur primitive Arraytypen. Die Wertesequenz im Array zu einer einzelnen
ByteString
verkettet -Objekt enthält.
Konvertierung von Pub/Sub zu Kafka
Der Quell-Connector konvertiert Pub/Sub-Nachrichten in Kafka-Einträge wie folgt:
Kafka-Eintragsschlüssel: Der Schlüssel ist standardmäßig auf
null
festgelegt. Optional können Sie ein Pub/Sub-Nachrichtenattribut als Schlüssel angeben, Festlegen der Konfigurationsoptionkafka.key.attribute
. In diesem Fall nach einem Attribut mit diesem Namen und legt als Eintragsschlüssel Attributwert Wenn das angegebene Attribut nicht vorhanden ist, lautet der Eintragsschlüssel aufnull
festgelegt.Kafka-Eintragswert. Der Connector schreibt den Eintragswert so:
Wenn die Pub/Sub-Nachricht keine benutzerdefinierten Attribute hat, Schreibt den Pub/Sub-Nachrichtentext direkt in den Kafka-Eintrag Wert als
byte[]
-Typ unter Verwendung des Konverters, der durchvalue.converter
.Ob die Pub/Sub-Nachricht benutzerdefinierte Attribute und
kafka.record.headers
gleichfalse
ist, schreibt der Connector eine Struktur in die Eintragswert. Die Struktur enthält ein Feld für jedes Attribut und ein Feld namens"message"
, dessen Wert der Pub/Sub-Nachrichtentext ist (gespeichert als Byte):{ "message": "<Pub/Sub message body>", "<attribute-1>": "<value-1>", "<attribute-2>": "<value-2>", .... }
In diesem Fall müssen Sie eine
value.converter
verwenden, die mitstruct
Schemas, z. B.org.apache.kafka.connect.json.JsonConverter
.Ob die Pub/Sub-Nachricht benutzerdefinierte Attribute und
kafka.record.headers
gleichtrue
ist, schreibt der Connector die Attribute als Kafka-Eintragsheader. Schreibt den Pub/Sub-Nachrichtentext direkt in den Kafka-Eintragswert alsbyte[]
-Typ, indem Sie den Converter verwenden. angegeben durchvalue.converter
.
Kafka-Eintragsheader. Standardmäßig sind die Header leer, es sei denn, Sie legen Folgendes fest:
kafka.record.headers
intrue
.
Konfigurationsoptionen
Zusätzlich zu den Konfigurationen, die von der Kafka Connect API bereitgestellt werden, Der Kafka-Connector für Pub/Sub-Gruppen unterstützt die folgenden Konfigurationen.
Konfigurationsoptionen für Senken-Connectors
Der Senken-Connector unterstützt die folgenden Konfigurationsoptionen.
Einstellung | Datentyp | Beschreibung |
---|---|---|
connector.class |
String |
Erforderlich. Die Java-Klasse für den Connector. Für
Pub/Sub-Senken-Connector ist, muss der Wert
com.google.pubsub.kafka.sink.CloudPubSubSinkConnector
|
cps.endpoint |
String |
Der zu verwendende Pub/Sub-Endpunkt. Standardeinstellung: |
cps.project |
String |
Erforderlich. Die Google Cloud, die die Pub/Sub-Thema. |
cps.topic |
String |
Erforderlich. Das zu veröffentlichende Pub/Sub-Thema Kafka zeichnet auf. |
gcp.credentials.file.path |
String |
Optional. Der Pfad zu einer Datei, in der Google Cloud-Anmeldedaten gespeichert sind zur Authentifizierung von Pub/Sub Lite. |
gcp.credentials.json |
String |
Optional. Ein JSON-Blob, das Google Cloud für Pub/Sub Lite authentifiziert wird. |
headers.publish |
Boolean |
Wenn Standardeinstellung: |
maxBufferBytes |
Long |
Die maximale Anzahl von Byte, die für eine Topic-Kafka-Partition empfangen werden sollen bevor sie in Pub/Sub veröffentlicht werden. Standardwert: 10000000. |
maxBufferSize |
Integer |
Die maximale Anzahl der Datensätze, die bei einer Kafka-Themenpartition empfangen werden sollen bevor sie in Pub/Sub veröffentlicht werden. Der Standardwert is 100. |
maxDelayThresholdMs |
Integer |
Die maximale Wartezeit bis zum Erreichen
Der Standardwert is 100. |
maxOutstandingMessages |
Long |
Die maximale Anzahl an Datensätzen, die ausstehend sein können, einschließlich unvollständige und ausstehende Batches, bevor der Publisher weitere Veröffentlichung. Standardeinstellung: |
maxOutstandingRequestBytes |
Long |
Die maximale Anzahl der insgesamt ausstehenden Byte, einschließlich unvollständige und ausstehende Batches, bevor der Publisher weitere Veröffentlichung. Standardeinstellung: |
maxRequestTimeoutMs |
Integer |
Das Zeitlimit für einzelne Veröffentlichungsanfragen an Pub/Sub in Millisekunden. Standardwert: 10.000. |
maxTotalTimeoutMs |
Integer |
Das Gesamtzeitlimit in Millisekunden für den Veröffentlichungsaufruf in Pub/Sub, einschließlich Wiederholungsversuche. Standardwert: 60.000. |
metadata.publish |
Boolean |
Fügen Sie bei Standardeinstellung: |
messageBodyName |
String |
Gibt bei Verwendung eines Struktur- oder Zuordnungswertschemas den Namen eines Feld oder Schlüssel als Pub/Sub-Nachrichtentext verwendet werden soll. Weitere Informationen finden Sie unter Konvertierung von Kafka zu Pub/Sub Standardeinstellung: |
orderingKeySource |
String |
Gibt an, wie der Sortierungsschlüssel in Pub/Sub festgelegt wird angezeigt. Kann einer der folgenden Werte sein:
Standardeinstellung: |
topics |
String |
Erforderlich. Eine durch Kommas getrennte Liste von Kafka-Themen, aus denen Sie ablesen können. |
Konfigurationsoptionen für den Quell-Connector
Der Quell-Connector unterstützt die folgenden Konfigurationsoptionen.
Einstellung | Datentyp | Beschreibung |
---|---|---|
connector.class |
String |
Erforderlich. Die Java-Klasse für den Connector. Für
Pub/Sub-Quell-Connector verwendet, muss der Wert
com.google.pubsub.kafka.source.CloudPubSubSourceConnector
|
cps.endpoint |
String |
Der zu verwendende Pub/Sub-Endpunkt. Standardeinstellung: |
cps.makeOrderingKeyAttribute |
Boolean |
Wenn Standardeinstellung: |
cps.maxBatchSize |
Integer |
Die maximale Anzahl von Nachrichten, die pro Pull-Anfrage in einem Stapel zusammengefasst werden sollen Pub/Sub Standardeinstellung: 100 |
cps.project |
String |
Erforderlich. Das Google Cloud-Projekt, das die Pub/Sub-Thema. |
cps.subscription |
String |
Erforderlich. Der Name von Pub/Sub Abo, aus dem Nachrichten abgerufen werden sollen. |
gcp.credentials.file.path |
String |
Optional. Der Pfad zu einer Datei, in der Google Cloud-Anmeldedaten gespeichert sind zur Authentifizierung von Pub/Sub Lite. |
gcp.credentials.json |
String |
Optional. Ein JSON-Blob, das Google Cloud für Pub/Sub Lite authentifiziert wird. |
kafka.key.attribute |
String |
Das Pub/Sub-Nachrichtenattribut, das als Schlüssel für
Nachrichten, die in Kafka veröffentlicht wurden. Wenn Standardeinstellung: |
kafka.partition.count |
Integer |
Die Anzahl der Kafka-Partitionen für das Kafka-Thema, in denen Nachrichten
veröffentlicht wurden. Dieser Parameter wird ignoriert, wenn das Partitionsschema
Der Standardwert ist 1. |
kafka.partition.scheme |
String |
Das Schema zum Zuweisen einer Nachricht zu einer Partition in Kafka. Kann sein einer der folgenden Werte:
Standardeinstellung: |
kafka.record.headers |
Boolean |
Wenn |
kafka.topic |
String |
Erforderlich. Das Kafka-Thema, das Nachrichten empfängt Pub/Sub |
Support
Wenn Sie Hilfe benötigen, erstellen Sie ein Support-Ticket. Erstellen Sie bei allgemeinen Fragen und Diskussionen ein Problem. im GitHub-Repository.
Nächste Schritte
- Unterschiede zwischen Kafka und Pub/Sub
- Weitere Informationen zum Kafka-Connector für Pub/Sub-Gruppen
- Kafka-Connector für Pub/Sub-Gruppen ansehen GitHub-Repository.