כשמפתחים את מערכת Pub/Sub, אפשר להשתמש בפירוק של מטען ייעודי כדי להתחבר למערכות אחרות שלא עומדות בכל דרישות המערכת של הטמעה רגילה של נקודת קצה מסוג Pub/Sub push.
הנה כמה תרחישי שימוש אפשריים בפירוק של מטען ייעודי (payload):
- אתם לא רוצים לכתוב קוד לניתוח הודעות שספציפי ל-Pub/Sub עבור נקודות הקצה של HTTP push.
- אתם מעדיפים לקבל את המטא-נתונים של הודעות Pub/Sub ככותרות HTTP במקום המטא-נתונים בגוף ה-HTTP POST.
- אתם רוצים לשלוח הודעות Pub/Sub ולהחריג את המטא-נתונים של Pub/Sub, למשל כששולחים נתונים ל-API של צד שלישי.
איך מתבצעת פריסת המטען הייעודי (payload)
התכונה 'פריקת מטען ייעודי' מסירה מהודעות Pub/Sub את כל המטא-נתונים של ההודעה, למעט נתוני ההודעה. כששולחים נתוני הודעות גולמיים, המנויים יכולים לעבד את ההודעה בלי להקפיד על דרישות המערכת של Pub/Sub.
- במקרה של פריסת מטען ייעודי (payload), נתוני ההודעה מועברים ישירות כגוף ה-HTTP.
- בלי פתיחה של מטען ייעודי (payload), Pub/Sub מעביר אובייקט JSON שמכיל כמה שדות של מטא-נתונים של ההודעה ושדה של נתוני ההודעה. במקרה הזה, צריך לנתח את ה-JSON כדי לאחזר את נתוני ההודעה ואז לבצע פענוח base64.
כתיבת מטא-נתונים
אחרי שמפעילים את האפשרות 'ביטול עטיפה של מטען ייעודי', אפשר להשתמש באפשרות כתיבת מטא-נתונים, שמוסיפה את המטא-נתונים של ההודעה שהוסרו קודם לכותרת הבקשה.
- הכתיבה של מטא-נתונים מופעלת. מוסיפים מחדש את המטא-נתונים של ההודעה לכותרת הבקשה. בנוסף, נתוני ההודעה הגולמיים מפוענחים ונשלחים.
- השבתה של כתיבת מטא-נתונים. רק נתוני ההודעה הגולמיים והמפוענחים מועברים.
מטא-נתונים של כתיבה נחשפים דרך Pub/Sub, הארגומנט --push-no-wrapper-write-metadata של Google Cloud CLI והמאפיין NoWrapper של ה-API.
כברירת מחדל, הערך הזה הוא null.
לפני שמתחילים
- מידע נוסף על מינויים ועל מינויים מסוג push ב-Pub/Sub אפשר להשתמש בפריקת מטען ייעודי (payload) רק עם מינויים לשליחת הודעות פוש.
- איך מגדירים מינוי דחיפה
דוגמה להודעות עטופות ולא עטופות
בדוגמאות הבאות מוצג ההבדל בין שליחת הודעת HTTP עטופה לבין שליחת הודעת HTTP לא עטופה. בדוגמאות האלה, נתוני ההודעה מכילים את המחרוזת {"status": "Hello there"}.
בדוגמה הזו, נוצר מינוי עם התכונה payload unwrapping (פריקת מטען ייעודי) מופעלת, והודעה מתפרסמת ב-mytopic. הוא משתמש במפתח סידור עם ערך של some-key וסוג המדיה מוצהר כ-application/json.
gcloud pubsub topics publish mytopic
--message='{"status": "Hello there"}'
--ordering-key="some-key"
--attribute "Content-Type=application/json"
בקטעים הבאים מוצג ההבדל בין הודעה עטופה להודעה לא עטופה.
הודעה עם גלישת טקסט
בדוגמה הבאה מוצגת הודעה רגילה שעטופה ב-Pub/Sub. במקרה הזה, האפשרות להסרת העטיפה של המטען הייעודי (payload) לא מופעלת.
| פרסום | נקודת הקצה (endpoint) של הודעת ה-Push מקבלת |
|---|---|
data="{"status": "Hello there"}"
ordering_key="some-key"
attributes=
{
{"Content-Type", "application/json"}
} |
Content-Length: 361
Content-Type: application/json
User-Agent: CloudPubSub-Google
Host: subscription-project.uc.r.appspot.com
{
"message": {
"attributes": {
"Content-Type": "application/json"
},
"data": "eyJzdGF0dXMiOiAiSGVsbG8gdGhlcmUifQ==", // Base64 - {"status": "Hello there"}
"messageId": "2070443601311540",
"message_id": "2070443601311540",
"publishTime": "2021-02-26T19:13:55.749Z",
"publish_time": "2021-02-26T19:13:55.749Z"
},
"subscription": "projects/myproject/..."
} |
הודעה לא עטופה עם השבתה של כתיבת מטא-נתונים
בדוגמה הבאה מוצגת הודעה לא עטופה עם האפשרות 'כתיבת מטא-נתונים' מושבתת. במקרה כזה, x-goog-pubsub-* הכותרות ומאפייני ההודעה לא נכללים.
| פרסום | נקודת הקצה (endpoint) של הודעת ה-Push מקבלת |
|---|---|
data="{"status": "Hello there"}"
ordering_key="some-key"
attributes=
{
{"Content-Type", "application/json"}
} |
Content-Length: 25
User-Agent: CloudPubSub-Google
Host: subscription-project.uc.r.appspot.com
{"status": "Hello there"} |
הודעה לא עטופה עם מטא-נתונים של כתיבה מופעלים
בדוגמה הבאה מוצגת הודעה לא עטופה עם האפשרות 'כתיבת מטא-נתונים' מופעלת. במקרה כזה, הכותרות x-goog-pubsub-* ומאפייני ההודעה נכללים.
| פרסום | נקודת הקצה (endpoint) של הודעת ה-Push מקבלת |
|---|---|
data="{"status": "Hello there"}"
ordering_key="some-key"
attributes=
{
{"Content-Type", "application/json"}
} |
x-goog-pubsub-subscription-name: "projects/myproject/..."
x-goog-pubsub-message-id: "2070443601311540"
x-goog-pubsub-publish-time: "2021-02-26T19:13:55.749Z"
x-goog-pubsub-ordering-key: "some-key"
Content-Type: application/json
Content-Length: 12
User-Agent: CloudPubSub-Google
Host: subscription-project.uc.r.appspot.com
{"status": "Hello there"} |
הגדרת פריסת מטען ייעודי (payload)
אפשר להפעיל את האפשרות 'שליחת הודעות בדחיפה עם פתיחת המטען הייעודי (payload) של המינוי' באמצעות הדף Subscription Details במסוף Google Cloud , Google Cloud CLI או ספריות הלקוח.
המסוף
נכנסים לדף Subscriptions במסוף Google Cloud .
לוחצים על יצירת מינוי.
כותבים שם בשדה Subscription ID.
מידע על מתן שם למינוי זמין במאמר הנחיות למתן שם לנושא או למינוי.
בוחרים נושא מהתפריט הנפתח. המינוי מקבל הודעות מהנושא.
בקטע סוג המסירה, בוחרים באפשרות דחיפה.
כדי להפעיל את חילוץ המטען הייעודי (payload), בוחרים באפשרות הפעלת חילוץ המטען הייעודי.
(אופציונלי) כדי לשמור את המטא-נתונים של ההודעות בכותרת הבקשה, בוחרים באפשרות כתיבת מטא-נתונים. צריך להפעיל את האפשרות הזו כדי להגדיר כותרת Content-Type להודעות.
מציינים כתובת URL של נקודת קצה.
משאירים את כל שאר ערכי ברירת המחדל.
לוחצים על יצירה.
gcloud
כדי להגדיר מינוי עם פריקת מטען (payload) שכולל כותרות HTTP רגילות, מריצים את הפקודה הבאה של gcloud pubsub subscriptions create:
gcloud pubsub subscriptions create SUBSCRIPTION \ --topic TOPIC \ --push-endpoint=PUSH_ENDPOINT \ --push-no-wrapper
מחליפים את מה שכתוב בשדות הבאים:
-
SUBSCRIPTION: השם או המזהה של מינוי המשיכה. -
TOPIC: מזהה הנושא. PUSH_ENDPOINT: כתובת ה-URL שתשמש כנקודת הקצה של המינוי הזה. לדוגמה,https://myproject.appspot.com/myhandler.-
--push-no-wrapper: מעביר את נתוני ההודעה ישירות כגוף ה-HTTP.
כדי להגדיר מינוי עם ביטול עטיפה של מטען ייעודי (payload) ולשלוט בשימוש בכותרות x-goog-pubsub-*, מריצים את הפקודה הבאה:
gcloud pubsub subscriptions create SUBSCRIPTION \ --topic TOPIC \ --push-endpoint=PUSH_ENDPOINT \ --push-no-wrapper \ --push-no-wrapper-write-metadata
-
--push-no-wrapper-write-metadata: אם הערך הוא true, המטא-נתונים של הודעת Pub/Sub נכתבים בכותרותx-goog-pubsub-<KEY>:<VAL>של בקשת ה-HTTP. כותב את מאפייני ההודעה ב-Pub/Sub לכותרות<KEY>:<VAL>של בקשת ה-HTTP.
Python
לפני שמנסים את הדוגמה הזו, צריך לפעול לפי הוראות ההגדרה של Python במאמר תחילת העבודה: שימוש בספריות לקוח. מידע נוסף זמין במאמרי העזרה של Pub/Sub Python API.
Java
לפני שמנסים את הדוגמה הזו, צריך לפעול לפי הוראות ההגדרה של Java במאמר תחילת העבודה: שימוש בספריות לקוח. מידע נוסף מופיע במאמרי העזרה של Pub/Sub Java API.
C++
לפני שמנסים את הדוגמה הזו, צריך לפעול לפי הוראות ההגדרה של C++ במאמר תחילת העבודה: שימוש בספריות לקוח. מידע נוסף זמין במאמרי העזרה בנושא Pub/Sub C++ API.
המשך
בדוגמה הבאה נעשה שימוש בגרסה הראשית של ספריית הלקוח Go Pub/Sub (v2). אם אתם עדיין משתמשים בספרייה v1, כדאי לעיין במדריך להעברה לגרסה v2. כדי לראות רשימה של דוגמאות קוד מגרסה 1, אפשר לעיין ב דוגמאות הקוד שהוצאו משימוש.
לפני שמנסים את הדוגמה הזו, צריך לפעול לפי הוראות ההגדרה של Go במאמר מדריך למתחילים: שימוש בספריות לקוח. מידע נוסף מופיע במאמרי העזרה של Pub/Sub Go API.
Node.js
לפני שמנסים את הדוגמה הזו, צריך לפעול לפי הוראות ההגדרה של Node.js במאמר תחילת העבודה: שימוש בספריות לקוח. מידע נוסף זמין במאמר Pub/Sub Node.js API reference documentation.
Node.js
לפני שמנסים את הדוגמה הזו, צריך לפעול לפי הוראות ההגדרה של Node.js במאמר תחילת העבודה: שימוש בספריות לקוח. מידע נוסף זמין במאמר Pub/Sub Node.js API reference documentation.
הגדרת כותרת מסוג תוכן בהודעה
אחרי שמפעילים את האפשרות להסרת העטיפה של מטען הייעודי (payload), Pub/Sub לא מגדיר באופן אוטומטי שדה כותרת של סוג מדיה בבקשה. אם לא מגדירים באופן מפורש שדה כותרת Content-Type, שרת האינטרנט שמטפל בבקשה עשוי להגדיר ערך ברירת מחדל של application/octet-stream או לפרש את הבקשה באופן לא צפוי.
אם אתם צריכים להשתמש בכותרת Content-Type, אתם צריכים להצהיר עליה באופן מפורש בזמן הפרסום של כל הודעה בנפרד. כדי לעשות זאת, אתם צריכים קודם להפעיל את האפשרות כתיבת מטא-נתונים. התוצאה של הפעלת האפשרות כתיבת מטא-נתונים מוצגת בדוגמאות שסופקו.
המאמרים הבאים
- אם נתקלתם בבעיות בפירוק המטען הייעודי, כדאי לעיין במאמר בנושא פתרון בעיות בפירוק המטען הייעודי.