יצירת מחבר Pub/Sub Sink

מחברי Pub/Sub Sink מעבירים בסטרימינג הודעות מנושאי Kafka לנושאי Pub/Sub, וכך מאפשרים לשלב אפליקציות שמבוססות על Kafka עם Pub/Sub.

תרחישים לדוגמה של מחברי Pub/Sub Sink:

  • ארכיטקטורות מבוססות-אירועים. הפעלת עיבוד ב-Pub/Sub מהודעות שפורסמו ב-Kafka.

  • שילוב שירותים. שליחת נתונים מ-Kafka לשירותים או לאפליקציות אחרים של Google Cloud שצורכים מ-Pub/Sub.

  • הפעלת התראות או פעולות בזמן אמת על סמך נתונים מעובדים.

לפני שמתחילים

לפני שיוצרים מחבר Pub/Sub Sink, צריך לוודא שיש לכם:

תפקידים והרשאות נדרשים

כדי לקבל את ההרשאות שנדרשות ליצירת מחבר, בקשו מהאדמין להקצות לכם את התפקיד עריכת מחבר מנוהל של Kafka (roles/managedkafka.connectorEditor) ב-IAM בפרויקט. כדי לקרוא הסבר על מתן תפקידים, ראו איך מנהלים את הגישה ברמת הפרויקט, התיקייה והארגון.

זהו תפקיד שמוגדר מראש וכולל את ההרשאות שנדרשות ליצירת מחבר. כדי לראות בדיוק אילו הרשאות נדרשות, אפשר להרחיב את הקטע ההרשאות הנדרשות:

ההרשאות הנדרשות

כדי ליצור מחבר, צריך את ההרשאות הבאות:

  • יוצרים מחבר: managedkafka.connectors.create

יכול להיות שתקבלו את ההרשאות האלה באמצעות תפקידים בהתאמה אישית או תפקידים מוגדרים מראש אחרים.

מתן הרשאות לפרסום בנושא Pub/Sub

לסוכן השירות של Managed Kafka צריכה להיות הרשאה לפרסם הודעות בנושא Pub/Sub. מקצים לסוכן השירות את התפקיד "פרסום הודעות ב-Pub/Sub" (roles/pubsub.publisher) בפרויקט שכולל את נושא Pub/Sub.

אם אשכול Connect נמצא בפרויקט אחר מאשכול השירות המנוהל ל-Apache Kafka, קראו את המאמר יצירת אשכול Connect בפרויקט אחר.

איך פועל מחבר Pub/Sub Sink

מחבר Pub/Sub Sink שולף הודעות מנושא אחד או יותר ב-Kafka ומפרסם אותן בנושא Pub/Sub.

כאן מוסבר בפירוט איך המחבר Pub/Sub Sink מעתיק נתונים:

  • המחבר צורך הודעות מנושא אחד או יותר של Kafka באשכול המקור.

  • המחבר כותב הודעות למזהה נושא היעד ב-Pub/Sub שצוין באמצעות מאפיין ההגדרה cps.topic. זהו מאפיין חובה.

  • בנוסף, צריך לציין את הפרויקט ב- Google Cloud שמכיל את הנושא ב-Pub/Sub באמצעות מאפיין ההגדרה cps.project. זהו מאפיין חובה.

  • המחבר יכול גם להשתמש בנקודת קצה מותאמת אישית של Pub/Sub, שצוינה באמצעות המאפיין cps.endpoint. נקודת הקצה שמוגדרת כברירת מחדל היא "pubsub.googleapis.com:443".

  • כדי לשפר את הביצועים, המחבר שומר את ההודעות במאגר נתונים זמני לפני שהוא מפרסם אותן ב-Pub/Sub. אפשר להגדיר את המדיניות maxBufferSize,‏ maxBufferBytes,‏ maxDelayThresholdMs,‏ maxOutstandingRequestBytes ו-maxOutstandingMessages כדי לשלוט במאגר הנתונים הזמני.

  • רשומת Kafka מורכבת משלושה רכיבים: כותרות, מפתחות וערכים. המחבר משתמש בממירי מפתחות וערכים כדי להמיר את נתוני ההודעות של Kafka לפורמט שנדרש ב-Pub/Sub. כשמשתמשים בסכימות של ערכי struct או map, המאפיין messageBodyName מציין את השדה או המפתח שצריך להשתמש בהם כגוף ההודעה ב-Pub/Sub.

  • המחבר יכול לכלול את הנושא, המחיצה, ההיסט וחותמת הזמן של Kafka כמאפייני הודעה, באמצעות המאפיין metadata.publish שמוגדר כ-true.

  • המחבר יכול לכלול כותרות של הודעות Kafka כמאפייני הודעות Pub/Sub, באמצעות המאפיין headers.publish שמוגדר כ-true.

  • המחבר יכול לכלול מפתח הזמנה להודעות Pub/Sub באמצעות המאפיין orderingKeySource. האפשרויות לערך שלו כוללות את "none" (ברירת המחדל), "key" ו-"partition".

  • המאפיין tasks.max קובע את רמת המקביליות של המחבר. הגדלת הערך של tasks.max יכולה לשפר את התפוקה, אבל המקביליות בפועל מוגבלת על ידי מספר המחיצות בנושאי Kafka.

