הנחיות למתן שם למשאב של שירות מנוהל של Google Cloud ל-Apache Kafka

Google Cloud משאב הוא כל רכיב שאתם יוצרים או משתמשים בו בתוך Google Cloud. המשאבים האלה הם אבני הבניין של האפליקציות והמערכות שפועלות בפלטפורמה.

המשאבים בשירות המנוהל ל-Apache Kafka כוללים את המשאבים הבאים:

• אשכול

• נושא

• קבוצת צרכנים

• ACL

• מאגר סכימות

• הקשר (בתוך מאגר סכימות)

• נושא (בתוך מאגר סכימות או הקשר)

• גרסה (גרסאות של סכימה בנושא מסוים)

• סכימה (מזוהה לפי מזהה, משויכת לנושא אחד או יותר ולגרסאות)

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

פורמט שמות המשאבים

אלה הפורמטים של רכיבי התוכן השונים:

• אשכול: projects/{PROJECT_ID}/locations/{LOCATION_NAME}/clusters/{CLUSTER_ID}

• נושא: projects/{PROJECT_ID}/locations/{LOCATION_NAME}/clusters/{CLUSTER_ID}/topics/{TOPIC_ID}

• קבוצת צרכנים: projects/{PROJECT_ID}/locations/{LOCATION_NAME}/clusters/{CLUSTER_ID}/consumerGroup/{CONSUMER_GROUP_ID}

• ‫ACL: projects/{PROJECT_ID}/locations/{LOCATION_NAME}/clusters/{CLUSTER_ID}/acl/{ACL_ID}

• מאגר סכימות: projects/{PROJECT_ID}/locations/{LOCATION_NAME}/schemaRegistries/{SCHEMA_REGISTRY_ID}

• הקשר: projects/{PROJECT_ID}/locations/{LOCATION_NAME}/schemaRegistries/{SCHEMA_REGISTRY_ID}/contexts/{CONTEXT_ID}

• נושא:

  • בהקשר ברירת המחדל: projects/{PROJECT_ID}/locations/{LOCATION_NAME}/schemaRegistries/{SCHEMA_REGISTRY_ID}/subjects/{SUBJECT_ID}
  • בהקשר ספציפי: projects/{PROJECT_ID}/locations/{LOCATION_NAME}/schemaRegistries/{SCHEMA_REGISTRY_ID}/contexts/{CONTEXT_ID}/subjects/{SUBJECT_ID}

• סכימה (מזוהה לפי מזהה):

  • בהקשר ברירת המחדל: projects/{PROJECT_ID}/locations/{LOCATION_NAME}/schemaRegistries/{SCHEMA_REGISTRY_ID}/schemas/ids/{SCHEMA_ID}
  • בהקשר ספציפי: projects/{PROJECT_ID}/locations/{LOCATION_NAME}/schemaRegistries/{SCHEMA_REGISTRY_ID}/contexts/{CONTEXT_ID}/schemas/ids/{SCHEMA_ID}

• גרסה (מזוהה לפי מספר הגרסה מתחת לנושא):

  • בהקשר ברירת המחדל: projects/{PROJECT_ID}/locations/{LOCATION_NAME}/schemaRegistries/{SCHEMA_REGISTRY_ID}/subjects/{SUBJECT_ID}/versions/{VERSION_ID}
  • בהקשר ספציפי: projects/{PROJECT_ID}/locations/{LOCATION_NAME}/schemaRegistries/{SCHEMA_REGISTRY_ID}/contexts/{CONTEXT_ID}/subjects/{SUBJECT_ID}/versions/{VERSION_ID}

בקטעים הבאים מפורט כל רכיב.

מזהה פרויקט

הערך צריך להיות מזהה הפרויקט או מספר הפרויקט, שזמינים במסוף Google Cloud . לדוגמה, my-cool-project הוא מזהה פרויקט, ו-123456789123 הוא מספר פרויקט.

מיקום

הערך חייב להיות אחד מהמיקומים הנתמכים של השירות המנוהל ל-Apache Kafka. רשימת המיקומים הזמינים מופיעה במאמר בנושא מיקומים של שירות מנוהל ל-Apache Kafka.

מזהה

‫ID הוא הפלח האחרון בנתיב המשאב. משתנים כמו {CLUSTER_ID}, {TOPIC_ID}, {CONSUMER_GROUP_ID}, {SCHEMA_REGISTRY_ID}, {CONTEXT_ID} ו-{SUBJECT_ID} צריכים לעמוד בהנחיות הבאות:

• לא מתחיל במחרוזת goog

• התחלה באות

• מגבלות אורך:

  • מזהי אשכול: מכילים בין 3 ל-255 תווים.

  • מזהי נושאים וקבוצות צרכנים: כל אורך שמותר על ידי Apache Kafka. שמות הנושאים ב-Apache Kafka מוגבלים ל-249 תווים.

  • מזהה של מאגר סכימות: יכול להכיל עד 255 תווים.

  • מזהה ההקשר: יכול להכיל עד 255 תווים.

  • מזהה הנושא: מכיל עד 255 בייטים בקידוד UTF-8.

