יצירת נושא

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

המסוף

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

    כניסה למרשמי סכימות

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

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

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

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

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

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

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

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

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

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

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

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

  6. בשדה סוג הסכימה, בוחרים באפשרות Avro או Protocol Buffer.

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

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

    1. לוחצים על הוספת הפניה לסכימה.
    2. בשדה שם ההפניה, מזינים את שם ההפניה של הסכימה שאליה מתבצעת ההפניה.
    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 או של השותפים העצמאיים שלה בארצות הברית או במדינות אחרות.