מאפיינים של מחבר Pub/Sub Sink

כשיוצרים מחבר Pub/Sub Sink, צריך לציין את המאפיינים הבאים.

שם המחבר

שם ייחודי למחבר בתוך אשכול Connect. הנחיות למתן שמות למשאבים של שירות מנוהל ל-Apache Kafka

סוג הפלאגין של המחבר

בוחרים באפשרות Pub/Sub Sink בתור סוג הפלאגין של המחבר. המאפיין הזה קובע את כיוון זרימת הנתונים, מ-Kafka אל Pub/Sub, ואת הטמעת המחבר הספציפי שבו משתמשים. אם אתם לא משתמשים בממשק המשתמש כדי להגדיר את המחבר, אתם צריכים לציין גם את מחלקת המחבר.

נושאים ב-Kafka

נושאי Kafka שמהם המחבר צורך הודעות. אפשר לציין נושא אחד או יותר, או להשתמש בביטוי רגולרי כדי להתאים לכמה נושאים. לדוגמה, topic.* כדי להתאים לכל הנושאים שמתחילים ב-"topic". הנושאים האלה צריכים להיות באשכול של השירות המנוהל ל-Apache Kafka שמשויך לאשכול של Connect.

נושא Pub/Sub

הנושא הקיים ב-Pub/Sub שאליו המחבר מפרסם הודעות. מוודאים שלחשבון השירות של אשכול Connect יש את התפקיד roles/pubsub.publisher בפרויקט של הנושא, כמו שמתואר בקטע לפני שמתחילים.

הגדרות אישיות

בקטע הזה אפשר לציין מאפייני הגדרה נוספים שספציפיים למחבר.

הנתונים בנושאים של Kafka יכולים להיות בפורמטים שונים, כמו Avro, ‏ JSON או בייטים גולמיים, ולכן חלק חשוב בהגדרה הוא ציון הממירים. ממירים מתרגמים נתונים מהפורמט שמשמש בנושאי Kafka לפורמט הפנימי הסטנדרטי של Kafka Connect. לאחר מכן, המחבר Pub/Sub Sink מקבל את הנתונים הפנימיים האלה וממיר אותם לפורמט שנדרש על ידי Pub/Sub לפני הכתיבה.

מידע כללי נוסף על התפקיד של ממירים ב-Kafka Connect, סוגי הממירים הנתמכים ואפשרויות הגדרה נפוצות זמין במאמר ממירים.

הנה כמה הגדרות ספציפיות למחבר Pub/Sub Sink:

  • ‫cps.project: מזהה הפרויקט ב- Google Cloud שמכיל את נושא Pub/Sub.

  • ‫cps.topic: מציין את נושא Pub/Sub שאליו הנתונים מתפרסמים.

  • ‫cps.endpoint: מציין את נקודת הקצה של Pub/Sub שבה רוצים להשתמש.

רשימה של מאפייני ההגדרות הזמינים הספציפיים למחבר הזה מופיעה במאמר הגדרות של מחבר Pub/Sub Sink.

יצירת מחבר Pub/Sub Sink

כדי ליצור מחבר Pub/Sub Sink:

