במאמר הזה מוסבר איך לבצע שינוי בסכימה של נושאי Pub/Sub.
לפני שמתחילים
- הסבר על סכימות של Pub/Sub.
- יוצרים סכימה.
תפקידים והרשאות נדרשים
כדי לקבל את ההרשאות שנדרשות לביצוע שינוי בסכימה ולניהול סכימות, צריך לבקש מהאדמין להקצות לכם ב-IAM את התפקיד עריכה ב-Pub/Sub (roles/pubsub.editor) בפרויקט.
כדי לקרוא הסבר על מתן תפקידים, ראו איך מנהלים את הגישה ברמת הפרויקט, התיקייה והארגון.
התפקיד המוגדר מראש הזה כולל את ההרשאות שנדרשות כדי לבצע שינוי בסכימה ולנהל סכימות. כדי לראות בדיוק אילו הרשאות נדרשות, אפשר להרחיב את הקטע ההרשאות הנדרשות:
ההרשאות הנדרשות
כדי לבצע שינוי בסכימה ולנהל סכימות, נדרשות ההרשאות הבאות:
-
יצירת סכימה:
pubsub.schemas.create -
צירוף סכימה לנושא:
pubsub.schemas.attach -
ביצוע Commit של גרסת סכימה:
pubsub.schemas.commit -
מחיקת סכימה או עדכון של סכימה:
pubsub.schemas.delete -
קבלת סכימה או עדכונים לסכימה:
pubsub.schemas.get -
רשימת סכימות:
pubsub.schemas.list -
רשימת שינויים בסכימה:
pubsub.schemas.listRevisions -
החזרה של סכימה למצב קודם:
pubsub.schemas.rollback -
כדי לאמת הודעה:
pubsub.schemas.validate -
קבלת מדיניות IAM עבור סכימה:
pubsub.schemas.getIamPolicy -
מגדירים את מדיניות IAM לסכימה:
pubsub.schemas.setIamPolicy
יכול להיות שתקבלו את ההרשאות האלה באמצעות תפקידים בהתאמה אישית או תפקידים מוגדרים מראש אחרים.
אתם יכולים להעניק תפקידים והרשאות לחשבונות ראשיים כמו משתמשים, קבוצות, דומיינים או חשבונות שירות. אפשר ליצור סכימה בפרויקט אחד ולצרף אותה לנושא שנמצא בפרויקט אחר. מוודאים שיש לכם את ההרשאות הנדרשות לכל פרויקט.
שינוי סכימה
אפשר לבצע commit לשינוי בסכימה באמצעותGoogle Cloud המסוף, ה-CLI של gcloud, Pub/Sub API או ספריות הלקוח ב-Cloud.
ריכזנו כאן כמה הנחיות לביצוע שינוי בסכימה:
אפשר לשנות סכימה במסגרת מגבלות מסוימות:
בסכימות של Protocol Buffer, אפשר להוסיף או להסיר שדות אופציונליים. אי אפשר להוסיף או למחוק שדות אחרים. בנוסף, אי אפשר לערוך שדות קיימים.
לגבי סכמות Avro, אפשר לעיין במסמכי התיעוד של Avro כדי לקרוא על הכללים בנושא פתרון סכמות. גרסה חדשה צריכה לפעול לפי הכללים כאילו היא גם סכימת הקורא וגם סכימת הכתיבה.
לסכימה יכולות להיות עד 20 גרסאות בו-זמנית. אם חורגים מהמגבלה, צריך למחוק גרסה של סכימה לפני שיוצרים גרסה נוספת.
לכל גרסה משויך מזהה גרסה ייחודי. מזהה הגרסה הוא מזהה ייחודי אוניברסלי (UUID) בן שמונה תווים שנוצר באופן אוטומטי.
כשמעדכנים את טווח הגרסאות או את הגרסה של סכימה שמשמשת לאימות נושאים, יכול להיות שיעברו כמה דקות עד שהשינויים ייכנסו לתוקף.
המסוף
כדי ליצור שינוי בסכימה, פועלים לפי השלבים הבאים:
נכנסים לדף Pub/Sub schemas במסוף Google Cloud .
לוחצים על מזהה הסכימה של סכימה קיימת.
ייפתח הדף Schema details של הסכימה.
לוחצים על יצירת עדכון.
ייפתח הדף Create schema revision.
מבצעים את השינויים הנדרשים.
לדוגמה, בסכימה לדוגמה ב-Avro שיצרתם במאמר יצירת סכימה, אתם יכולים להוסיף שדה אופציונלי נוסף בשם
Priceבאופן הבא:{ "type": "record", "name": "Avro", "fields": [ { "name": "ProductName", "type": "string", "default": "" }, { "name": "SKU", "type": "int", "default": 0 }, { "name": "InStock", "type": "boolean", "default": false }, { "name": "Price", "type": "double", "default": "0.0" } ] }לוחצים על Validate definition (אימות ההגדרה) כדי לבדוק אם הגדרת הסכימה נכונה.
אפשר גם לאמת את ההודעות לפי הסכימה.
לוחצים על הודעת בדיקה כדי לבדוק הודעה לדוגמה.
בחלון Test message (הודעת בדיקה), בוחרים סוג של Message encoding (קידוד הודעה).
כותבים הודעת בדיקה בתיבת הטקסט גוף ההודעה.
לדוגמה, הנה הודעה לדוגמה לסכימת הבדיקה. בדוגמה הזו, בוחרים באפשרות קידוד ההודעה בתור
JSON.{"ProductName":"GreenOnions", "SKU":34543, "Price":12, "InStock":true}לוחצים על בדיקה.
לוחצים על Commit כדי לשמור את הסכימה.
gcloud
gcloud pubsub schemas commit SCHEMA_ID \ --type=SCHEMA_TYPE \ --definition=SCHEMA_DEFINITION
כאשר:
- SCHEMA_TYPE הוא
avroאוprotocol-buffer. - SCHEMA_DEFINITION הוא
stringשמכיל את הגדרת הסכימה, בפורמט שמותאם לסוג הסכימה שנבחר.
אפשר גם לציין את הגדרת הסכימה בקובץ:
gcloud pubsub schemas commit SCHEMA_ID \ --type=SCHEMA_TYPE \ --definition-file=SCHEMA_DEFINITION_FILE
כאשר:
- SCHEMA_TYPE הוא
avroאוprotocol-buffer. - SCHEMA_DEFINITION_FILE הוא
stringשמכיל את הנתיב לקובץ עם הגדרת הסכימה, בפורמט שמתאים לסוג הסכימה שנבחר.
REST
כדי לבצע שינוי בסכימה, שולחים בקשת POST כמו הבקשה הבאה:
POST https://pubsub.googleapis.com/v1/projects/PROJECT_ID/schemas/SCHEMA_ID:commit Authorization: Bearer $(gcloud auth application-default print-access-token) Content-Type: application/json --data @response-body.json
מציינים את השדות הבאים בגוף הבקשה:
{ "definition": SCHEMA_DEFINITION "type": SCHEMA_TYPE "name": SCHEMA_NAME }
כאשר:
- SCHEMA_TYPE הוא
AVROאוPROTOCOL_BUFFER. - SCHEMA_DEFINITION היא מחרוזת שמכילה את ההגדרה של הסכימה, בפורמט שמתאים לסוג הסכימה שנבחר.
- SCHEMA_NAME הוא השם של סכימה קיימת.
גוף התגובה צריך להכיל ייצוג JSON של משאב סכימה. לדוגמה:
{
"name": SCHEMA_NAME,
"type": SCHEMA_TYPE,
"definition": SCHEMA_DEFINITION
"revisionId": REVISION_ID
"revisionCreateTime": REVISION_CREATE_TIME
}
כאשר:
- REVISION_ID הוא המזהה של הגרסה שנוצר בשרת.
- REVISION_CREATE_TIME היא חותמת הזמן בפורמט ISO 8601 שבה נוצרה הגרסה.
המשך
בדוגמה הבאה נעשה שימוש בגרסה הראשית של ספריית הלקוח Go Pub/Sub (v2). אם אתם עדיין משתמשים בספרייה v1, כדאי לעיין במדריך להעברה לגרסה v2. כדי לראות רשימה של דוגמאות קוד מגרסה 1, אפשר לעיין ב דוגמאות הקוד שהוצאו משימוש.
לפני שמנסים את הדוגמה הזו, צריך לפעול לפי הוראות ההגדרה של Go במאמר מדריך למתחילים: שימוש בספריות לקוח. מידע נוסף מופיע במאמרי העזרה של Pub/Sub Go API.
Avro
Proto
C++
לפני שמנסים את הדוגמה הזו, צריך לפעול לפי הוראות ההגדרה של C++ במאמר תחילת העבודה: שימוש בספריות לקוח. מידע נוסף זמין במאמרי העזרה בנושא Pub/Sub C++ API.
Avro
Proto
Java
לפני שמנסים את הדוגמה הזו, צריך לפעול לפי הוראות ההגדרה של Java במאמר תחילת העבודה: שימוש בספריות לקוח. מידע נוסף מופיע במאמרי העזרה של Pub/Sub Java API.
Avro
Proto
Python
לפני שמנסים את הדוגמה הזו, צריך לפעול לפי הוראות ההגדרה של Python במאמר תחילת העבודה: שימוש בספריות לקוח. מידע נוסף זמין במאמרי העזרה של Pub/Sub Python API.
Avro
Proto
Node.js
לפני שמנסים את הדוגמה הזו, צריך לפעול לפי הוראות ההגדרה של Node.js במאמר תחילת העבודה: שימוש בספריות לקוח. מידע נוסף זמין במאמר Pub/Sub Node.js API reference documentation.
Avro
Proto
Node.js
לפני שמנסים את הדוגמה הזו, צריך לפעול לפי הוראות ההגדרה של Node.js במאמר תחילת העבודה: שימוש בספריות לקוח. מידע נוסף זמין במאמר Pub/Sub Node.js API reference documentation.
Avro
Proto
אחרי שמאשרים שינוי בסכימה, אפשר לראות את הפרטים של השינוי החדש בדף Schemas.