מחבר מקור של Pub/Sub מעביר הודעות בסטרימינג מ-Pub/Sub אל השירות המנוהל ל-Apache Kafka, וכך מאפשר לשלב את Pub/Sub עם אפליקציות ופייפליינים שמבוססים על Kafka. תרחישים נפוצים לדוגמה כוללים הטמעת נתונים בזמן אמת לעיבוד זרמי נתונים (stream processing) ובניית ארכיטקטורות מבוססות-אירועים.
סקירה כללית
המחבר הזה קורא הודעות ממינוי Pub/Sub, ממיר כל הודעה לרשומת Kafka וכותב את הרשומות לנושא Kafka. כברירת מחדל, המחבר יוצר רשומות Kafka באופן הבא:
- מפתח הרשומה של Kafka הוא
null. - ערך הרשומה של Kafka הוא נתוני ההודעה של Pub/Sub בבייטים.
- הכותרות של רשומות Kafka ריקות.
עם זאת, אפשר לשנות את ההתנהגות הזו. מידע נוסף זמין במאמר הגדרת המחבר.
לפני שמתחילים
לפני שיוצרים מחבר מקור של Pub/Sub, צריך לוודא שיש לכם:
נושא Pub/Sub עם מינוי.
נושא Kafka באשכול Kafka.
אשכול Connect. כשיוצרים את אשכול Connect, מגדירים את האשכול של השירות המנוהל ל-Apache Kafka בתור אשכול Kafka הראשי.
תפקידים והרשאות נדרשים
כדי לקבל את ההרשאות שנדרשות ליצירת מחבר, בקשו מהאדמין להקצות לכם את התפקיד עריכת מחבר מנוהל של Kafka (roles/managedkafka.connectorEditor) ב-IAM בפרויקט.
כדי לקרוא הסבר על מתן תפקידים, ראו איך מנהלים את הגישה ברמת הפרויקט, התיקייה והארגון.
זהו תפקיד שמוגדר מראש וכולל את ההרשאות שנדרשות ליצירת מחבר. כדי לראות בדיוק אילו הרשאות נדרשות, אפשר להרחיב את הקטע ההרשאות הנדרשות:
ההרשאות הנדרשות
כדי ליצור מחבר, צריך את ההרשאות הבאות:
-
יוצרים מחבר:
managedkafka.connectors.create
יכול להיות שתקבלו את ההרשאות האלה באמצעות תפקידים בהתאמה אישית או תפקידים מוגדרים מראש אחרים.
מתן הרשאות לקריאה מ-Pub/Sub
לסוכן השירות המנוהל של Kafka צריכה להיות הרשאה לקרוא הודעות מהמינוי ל-Pub/Sub. מקצים לסוכן השירות את תפקידי ה-IAM הבאים בפרויקט שכולל את המינוי:
- מנוי Pub/Sub (
roles/pubsub.subscriber) - צפייה ב-Pub/Sub (
roles/pubsub.viewer)
אם אשכול Connect נמצא בפרויקט אחר מאשכול השירות המנוהל ל-Apache Kafka, קראו את המאמר יצירת אשכול Connect בפרויקט אחר.
יצירת מחבר מקור של Pub/Sub
כדי ליצור מחבר מקור של Pub/Sub:
המסוף
נכנסים לדף Connect Clusters במסוף Google Cloud .
לוחצים על אשכול Connect שבו רוצים ליצור את המחבר.
לוחצים על Create connector.
בשדה שם המחבר, מזינים שם למחבר.
ברשימה Connector plugin, בוחרים באפשרות Pub/Sub Source.
ברשימה Cloud Pub/Sub subscription, בוחרים מינוי ל-Pub/Sub. המחבר מושך הודעות מהמינוי הזה.
ברשימה Kafka topic, בוחרים את נושא Kafka שבו המחבר כותב הודעות.
אופציונלי: בשדה Configurations, מוסיפים מאפייני הגדרות או עורכים את מאפייני ברירת המחדל. מידע נוסף זמין במאמר הגדרת המחבר.
אופציונלי: בקטע מדיניות הפעלה מחדש של משימות, בוחרים את מדיניות ההפעלה מחדש של משימות של המחבר. מידע נוסף זמין במאמר מדיניות ההפעלה מחדש של משימות.
לוחצים על יצירה.
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.
דוגמה לקובץ תצורה:
connector.class: "com.google.pubsub.kafka.source.CloudPubSubSourceConnector"
cps.project: "PROJECT_ID"
cps.subscription: "PUBSUB_SUBSCRIPTION_ID"
kafka.topic: "KAFKA_TOPIC_ID"
value.converter: "org.apache.kafka.connect.converters.ByteArrayConverter"
key.converter: "org.apache.kafka.connect.storage.StringConverter"
tasks.max: "3"
מחליפים את מה שכתוב בשדות הבאים:
PROJECT_ID: מזהה הפרויקט ב- Google Cloudשבו נמצא המינוי ל-Pub/Sub.
PUBSUB_SUBSCRIPTION_ID: המזהה של המינוי ל-Pub/Sub שממנו רוצים לשלוף נתונים.
KAFKA_TOPIC_ID: המזהה של נושא Kafka שאליו נכתבים הנתונים.
חובה להגדיר את מאפייני ההגדרות cps.project, cps.subscription ו-kafka.topic. לאפשרויות הגדרה נוספות, ראו הגדרת המחבר.
Terraform
אתם יכולים להשתמש במשאב של Terraform כדי ליצור מחבר.
כדי ללמוד איך להחיל הגדרות ב-Terraform או להסיר אותן, ראו פקודות בסיסיות ב-Terraform.
המשך
לפני שמנסים את הדוגמה הזו, צריך לפעול לפי ההוראות להגדרת Go בקטע התקנת ספריות הלקוח. מידע נוסף מופיע במאמרי העזרה של ה-API של Go עבור שירות מנוהל ל-Apache Kafka.
כדי לבצע אימות בשירות המנוהל ל-Apache Kafka, צריך להגדיר את Application Default Credentials (ADC). מידע נוסף זמין במאמר הגדרת ADC לסביבת פיתוח מקומית.
Java
לפני שמנסים את הדוגמה הזו, צריך לפעול לפי הוראות ההתקנה של Java בקטע התקנת ספריות הלקוח. מידע נוסף מופיע במאמרי העזרה של Managed Service for Apache Kafka Java API.
כדי לבצע אימות בשירות המנוהל ל-Apache Kafka, צריך להגדיר את Application Default Credentials. מידע נוסף זמין במאמר הגדרת ADC לסביבת פיתוח מקומית.
Python
לפני שתנסו את הדוגמה הזו, פעלו לפי הוראות ההגדרה של Python בקטע התקנת ספריות הלקוח. מידע נוסף מופיע במאמרי העזרה של ה-API בשפת Python של שירות מנוהל ל-Apache Kafka.
כדי לבצע אימות בשירות המנוהל ל-Apache Kafka, צריך להגדיר את Application Default Credentials. מידע נוסף זמין במאמר הגדרת ADC לסביבת פיתוח מקומית.
הגדרת המחבר
בקטע הזה מתוארים כמה מאפייני הגדרה שאפשר להגדיר במחבר.
רשימה מלאה של המאפיינים הספציפיים למחבר הזה מופיעה במאמר הגדרות של מחבר מקור Pub/Sub.
מצב משיכה
מצב המשיכה קובע איך המחבר מאחזר הודעות Pub/Sub. אלה המצבים הנתמכים:
מצב משיכה (ברירת מחדל). ההודעות נשלפות בקבוצות. כדי להפעיל את המצב הזה, מגדירים את
cps.streamingPull.enabled=false.. כדי להגדיר את גודל האצווה, מגדירים את המאפייןcps.maxBatchSize.מידע נוסף על מצב משיכה זמין במאמר Pull API.
מצב משיכה בסטרימינג. מאפשרת קצב העברת נתונים מקסימלי וזמן אחזור מינימלי כשמאחזרים הודעות מ-Pub/Sub. כדי להפעיל את המצב הזה, מגדירים את
cps.streamingPull.enabled=true.מידע נוסף על מצב משיכה בסטרימינג זמין במאמר StreamingPull API.
אם הפעלתם את משיכת הנתונים בסטרימינג, אתם יכולים לשפר את הביצועים באמצעות הגדרת מאפייני התצורה הבאים:
-
cps.streamingPull.flowControlBytes: המספר המקסימלי של בייטים של הודעות ממתינות לכל משימה. -
cps.streamingPull.flowControlMessages: המספר המקסימלי של הודעות ממתינות לכל משימה. -
cps.streamingPull.maxAckExtensionMs: משך הזמן המקסימלי באלפיות השנייה שבו המחבר מאריך את המועד האחרון להרשמה. cps.streamingPull.maxMsPerAckExtension: משך הזמן המקסימלי שבו המחבר מאריך את המועד האחרון להרשמה לכל הארכה, באלפיות השנייה.-
cps.streamingPull.parallelStreams: מספר הסטרימינג למשיכת הודעות מהמינוי.
-
נקודת קצה (endpoint) של Pub/Sub
כברירת מחדל, המחבר משתמש בנקודת הקצה הגלובלית של Pub/Sub. כדי לציין נקודת קצה, מגדירים את המאפיין cps.endpoint לכתובת של נקודת הקצה.
מידע נוסף על נקודות קצה (endpoints) ב-Pub/Sub
מחיצות Kafka
כברירת מחדל, המחבר כותב למחיצה אחת בנושא. כדי לציין לכמה מחיצות המחבר כותב, מגדירים את המאפיין kafka.partition.count. הערך לא יכול להיות גדול ממספר המחיצות של הנושא.
כדי לציין איך המחבר מקצה הודעות למחיצות, מגדירים את המאפיין kafka.partition.scheme. מידע נוסף זמין במאמר הגדרות של מחבר מקור ב-Pub/Sub.
משתמשים שהשלימו המרה
מגדירים את ממיר המפתחות ל-org.apache.kafka.connect.storage.StringConverter.
בהתאם להגדרות של המחבר, מגדירים את ממיר הערכים לאחת מהאפשרויות הבאות:
org.apache.kafka.connect.converters.ByteArrayConverterorg.apache.kafka.connect.json.JsonConverter
מידע נוסף זמין במאמר ערך הרשומה.
המרה מהודעת טקסט
המחבר Pub/Sub Source ממיר הודעות Pub/Sub לרשומות Kafka. בקטעים הבאים מתואר תהליך ההמרה.
מפתח הרשומה
ממיר המפתחות חייב להיות org.apache.kafka.connect.storage.StringConverter.
כברירת מחדל, מפתחות הרשומות הם
null.כדי להשתמש במאפיין הודעה של Pub/Sub כמפתח, מגדירים את
kafka.key.attributeלשם המאפיין. לדוגמה:kafka.key.attribute=username.כדי להשתמש במפתח ההזמנה של Pub/Sub כמפתח, מגדירים את
kafka.key.attribute=orderingKey.
כותרות של רשומות
כברירת מחדל, כותרות הרשומות ריקות.
אם הערך של kafka.record.headers הוא true, מאפייני ההודעות של Pub/Sub נכתבים ככותרות של רשומות. כדי לכלול את מפתח הסדר, מגדירים את cps.makeOrderingKeyAttribute=true.
ערך הרשומה
ערכי הרשומות נכתבים כמערכי בייטים או כסוגי struct.
ערכי רשומות של מערך בייטים
אם kafka.record.headers הוא true, או אם להודעת Pub/Sub אין מאפיינים מותאמים אישית, המחבר כותב את נתוני ההודעה כמערך בייטים.
מגדירים את ממיר הערכים ל-org.apache.kafka.connect.converters.ByteArrayConverter.
ערכי רשומות של מבנים
אם kafka.record.headers הוא false ולהודעה יש לפחות מאפיין מותאם אישית אחד, המחבר כותב את ערך הרשומה בתור struct. מגדירים את ממיר הערכים ל-org.apache.kafka.connect.json.JsonConverter.
השדות הבאים נכללים ב-struct:
message: נתוני ההודעה ב-Pub/Sub, בבייטים.שדה לכל מאפיין של הודעת Pub/Sub. כדי לכלול את מפתח הסדר, מגדירים את
cps.makeOrderingKeyAttribute=true.
לדוגמה, אם להודעה יש מאפיין username, ערך הרשומה נראה כך:
{
"message":"MESSAGE_DATA",
"username":"Alice"
}
אם הערך של value.converter.schemas.enable הוא true, השדה struct כולל גם את המטען הייעודי (payload) וגם את הסכימה:
{
"schema":
{
"type":"struct",
"fields": [
{
"type":"bytes",
"optional":false,
"field":"message"
},
{
"type":"string",
"optional":false,
"field":"username"
}
],
"optional":false
},
"payload": {
"message":"MESSAGE_DATA",
"username":"Alice"
}
}