המסוף

  1. נכנסים לדף Connect Clusters במסוף Google Cloud .

    מעבר אל Connect Clusters

  2. לוחצים על אשכול Connect שבו רוצים ליצור את המחבר.

  3. לוחצים על Create connector.

  4. בשדה שם המחבר, מזינים שם למחבר.

  5. ברשימה Connector plugin, בוחרים באפשרות Pub/Sub Sink.

  6. בקטע Topics, מציינים את נושאי Kafka שהמחבר קורא מהם. אתם יכולים לבחור נושאים ספציפיים או להשתמש בביטוי רגולרי.

    • כדי לבחור נושאים ספציפיים:

      1. לוחצים על Select a list of Kafka topics.
      2. בוחרים נושא אחד לפחות.
      3. לוחצים על OK.
    • כדי להשתמש בביטוי רגולרי:

      1. לוחצים על שימוש בביטוי רגולרי של נושא.
      2. בשדה Topic regex מזינים ביטוי רגולרי. המחבר קורא מכל נושא שתואם לביטוי.

  7. ברשימה Select a Cloud Pub/Sub topic, בוחרים את נושא Pub/Sub שבו המחבר מפרסם הודעות.

  8. אופציונלי: בשדה Configurations, מוסיפים מאפייני הגדרות או עורכים את מאפייני ברירת המחדל. מידע נוסף זמין במאמר הגדרת המחבר.

  9. אופציונלי: בקטע מדיניות הפעלה מחדש של משימות, בוחרים את מדיניות ההפעלה מחדש של משימות של המחבר. מידע נוסף זמין במאמר מדיניות ההפעלה מחדש של משימות.

  10. לוחצים על יצירה.

gcloud

מריצים את הפקודה gcloud managed-kafka connectors create:

gcloud managed-kafka connectors create CONNECTOR_ID \
    --connect-cluster=CONNECT_CLUSTER_ID \
    --location=LOCATION \
    --config-file=CONFIG_FILE

מחליפים את מה שכתוב בשדות הבאים:

  • ‫CONNECTOR_ID: המזהה או השם של המחבר.
  • ‫CONNECT_CLUSTER_ID: המזהה של אשכול Connect שבו נוצר המחבר.
  • ‫LOCATION: המיקום של אשכול Connect.
  • ‫CONFIG_FILE: הנתיב לקובץ תצורה מקומי בפורמט YAML או JSON.

דוגמה לקובץ תצורה של Pub/Sub Sink connector:

connector.class: "com.google.pubsub.kafka.sink.CloudPubSubSinkConnector"
name: "CPS_SINK_CONNECTOR_ID"
tasks.max: "1"
topics: "GMK_TOPIC_ID"
value.converter: "org.apache.kafka.connect.storage.StringConverter"
key.converter: "org.apache.kafka.connect.storage.StringConverter"
cps.topic: "CPS_TOPIC_ID"
cps.project: "GCP_PROJECT_ID"

מחליפים את מה שכתוב בשדות הבאים:

  • ‫CPS_SINK_CONNECTOR_ID: השם או המזהה של מחבר Pub/Sub Sink. במאמר הנחיות למתן שמות למשאבים בשירות המנוהל ל-Apache Kafka מוסבר איך נותנים שמות למחברים. אי אפשר לשנות את השם של המחבר.

  • ‫GMK_TOPIC_ID: המזהה של הנושא בשירות המנוהל ל-Apache Kafka, שממנו מחבר ה-Sink של Pub/Sub קורא את הנתונים.

  • ‫CPS_TOPIC_ID: המזהה של נושא Pub/Sub שאליו מתפרסמים הנתונים.

  • ‫GCP_PROJECT_ID: מזהה הפרויקט ב- Google Cloudשבו נמצא נושא Pub/Sub.

Terraform

אתם יכולים להשתמש במשאב של Terraform כדי ליצור מחבר.

resource "google_managed_kafka_connector" "example-pubsub-sink-connector" {
  project         = data.google_project.default.project_id
  connector_id    = "my-pubsub-sink-connector"
  connect_cluster = google_managed_kafka_connect_cluster.default.connect_cluster_id
  location        = "us-central1"

  configs = {
    "connector.class" = "com.google.pubsub.kafka.sink.CloudPubSubSinkConnector"
    "name"            = "my-pubsub-sink-connector"
    "tasks.max"       = "3"
    "topics"          = "TOPIC_NAME"
    "cps.topic"       = "CPS_TOPIC_NAME"
    "cps.project"     = "CPS_PROJECT_NAME"
    "value.converter" = "org.apache.kafka.connect.storage.StringConverter"
    "key.converter"   = "org.apache.kafka.connect.storage.StringConverter"
  }

  provider = google-beta
}

כדי ללמוד איך להחיל הגדרות ב-Terraform או להסיר אותן, ראו פקודות בסיסיות ב-Terraform.

