מחבר BigQuery Sink מאפשר להעביר נתונים בסטרימינג בזמן אמת מהשירות המנוהל ל-Apache Kafka לטבלאות ב-BigQuery. אתם יכולים להשתמש במחבר הזה כדי להטמיע נתונים בסטרימינג ב-BigQuery לצורך אחסון נתונים, דיווח אנליטי והפעלת לוחות בקרה בזמן אמת.
לפני שמתחילים
לפני שיוצרים מחבר BigQuery Sink, צריך לוודא שיש לכם:
יוצרים אשכול של שירות מנוהל ל-Apache Kafka בשביל אשכול Connect. האשכול הזה הוא אשכול Kafka הראשי שמשויך לאשכול Connect. האשכול הזה הוא גם אשכול המקור שיוצר קצה אחד של צינור עיבוד הנתונים של מחבר BigQuery Sink.
יוצרים אשכול Connect לאירוח של מחבר BigQuery Sink.
יוצרים קבוצת נתונים ב-BigQuery כדי לאחסן את הנתונים שמועברים בסטרימינג מ-Kafka.
יוצרים ומגדירים נושא של Kafka באשכול המקור. הנתונים עוברים מהנושא הזה ב-Kafka למערך הנתונים של היעד ב-BigQuery.
תפקידים והרשאות נדרשים
כדי לקבל את ההרשאות שנדרשות ליצירת מחבר, צריך לבקש מהאדמין להקצות לכם ב-IAM את התפקיד עריכת מחבר מנוהל של Kafka (roles/managedkafka.connectorEditor) בפרויקט.
כדי לקרוא הסבר על מתן תפקידים, ראו איך מנהלים את הגישה ברמת הפרויקט, התיקייה והארגון.
זהו תפקיד שמוגדר מראש וכולל את ההרשאות שנדרשות ליצירת מחבר. כדי לראות בדיוק אילו הרשאות נדרשות, אפשר להרחיב את הקטע ההרשאות הנדרשות:
ההרשאות הנדרשות
כדי ליצור מחבר, צריך את ההרשאות הבאות:
-
יוצרים מחבר:
managedkafka.connectors.create
יכול להיות שתקבלו את ההרשאות האלה באמצעות תפקידים בהתאמה אישית או תפקידים מוגדרים מראש אחרים.
מתן הרשאות כתיבה בטבלה ב-BigQuery
לסוכן השירות של Managed Kafka צריכה להיות הרשאה לכתוב הודעות בטבלה ב-BigQuery.
מקצים לסוכן השירות את התפקיד "עריכת נתונים ב-BigQuery" (roles/bigquery.dataEditor) בפרויקט שמכיל את הטבלה.
אם אשכול Connect נמצא בפרויקט אחר מאשכול השירות המנוהל ל-Apache Kafka, קראו את המאמר יצירת אשכול Connect בפרויקט אחר.
פרמטרים מרכזיים להגדרה
ההמלצות הבאות מתייחסות להגדרות של מחבר ה-sink של BigQuery.
גודל התור
ההגדרה queueSize קובעת את המספר המקסימלי של בקשות כתיבה ל-BigQuery. כברירת מחדל, הערך הזה לא מוגדר, מה שעלול לגרום לשגיאות של מחסור בזיכרון באשכול Connect. מומלץ להגדיר את הערך הזה כדי להפחית את הסיכוי לשגיאות כאלה. הפריטים בתור הם בקשות כתיבה, והם לא תואמים ישירות למספר ההודעות או הבייטים. לכן קשה לדעת מראש מה הערך המומלץ.
כשההודעות נשלפות מ-Kafka, המחבר מפצל את העבודה לפי טבלת היעד שלהן. אם כל ההודעות בסקר נכתבות בטבלה אחת, נוסף רק פריט עבודה אחד. אבל אם ההודעות בסקר נכתבות לשלוש טבלאות, למשל, אז נוספים שלושה פריטי עבודה. אפשר להעריך באופן גס את הגודל של פריט עבודה על סמך הגדרות הסקר של ההודעות, הגודל של הודעות Kafka ומספר הטבלאות שאליהן מתבצעת הכתיבה.
סכימות למחבר BigQuery Sink
המחבר BigQuery Sink משתמש בממיר הערכים שהוגדר (value.converter) כדי לנתח ערכי רשומות של Kafka לשדות. לאחר מכן, הוא כותב את השדות בעמודות עם אותו שם בטבלה ב-BigQuery.
כדי שהמחבר יפעל, צריך סכימה. אפשר לספק את הסכימה בדרכים הבאות:
- סכימה מבוססת-הודעה: הסכימה נכללת כחלק מכל הודעה.
- סכימה מבוססת-טבלה: המחבר מסיק את סכימת ההודעה מסכימת הטבלה ב-BigQuery.
- מרשם סכימות: המחבר קורא את הסכימה ממרשם סכימות, כמו מרשם הסכימות של השירות המנוהל ל-Apache Kafka (גרסת טרום-השקה (Preview)).
בקטעים הבאים מפורטות האפשרויות האלה.
סכימה מבוססת-הודעות
במצב הזה, כל רשומת Kafka כוללת סכימת JSON. המחבר משתמש בסכימה כדי לכתוב את נתוני הרשומה כשורה בטבלה ב-BigQuery.
כדי להשתמש בסכימות שמבוססות על הודעות, צריך להגדיר את המאפיינים הבאים במחבר:
value.converter=org.apache.kafka.connect.json.JsonConvertervalue.converter.schemas.enable=true
ערך לדוגמה של רשומת Kafka:
{
"schema": {
"type": "struct",
"fields": [
{
"field": "user",
"type": "string",
"optional": false
},
{
"field": "age",
"type": "int64",
"optional": false
}
]
},
"payload": {
"user": "userId",
"age": 30
}
}
אם טבלת היעד כבר קיימת, הסכימה של הטבלה ב-BigQuery צריכה להיות תואמת לסכימה של ההודעה המוטמעת. אם הערך הוא autoCreateTables=true, המחבר יוצר באופן אוטומטי את טבלת היעד לפי הצורך. מידע נוסף זמין במאמר יצירת טבלאות.
אם רוצים שהמחבר יעדכן את סכימת הטבלה ב-BigQuery כשסכימות ההודעות משתנות, מגדירים את allowNewBigQueryFields, allowSchemaUnionization או allowBigQueryRequiredFieldRelaxation כ-true.
סכימה מבוססת-טבלה
במצב הזה, הרשומות של Kafka מכילות נתוני JSON פשוטים בלי סכימה מפורשת. המחבר מסיק את הסכימה מטבלת היעד.
דרישות:
- הטבלה ב-BigQuery כבר צריכה להיות קיימת.
- נתוני הרשומה של Kafka צריכים להיות תואמים לסכימת הטבלה.
- במצב הזה אין תמיכה בעדכוני סכימה דינמיים על סמך הודעות נכנסות.
כדי להשתמש בסכימות שמבוססות על טבלאות, צריך להגדיר את המאפיינים הבאים במחבר:
value.converter=org.apache.kafka.connect.json.JsonConvertervalue.converter.schemas.enable=falsebigQueryPartitionDecorator=false
אם הטבלה ב-BigQuery משתמשת בחלוקה למחיצות לפי זמן עם חלוקה יומית למחיצות, הערך של bigQueryPartitionDecorator יכול להיות true. אחרת, צריך להגדיר את המאפיין הזה לערך false.
ערך לדוגמה של רשומת Kafka:
{
"user": "userId",
"age": 30
}
רישום סכימה
במצב הזה, כל רשומת Kafka מכילה נתוני Apache Avro, והסכימה של ההודעה מאוחסנת במרשם סכימות.
כדי להשתמש במחבר BigQuery Sink עם מאגר סכימות, צריך להגדיר את המאפיינים הבאים במחבר:
value.converter=io.confluent.connect.avro.AvroConvertervalue.converter.schema.registry.url=SCHEMA_REGISTRY_URL
מחליפים את SCHEMA_REGISTRY_URL בכתובת ה-URL של מאגר הסכימות.
כדי להשתמש במחבר עם רישום הסכימה של השירות המנוהל ל-Apache Kafka, מגדירים את המאפיין הבא:
value.converter.bearer.auth.credentials.source=GCP
מידע נוסף זמין במאמר שימוש ב-Kafka Connect עם רישום סכימה.
טבלאות מנוהלות של Apache Iceberg
המחבר BigQuery Sink תומך בטבלאות מנוהלות של Apache Iceberg (להלן, טבלאות מנוהלות של Iceberg) כיעד sink.
טבלאות מנוהלות של Iceberg מספקות את הבסיס לבניית מאגרי נתונים בפורמט פתוח ב- Google Cloud. טבלאות מנוהלות ב-Iceberg מציעות את אותה חוויה מנוהלת כמו טבלאות ב-BigQuery, אבל הנתונים מאוחסנים בקטגוריות אחסון בבעלות הלקוח באמצעות Parquet, כדי לאפשר יכולת פעולה הדדית עם פורמטים של טבלאות פתוחות ב-Apache Iceberg.
במאמר יצירת טבלת Apache Iceberg מוסבר איך יוצרים טבלת Apache Iceberg.
יצירת מחבר BigQuery Sink
המסוף
נכנסים לדף Connect Clusters במסוף Google Cloud .
לוחצים על אשכול Connect שבו רוצים ליצור את המחבר.
לוחצים על Create connector.
מזינים מחרוזת בשם המחבר.
בשדה Connector plugin, בוחרים באפשרות BigQuery Sink.
בקטע Topics, מציינים את נושאי Kafka שמהם רוצים לקרוא. אפשר לציין רשימה של נושאים או ביטוי רגולרי שיתאים לשמות של נושאים.
אפשרות 1: בוחרים באפשרות Select a list of Kafka topics. ברשימה Kafka topics, בוחרים נושא אחד או יותר. לוחצים על אישור.
אפשרות 2: בוחרים באפשרות שימוש בביטוי רגולרי של נושא. בשדה Topic regex מזינים ביטוי רגולרי.
לוחצים על Dataset ומציינים מערך נתונים ב-BigQuery. אפשר לבחור מערך נתונים קיים או ליצור מערך נתונים חדש.
אופציונלי: בתיבה 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.
דוגמה לקובץ תצורה של מחבר BigQuery Sink:
name: "BQ_SINK_CONNECTOR_ID"
project: "GCP_PROJECT_ID"
topics: "GMK_TOPIC_ID"
tasks.max: 3
connector.class: "com.wepay.kafka.connect.bigquery.BigQuerySinkConnector"
key.converter: "org.apache.kafka.connect.storage.StringConverter"
value.converter: "org.apache.kafka.connect.json.JsonConverter"
value.converter.schemas.enable: "false"
defaultDataset: "BQ_DATASET_ID"
מחליפים את מה שכתוב בשדות הבאים:
BQ_SINK_CONNECTOR_ID: המזהה או השם של מחבר ה-Sink של BigQuery. במאמר הנחיות למתן שמות למשאבים של שירות מנוהל ל-Apache Kafka מוסבר איך נותנים שמות למחברים. אי אפשר לשנות את השם של המחבר.
GCP_PROJECT_ID: המזהה של הפרויקט ב- Google Cloudשבו נמצא מערך הנתונים ב-BigQuery.
GMK_TOPIC_ID: המזהה של הנושא בשירות המנוהל ל-Apache Kafka, שממנו הנתונים זורמים למחבר BigQuery Sink.
BQ_DATASET_ID: המזהה של מערך הנתונים ב-BigQuery שמשמש ככיור של צינור עיבוד הנתונים.
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 לסביבת פיתוח מקומית.
אחרי שיוצרים מחבר, אפשר לערוך, למחוק, להשהות, לעצור או להפעיל אותו מחדש.
הגדרת המחבר
בקטע הזה מתוארים כמה מאפייני הגדרה שאפשר להגדיר במחבר. רשימה מלאה של המאפיינים הספציפיים למחבר הזה מופיעה במאמר הגדרות של מחבר BigQuery Sink.
שם טבלה
כברירת מחדל, המחבר משתמש בשם הנושא כשם הטבלה ב-BigQuery. כדי להשתמש בשם אחר לטבלה, מגדירים את המאפיין topic2TableMap בפורמט הבא:
topic2TableMap=TOPIC_1:TABLE_1,TOPIC_2:TABLE_2,...
יצירת טבלאות
המחבר BigQuery Sink יכול ליצור את טבלאות היעד אם הן לא קיימות.
אם הערך הוא
autoCreateTables=true, המחבר מנסה ליצור טבלאות ב-BigQuery שלא קיימות. ההגדרה הזו היא פעולת ברירת המחדל.אם הערך הוא
autoCreateTables=false, המחבר לא יוצר טבלאות. אם טבלת היעד לא קיימת, תופיע הודעת שגיאה.
כשהערך של autoCreateTables הוא true, אפשר להשתמש במאפייני ההגדרות הבאים כדי לשלוט באופן מדויק יותר באופן שבו המחבר יוצר ומגדיר טבלאות חדשות:
allBQFieldsNullableclusteringPartitionFieldNamesconvertDoubleSpecialValuespartitionExpirationMssanitizeFieldNamessanitizeTopicstimestampPartitionFieldName
למידע נוסף על המאפיינים האלה, ראו הגדרות של מחבר BigQuery Sink.
מטא-נתונים של Kafka
כדי למפות נתונים נוספים מ-Kafka, כמו מטא-נתונים ומידע על מפתחות, לטבלה ב-BigQuery, צריך להגדיר את השדות kafkaDataFieldName ו-kafkaKeyFieldName בהתאמה. דוגמאות לפרטי מטא-נתונים: הנושא, המחיצה, ההיסט וזמן ההוספה של Kafka.