יצירת נושא

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

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

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

  • מפורש (מומלץ): בשיטה הזו, צריך ליצור כל סכימה במאגר לפני שלקוח של יצרן או צרכן יוכל להשתמש בה. אפשר להשתמש Google Cloud במסוף או ב-Managed Kafka API כדי לעשות את זה.

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

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

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

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

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

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

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

  • צריך להעניק את ההרשאה הזו בהקשר הראשי או בהקשר שמוגדר כברירת מחדל: managedkafka.versions.create

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

יצירת נושא או גרסה ראשונה של סכימה

כשיוצרים נושא, יוצרים גם את הגרסה הראשונה שלו. הגרסה הראשונה הזו יוצרת סכימה חדשה או מתייחסת לסכימה קיימת.

המסוף

  1. נכנסים לדף Schema registries במסוף Google Cloud .

    כניסה לדף Schema registries

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

  3. לוחצים על יצירת נושא.

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

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

    מידע נוסף על בחירת שם נושא זמין במאמר אסטרטגיות למתן שמות לנושאים.

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

    • כדי להשתמש בהקשר קיים, בוחרים את ההקשר מתוך הרשימה הקשר. ההקשר שמוגדר כברירת מחדל מוצג כ-(default context).

    • כדי ליצור הקשר חדש, מבצעים את השלבים הבאים:

      1. ברשימה Context, בוחרים באפשרות Create context.

      2. בשדה שם ההקשר, מזינים שם להקשר.

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

      3. לוחצים על Save.

  6. בשדה סוג הסכימה, בוחרים באפשרות Avro או מאגר אחסון לפרוטוקולים.

  7. בשדה Schema definition (הגדרת סכימה), מזינים את הגדרת הסכימה. הפורמט של הסכימה צריך להתאים לסוג הסכימה. אסור לכלול בשמות של שדות הסכימה מידע רגיש כמו פרטים אישיים מזהים (PII) או נתוני אבטחה.

  8. אם הסכימה שלכם משתמשת במבני נתונים שמוגדרים בסכימות אחרות במאגר הסכימות או תלויה בהם, צריך לבצע את השלבים הבאים:

    1. לוחצים על הוספת הפניה לסכימה.
    2. בשדה Reference name, מזינים את שם ההפניה של הסכימה שאליה מתבצעת ההפניה.
    3. ברשימה Subject, בוחרים את הנושא שמכיל את הסכימה שאליה מתייחסים.
    4. ברשימה Version, בוחרים את מספר הגרסה של הסכימה שאליה מתייחסים.
    5. לוחצים על OK.

    חוזרים על השלבים האלה לכל סכימה שמפנים אליה.

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

REST

הבקשה צריכה להיות מאומתת באמצעות אסימון גישה בכותרת Authorization. כדי לקבל אסימון גישה ל-Application Default Credentials הנוכחיים: gcloud auth application-default print-access-token.

בדוגמאות הבאות של API בארכיטקטורת REST נוצרת הגרסה הראשונה של נושא.

כדי ליצור נושא בהקשר שמוגדר כברירת מחדל, שולחים בקשת POST אל ה-URI שצוין באמצעות ה-method‏ projects.locations.schemaRegistries.subjects.versions.create:

POST https://managedkafka.googleapis.com/v1main/projects/PROJECT_ID/locations/LOCATION/schemaRegistries/REGISTRY_ID/subjects/SUBJECT_ID/versions
Authorization: Bearer $(gcloud auth application-default print-access-token)
Content-Type: application/json

אפשרות אחרת היא להשתמש בהקשר ספציפי ולכלול אותו ב-URI של אוסף הנושא באמצעות המתודה projects.locations.schemaRegistries.contexts.subjects.versions.create:

POST https://managedkafka.googleapis.com/v1main/projects/PROJECT_ID/locations/LOCATION/schemaRegistries/REGISTRY_ID/contexts/CONTEXT_ID/subjects/SUBJECT_ID/versions
Authorization: Bearer $(gcloud auth application-default print-access-token)
Content-Type: application/json

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

  • ‫PROJECT_ID (חובה): מזהה הפרויקט ב- Google Cloud.

  • ‫LOCATION (חובה): האזור Google Cloud שבו נמצא מאגר הסכימות.

  • ‫REGISTRY_ID (חובה): המזהה של מאגר הסכימות של היעד.

  • ‫CONTEXT_ID (אופציונלי): המזהה של ההקשר שמכיל את הנושא. אם רוצים להגדיר הקשר ברירת מחדל באופן מפורש, משתמשים ב-.. אחרת, אפשר להשמיט את /contexts/CONTEXT_ID כדי להשתמש בהקשר ברירת המחדל באופן מרומז.

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

  • ‫SUBJECT_ID (חובה): המזהה של הנושא החדש שרוצים ליצור עבורו את הגרסה הראשונה.

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

גוף הבקשה:

בגוף הבקשה צריך לכלול אובייקט JSON שמציין את פרטי הסכימה:

{
  "schema": "YOUR_SCHEMA_DEFINITION_STRING",
  "schema_type": "AVRO" | "PROTOBUF", // Optional, defaults to AVRO
  "references": [ // Optional
    {
      "name": "REFERENCE_NAME",
      "subject": "REFERENCED_SUBJECT_ID",
      "version": REFERENCED_VERSION_NUMBER
    }
    // ... more references
  ]
  // "version": VERSION_NUMBER, // Optional: Usually omitted, let service assign next
  // "id": SCHEMA_ID, // Optional: Usually omitted, let service assign or reuse
}

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

  • ‫YOUR_SCHEMA_DEFINITION_STRING (חובה): מחרוזת שמכילה את המטען הייעודי (payload) של הגדרת הסכימה בפועל.

    אל תכללו בשמות של שדות הסכימה מידע רגיש כמו פרטים אישיים מזהים (PII) או נתוני אבטחה.

  • ‫schemaType (אופציונלי): סוג הסכימה. יכול להיות AVRO או PROTOBUF. אם לא מציינים ערך, ברירת המחדל היא AVRO.

  • ‫references (אופציונלי): מערך של אובייקטים שמגדירים סכימות שאליהן יש הפניה בסכימה הזו.

    • ‫REFERENCE_NAME: השם שמשמש להפניה לסכימה אחרת בהגדרה של הסכימה הזו.
    • ‫REFERENCED_SUBJECT_ID: מזהה הנושא של הסכימה שאליה מתבצעת הפניה.
    • ‫REFERENCED_VERSION_NUMBER: מספר הגרסה הספציפי של הסכימה של הנושא שאליו מתייחסים.

  • ‫versionId, ‏ schemaId: שדות אופציונליים שבדרך כלל המערכת מטפלת בהם. בגרסה הראשונה של נושא, הערך של versionId יהיה 1.

אם הבקשה תתבצע בהצלחה והסכימה תהיה תקפה ותעבור את בדיקות התאימות (אם הן מוגדרות), ה-API יחזיר קוד סטטוס 200 OK. גוף התשובה מכיל את מזהה הסכימה שבו נעשה שימוש בגרסה שנוצרה, שהוא שונה ממזהה הגרסה.

מידע נוסף מופיע במאמרי העזרה של ה-API בארכיטקטורת REST.

המאמרים הבאים

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