המשך

לפני שמנסים את הדוגמה הזו, צריך לפעול לפי ההוראות להגדרת Go בקטע התקנת ספריות הלקוח. מידע נוסף מופיע במאמרי העזרה של ה-API של Go עבור שירות מנוהל ל-Apache Kafka.

כדי לבצע אימות בשירות המנוהל ל-Apache Kafka, צריך להגדיר את Application Default Credentials ‏(ADC). מידע נוסף זמין במאמר הגדרת ADC לסביבת פיתוח מקומית.

import (
	"context"
	"fmt"
	"io"

	managedkafka "cloud.google.com/go/managedkafka/apiv1"
	"cloud.google.com/go/managedkafka/apiv1/managedkafkapb"
	"google.golang.org/api/option"
)

// createPubSubSinkConnector creates a Pub/Sub Sink connector.
func createPubSubSinkConnector(w io.Writer, projectID, region, connectClusterID, connectorID, topics, valueConverter, keyConverter, cpsTopic, cpsProject, tasksMax string, opts ...option.ClientOption) error {
	// TODO(developer): Update with your config values. Here is a sample configuration:
	// projectID := "my-project-id"
	// region := "us-central1"
	// connectClusterID := "my-connect-cluster"
	// connectorID := "CPS_SINK_CONNECTOR_ID"
	// topics := "GMK_TOPIC_ID"
	// valueConverter := "org.apache.kafka.connect.storage.StringConverter"
	// keyConverter := "org.apache.kafka.connect.storage.StringConverter"
	// cpsTopic := "CPS_TOPIC_ID"
	// cpsProject := "GCP_PROJECT_ID"
	// tasksMax := "3"
	ctx := context.Background()
	client, err := managedkafka.NewManagedKafkaConnectClient(ctx, opts...)
	if err != nil {
		return fmt.Errorf("managedkafka.NewManagedKafkaConnectClient got err: %w", err)
	}
	defer client.Close()

	parent := fmt.Sprintf("projects/%s/locations/%s/connectClusters/%s", projectID, region, connectClusterID)

	// Pub/Sub Sink sample connector configuration
	config := map[string]string{
		"connector.class": "com.google.pubsub.kafka.sink.CloudPubSubSinkConnector",
		"name":            connectorID,
		"tasks.max":       tasksMax,
		"topics":          topics,
		"value.converter": valueConverter,
		"key.converter":   keyConverter,
		"cps.topic":       cpsTopic,
		"cps.project":     cpsProject,
	}

	connector := &managedkafkapb.Connector{
		Name:    fmt.Sprintf("%s/connectors/%s", parent, connectorID),
		Configs: config,
	}

	req := &managedkafkapb.CreateConnectorRequest{
		Parent:      parent,
		ConnectorId: connectorID,
		Connector:   connector,
	}

	resp, err := client.CreateConnector(ctx, req)
	if err != nil {
		return fmt.Errorf("client.CreateConnector got err: %w", err)
	}
	fmt.Fprintf(w, "Created Pub/Sub sink connector: %s\n", resp.Name)
	return nil
}

Java

לפני שמנסים את הדוגמה הזו, צריך לפעול לפי הוראות ההתקנה של Java בקטע התקנת ספריות הלקוח. מידע נוסף מופיע במאמרי העזרה של Managed Service for Apache Kafka Java API.

כדי לבצע אימות בשירות המנוהל ל-Apache Kafka, צריך להגדיר את Application Default Credentials. מידע נוסף זמין במאמר הגדרת ADC לסביבת פיתוח מקומית.


import com.google.api.gax.rpc.ApiException;
import com.google.cloud.managedkafka.v1.ConnectClusterName;
import com.google.cloud.managedkafka.v1.Connector;
import com.google.cloud.managedkafka.v1.ConnectorName;
import com.google.cloud.managedkafka.v1.CreateConnectorRequest;
import com.google.cloud.managedkafka.v1.ManagedKafkaConnectClient;
import java.io.IOException;
import java.util.HashMap;
import java.util.Map;

public class CreatePubSubSinkConnector {

