רישום גרסה חדשה של סכימה

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

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

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

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

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

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

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

כדי לרשום גרסת סכימה לנושא, נדרשות ההרשאות הבאות:

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

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

רישום גרסה חדשה של סכימה

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

המסוף

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

    כניסה לדף Schema registries

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

  3. בקטע Subjects in this schema registry (נושאים במאגר הסכימות הזה), לוחצים על שם הנושא.

  4. בדף פרטי הנושא, לוחצים על יצירת גרסה.

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

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

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

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

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

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

    בדיקת התאימות שמתבצעת תלויה בסוג התאימות של הנושא.

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

REST

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

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

POST https://managedkafka.googleapis.com/v1/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/v1/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" | "JSON", // 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) של הגדרת הסכימה בפועל.

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

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

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

    • ‫REFERENCED_SUBJECT_ID: שם הנושא המלא של הסכימה שאליה מתבצעת ההפניה. דוגמה: projects/test-project/locations/us-central1/schemaRegistries/test-registry/subjects/test-referenced-subject.

    • ‫REFERENCED_VERSION_NUMBER: מספר הגרסה הספציפי (מספר שלם) של הסכימה של הנושא שאליו יש הפניה.

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

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

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

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

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