• מגבלות תווים:

  • מזהי אשכולות: צריכים להתאים לביטוי הרגולרי ^[a-z]([-a-z0-9]*[a-z0-9])?. הכוונה היא לאותיות קטנות, מספרים ומקפים. הוא חייב להתחיל באות ולא יכול להסתיים במקף.

  • מזהי נושאים וקבוצות צרכנים: האימות מתבצע על ידי Kafka. התווים המותרים הם `[a-zA-Z0-9.-], שכוללים אלפאנומריים של ASCII, נקודות (.), קווים תחתונים () ומקפים (-).

  • מזהה מאגר הסכימות: אותיות (גדולות או קטנות), מספרים וקווים תחתונים _.

  • מזהה ההקשר: אותיות (רישיות או קטנות), מספרים והתווים המיוחדים הבאים: מקפים -, נקודות ., קווים תחתונים _, טילדות ~, אחוזים % או סימני פלוס +.

  • מזהה הנושא: אותיות (רישיות או קטנות), מספרים והתווים המיוחדים הבאים: מקפים -, נקודות ., קווים תחתונים _, טילדות ~, אחוזים % או סימני פלוס +.

תווים מיוחדים

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

לדוגמה, mi-tópico הוא מזהה לא תקין אם ó הוא לא תו מותר לסוג המזהה הספציפי של המשאב. עם זאת, mi-topico יהיה תקין אם מותרות רק אותיות לטיניות בסיסיות. הפורמט הזה חשוב כשמבצעים קריאות REST.

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

שיטות למתן שמות לנושאים

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

אפשר להגדיר את אסטרטגיית מתן השמות לנושאים על ידי הגדרת המאפיין key.subject.name.strategy או value.subject.name.strategy בהגדרות של לקוח Kafka.

TopicNameStrategy

זו אסטרטגיית ברירת המחדל לספריות לקוח של Kafka בקוד פתוח.

שם הנושא נגזר ישירות משם הנושא ב-Kafka, עם התוספת key למפתחות של הודעות או value לערכים של הודעות. אם הערך של auto.register.schema הוא true, לקוחות של יצרנים משתמשים ב-topicName-value או ב-topicName-key לנושא בשם topicName.

הנה כמה דוגמאות:

• שם הנושא: orders
• ערכים של נושא ההודעה: orders-value
• נושא למפתחות של הודעות: orders-key

הנה רשימה של יתרונות השימוש ב-TopicNameStrategy:

• זו אסטרטגיה פשוטה, ולכן היא מתאימה לתרחישי שימוש רבים.

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

בהמשך מופיעה רשימה של חסרונות בשימוש ב-TopicNameStrategy:

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

RecordNameStrategy

בשיטה הזו נעשה שימוש בשם המחלקה המוגדר במלואו של רשומת Avro או Protobuf כשם הנושא.

הנה כמה דוגמאות:

• שם סכימת Avro: com.example.data.Customer
• שם ההודעה ב-Protobuf: com.example.data.Order
• נושא לתרשים customer: com.example.data.Customer
• נושא לתרשים order: com.example.data.Order

הנה רשימה של יתרונות השימוש ב-RecordNameStrategy:

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

• אפשר להשתמש בסכימה של סוג רשומה ספציפי, כמו com.example.common.Address, בכמה נושאים, וההתפתחות שלה מנוהלת באופן מרכזי במסגרת נושא יחיד.

בהמשך מופיעה רשימה של חסרונות בשימוש ב-RecordNameStrategy:

• חובה להשתמש באותו נושא ובאותה גרסה לכל הנושאים שמשתמשים בסוג רשומה מסוים. זה יכול להיות מגביל אם אתם צריכים גרסאות שונות של אותו סוג רשומה בנושאים שונים.

TopicRecordNameStrategy

האסטרטגיה הזו משלבת היבטים של TopicNameStrategy ושל RecordNameStrategy.

שם הנושא הוא שילוב של שם הנושא ב-Kafka ושם המחלקה המוסמך המלא של הרשומה, בפורמט TOPIC_NAME-FULLY_QUALIFIED_CLASS_NAME.

הנה כמה דוגמאות:

• נושא: user-events

• שם מוגדר במלואו: com.example.events.PageView

• שם הנושא לשילוב הזה: user-events-com.example.events.PageView

• נושא אחר: product-interactions

• שם מוגדר במלואו: com.example.events.PageView

• שם הנושא לשילוב הזה: product-interactions-com.example.events.PageView

הערה: יכול להיות ש-com.example.events.PageView יתפתח בצורה שונה ב-user-events מאשר ב-product-interactions.

הנה רשימה של יתרונות השימוש ב-TopicRecordNameStrategy:

• בדומה ל-RecordNameStrategy, אפשר לשלוח סוגים שונים של רשומות לאותו נושא.

• בניגוד לשיטה RecordNameStrategy, השיטה הזו מאפשרת לכם לפתח את הסכימה לסוג מסוים של רשומה באופן עצמאי בכל נושא. כלומר, יכול להיות ש-my-topic-com.example.project.MyRecord יתפתח בצורה שונה מ-another-topic-com.example.project.MyRecord.

בהמשך מופיעה רשימה של חסרונות בשימוש ב-TopicRecordNameStrategy:

• שמות הנושאים יכולים להיות ארוכים למדי בגלל השילוב של שם הנושא ושם הרשומה המוגדר במלואו.

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