  public static void main(String[] args) throws Exception {
    // TODO(developer): Replace these variables before running the example.
    String projectId = "my-project-id";
    String region = "my-region"; // e.g. us-east1
    String connectClusterId = "my-connect-cluster";
    String connectorId = "my-pubsub-sink-connector";
    String pubsubProjectId = "my-pubsub-project-id";
    String pubsubTopicName = "my-pubsub-topic";
    String kafkaTopicName = "kafka-topic";
    String connectorClass = "com.google.pubsub.kafka.sink.CloudPubSubSinkConnector";
    String maxTasks = "3";
    String valueConverter = "org.apache.kafka.connect.storage.StringConverter";
    String keyConverter = "org.apache.kafka.connect.storage.StringConverter";
    createPubSubSinkConnector(
        projectId,
        region,
        connectClusterId,
        connectorId,
        pubsubProjectId,
        pubsubTopicName,
        kafkaTopicName,
        connectorClass,
        maxTasks,
        valueConverter,
        keyConverter);
  }

  public static void createPubSubSinkConnector(
      String projectId,
      String region,
      String connectClusterId,
      String connectorId,
      String pubsubProjectId,
      String pubsubTopicName,
      String kafkaTopicName,
      String connectorClass,
      String maxTasks,
      String valueConverter,
      String keyConverter)
      throws Exception {

    // Build the connector configuration
    Map<String, String> configMap = new HashMap<>();
    configMap.put("connector.class", connectorClass);
    configMap.put("name", connectorId);
    configMap.put("tasks.max", maxTasks);
    configMap.put("topics", kafkaTopicName);
    configMap.put("value.converter", valueConverter);
    configMap.put("key.converter", keyConverter);
    configMap.put("cps.topic", pubsubTopicName);
    configMap.put("cps.project", pubsubProjectId);

    Connector connector = Connector.newBuilder()
        .setName(
            ConnectorName.of(projectId, region, connectClusterId, connectorId).toString())
        .putAllConfigs(configMap)
        .build();

    try (ManagedKafkaConnectClient managedKafkaConnectClient = ManagedKafkaConnectClient.create()) {
      CreateConnectorRequest request = CreateConnectorRequest.newBuilder()
          .setParent(ConnectClusterName.of(projectId, region, connectClusterId).toString())
          .setConnectorId(connectorId)
          .setConnector(connector)
          .build();

      // This operation is being handled synchronously.
      Connector response = managedKafkaConnectClient.createConnector(request);
      System.out.printf("Created Pub/Sub Sink connector: %s\n", response.getName());
    } catch (IOException | ApiException e) {
      System.err.printf("managedKafkaConnectClient.createConnector got err: %s\n", e.getMessage());
    }
  }
}

Python

לפני שתנסו את הדוגמה הזו, פעלו לפי הוראות ההגדרה של Python בקטע התקנת ספריות הלקוח. מידע נוסף מופיע במאמרי העזרה של ה-API בשפת Python של שירות מנוהל ל-Apache Kafka.

כדי לבצע אימות בשירות המנוהל ל-Apache Kafka, צריך להגדיר את Application Default Credentials. מידע נוסף זמין במאמר הגדרת ADC לסביבת פיתוח מקומית.

from google.api_core.exceptions import GoogleAPICallError
from google.cloud.managedkafka_v1.services.managed_kafka_connect import (
    ManagedKafkaConnectClient,
)
from google.cloud.managedkafka_v1.types import Connector, CreateConnectorRequest

connect_client = ManagedKafkaConnectClient()
parent = connect_client.connect_cluster_path(project_id, region, connect_cluster_id)

configs = {
    "connector.class": "com.google.pubsub.kafka.sink.CloudPubSubSinkConnector",
    "name": connector_id,
    "tasks.max": tasks_max,
    "topics": topics,
    "value.converter": value_converter,
    "key.converter": key_converter,
    "cps.topic": cps_topic,
    "cps.project": cps_project,
}

connector = Connector()
connector.name = connector_id
connector.configs = configs

request = CreateConnectorRequest(
    parent=parent,
    connector_id=connector_id,
    connector=connector,
)

try:
    operation = connect_client.create_connector(request=request)
    print(f"Waiting for operation {operation.operation.name} to complete...")
    response = operation.result()
    print("Created Connector:", response)
except GoogleAPICallError as e:
    print(f"The operation failed with error: {e}")

אחרי שיוצרים מחבר, אפשר לערוך, למחוק, להשהות, לעצור או להפעיל אותו מחדש.

מה השלב הבא?

‫Apache Kafka®‎ הוא סימן מסחרי רשום של The Apache Software Foundation או של השותפים העצמאיים שלה בארצות הברית או במדינות אחרות.