התראות Pub/Sub

  • חשוב להשלים את ה-Codelab בנושא הגדרת API כדי להגדירGoogle Cloud פרויקט וליצור חשבון שירות להפעלת Cloud Channel API.

  • מומלץ להשתמש במסוף Partner Sales לניסויים לצורך ה-codelab הזה.

  • מומלץ להכיר את המושגים של Pub/Sub.

סקירה כללית

‫Cloud Channel API משתמש ב-Pub/Sub כדי לשלוח התראות על אירועים שונים שקשורים ללקוחות ולזכויות.

האפשרות הזו שימושית במיוחד ל:

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

ההגדרה של Pub/Sub כוללת את שלושת השלבים הבאים:

  1. מפעילים את Pub/Sub API ומכינים את חשבון השירות.

  2. יוצרים נושא Pub/Sub. הנושא הזה הוא בבעלות Channel Services, ותצטרכו לציין חשבון שירות שיכול ליצור מינוי.

  3. יוצרים מינוי ל-Pub/Sub. אפשר לדחוף את המינוי הזה באמצעות Webhooks (השיטה המומלצת) או למשוך אותו.

במינוי push, מארחים webhook שמקבל את האירועים שמופקים על ידי שירותי הערוץ:

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

פורמט ההתראות

בהמשך מופיעה דוגמה להתראת Pub/Sub. נתוני ההודעה מועברים כמחרוזת JSON בקידוד base64. 

{
  "message": {
    "attributes": {
      "event_type": "LICENSE_ASSIGNMENT_CHANGED",
      "subscriber_event_type": "ENTITLEMENT_EVENT"
    },
    "data": "eyJlbnRpdGxlbWVudF9ldmVudCI6eyJldmVudF90eXBlIjoiTElDRU5TRV9BU1NJR05NRU5UX0NIQU5HRUQiLCJlbnRpdGxlbWVudCI6ImFjY291bnRzL0MwMTIzNDU2L2N1c3RvbWVycy9TMDEyMzQ1NjcvZW50aXRsZW1lbnRzL1NhYmNkZWYxMjM0NSJ9fQ==",
    "message_id": 1918124788439510,
    "publish_time": "2021-01-14T01:23:45.678Z"
  },
  "subscription": "projects/project/subscriptions/channel-pubsub-test"
}

אלה אותם נתוני הודעה, אחרי פענוח:

{
  "entitlement_event": {
    "event_type": "LICENSE_ASSIGNMENT_CHANGED",
    "entitlement": "accounts/C0123456/customers/S01234567/entitlements/Sabcdef12345"}
  }
}

שלב 1: הפעלת Pub/Sub API והכנת חשבון השירות

כדי להפעיל את ה-codelab הזה, אתם צריכים:

  • כתובת האימייל של חשבון שירות בפרויקט. הכתובת תיראה כך: service-account@project.iam.gserviceaccount.com.
  • גישה לחשבון סופר-אדמין בדומיין של מפיץ (רצוי דרך Partner Sales Console לניסיון).
  • מזהה החשבון. אפשר למצוא את זה בהגדרות של Partner Sales Console.

כדי להכין את חשבון השירות:

  • נכנסים לקטע API Library במסוף Google Cloud ומפעילים את Pub/Sub API.
  • מקצים לחשבון השירות את תפקיד ה-IAM של Pub/Sub בפרויקט. ההרשאה roles/pubsub.editor (שם התפקיד = Pub/Sub Editor) מספיקה לשיעור Codelab הזה, אבל יכול להיות שתרצו להשתמש בהרשאות מפורטות יותר בשילוב שלכם בסביבת הייצור. פרטים מלאים על תפקידים ב-IAM זמינים בדף בקרת גישה ל-Pub/Sub.
  • אם אתם בוחרים להשתמש בתפקיד בהתאמה אישית, אתם צריכים להעניק לתפקיד הזה את ההרשאה pubsub.subscriptions.create ליצירת מינויים.

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

שלב 2: יצירת הנושא בחשבון

כדי ליצור את נושא Pub/Sub, צריך להשתמש ב-method ‏accounts.register. השיטה הזו מקבלת כפרמטר כתובת האימייל בחשבון שירות. רק חשבונות שירות שאושרו באמצעות השיטה הזו יכולים להירשם לנושא החדש.

  1. עוברים לתיעוד של accounts.register ולוחצים על Try it!‎.
  2. בשדה account, מזינים accounts/ACCOUNT_ID ומחליפים את ACCOUNT_ID במספר החשבון.
  3. לוחצים על Add request body parameters (הוספת פרמטרים של גוף הבקשה), בוחרים באפשרות serviceAccount ומזינים את כתובת האימייל בחשבון השירות.
  4. לוחצים על Execute (הפעלה) ומוודאים שאתם מחוברים כסופר-אדמין בדומיין של המפיץ.

אמורה להתקבל תגובה עם קוד 200 שדומה לזו:

{
  "topic": "projects/cloud-channel-pubsub/topics/C0123456-notify"
}

זהו נושא ה-Pub/Sub שבו יפורסמו האירועים.

שלב 3: נרשמים לנושא

אחרי שיוצרים את נושא Pub/Sub, צריך להגדיר איך האפליקציה צורכת אירועי שינוי. יש שתי אפשרויות:

  • מינוי Push: אתם מספקים קריאה חוזרת (callback) מסוג HTTP POST. מערכת Pub/Sub תשתמש בזה כדי לשלוח לאפליקציה התראות על אירועים חדשים.
  • מינוי מסוג pull: האפליקציה שלכם מבצעת מעת לעת קריאות HTTP כדי לקבל שינויים בתור.

בשיעור ה-Codelab הזה נשתמש ב-Push ונשלח את כל האירועים לפונקציית Cloud Run שתתעד אותם ב-Cloud Logging.

שליחת התראות של שירותי ערוצים לפונקציית Cloud Run

שלב 3א: יצירת פונקציית Cloud Run

בשלב הזה ניצור פונקציית Cloud Run שתתעד ביומן את ההודעות שהתקבלו.

  1. נכנסים לקטע Cloud Run functions במסוףGoogle Cloud . יכול להיות שתצטרכו להפעיל את Cloud Run functions API.
  2. לוחצים על Create Function (יצירת פונקציה).
  3. במסך הגדרות:
    1. משנים את שם הפונקציה. אפשר גם לבחור אזור אחר.
    2. בטריגר HTTP, משנים את האימות לאפשר הפעלות לא מאומתות ולוחצים על שמירה.
    3. רושמים את כתובת ה-URL של הטריגר. תצטרכו אותו בשלב הבא.
    4. לוחצים על הבא.

  4. במסך קוד:

    1. בחירת סביבת זמן ריצה של Node.js
    2. משנים את Entry point ל-log.
    3. בקובץ index.js, מחליפים את הקוד לדוגמה בקוד הבא:
    exports.log = (req, res) => {
  if (req.body && req.body.message) {
    console.log(req.body);
    const message = req.body.message;
    // data is base64-encoded JSON
    const data = new Buffer.from(message.data, 'base64').toString();
    console.log(data);
  }
  res.status(200).send('OK');
};

אפשר להמשיך לשלב הבא בזמן שפונקציית Cloud Run נפרסת.

שלב 3ב: יצירת המינוי

רק חשבונות שירות שנרשמו לנושא Channel Services (ראו שלב 2) יכולים ליצור מינוי.

אפשר לעשות זאת באמצעות קוד על ידי קריאה ל-Pub/Sub API עם פרטי הכניסה של חשבון השירות. חשוב לוודא שאתם לא מתחזים לאדמין העל של הדומיין של המפיץ שלכם – זה נדרש כשמפעילים את Cloud Channel API.

לצורך שיעור התכנות הזה, תשתמשו בכלי gcloud CLI ב-Cloud Shell.

  1. לוחצים על Activate Cloud Shell (הפעלת Cloud Shell) בחלק העליון של Google Cloud console.

  2. אחרי שהמעטפת מוכנה, מריצים את הפקודה הבאה. מחליפים את הערכים של SERVICE_ACCOUNT בכתובת האימייל של חשבון השירות, את TOPIC בנושא שנוצר בשלב 2 ואת PUSH_ENDPOINT בכתובת ה-URL של הטריגר של פונקציית Cloud Run שנוצרה בשלב 3א:

    SERVICE_ACCOUNT=service-account@project.iam.gserviceaccount.com
TOPIC=projects/cloud-channel-pubsub/topics/C0123456-notify
PUSH_ENDPOINT=https://us-central1-project.cloudfunctions.net/pubsub

  3. מפעילים את חשבון השירות במעטפת:

    gcloud iam service-accounts keys create sa-keys.json \
    --iam-account=$SERVICE_ACCOUNT
gcloud auth activate-service-account --key-file=sa-keys.json

  4. יוצרים את המינוי:

    gcloud pubsub subscriptions create channel-pubsub-test \
    --topic=$TOPIC \
    --push-endpoint=$PUSH_ENDPOINT

כדי לוודא שהמינוי הוגדר, עוברים אל הקטע Pub/Sub subscriptions.

יצירת נתונים

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

הדרך הכי פשוטה היא ליצור לקוח במסוף תוכנית המכירות של שותפי YouTube ולהקצות לו מוצר. אם סיימתם את ה-Codelab בנושא הקצאת משתמשים ב-Workspace מקצה לקצה, תוכלו ליצור לקוח עם Google Workspace על ידי הפעלת קוד לדוגמה.

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

דוגמאות ליומנים של אירועים ב-Pub/Sub

הסרת המשאבים

  • מחיקת פונקציית Cloud Run
  • מחיקת המינוי

הנושא ינוקה באופן אוטומטי כשלא יישארו בו מנויים.

השלבים הבאים

בשיעור Codelab הזה למדתם איך שירותי הערוצים משתמשים ב-Pub/Sub כדי לאפשר לכם ליצור שילוב באופן תגובתי, ובקנה מידה גדול.

מידע על אירועים

בהפניה ל-RPC מופיעה רשימה של האירועים שנוצרים על ידי Channel Services.

הפניית API

בשיעור Codelab הזה נעשה שימוש במסוף Google Cloud , אבל אפשר לבצע את השלבים האלה באופן פרוגרמטי. כדי לעשות את זה:

התחייבויות ושיטות מומלצות לשימוש ב-Pub/Sub

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

שיטות מומלצות לשימוש בנקודות קצה של Push:

  • יכול להיות שההודעות יתעכבו, יישלחו לא לפי הסדר או יישלחו כמה פעמים, ולכן נקודת הקצה צריכה להיות אידמפוטנטית ולהשתמש ב-customers.get וב-entitlements.get

  • זמן הקצוב לתפוגה (timeout) שמוגדר כברירת מחדל ב-Pub/Sub לשליחת הודעות הוא 10 שניות (אפשר להגדיל את הזמן הזה דרך ackDeadline במינוי ל-Pub/Sub), אבל מומלץ להשתמש בארכיטקטורה מבוססת-הודעות ולגרום לנקודת הקצה להגיב כמה שיותר מהר.

  • אם נקודת הקצה מושבתת או מחזירה שגיאות 5xx, ‏ Pub/Sub ינסה שוב. מידע נוסף על קבלת הודעות באמצעות Push זמין במסמכי התיעוד של Pub/Sub.

אם אתם מעדיפים להשתמש בשיטת pull, תוכלו למצוא מידע על קבלת הודעות באמצעות pull במסמכי Pub/Sub.

סינון אירועים

ההתראות של Channel Services כוללות את attributes, ולכן אפשר ליצור מינויים מפורטים באמצעות יצירה של מינויים ספציפיים ל-Pub/Sub עם סינון Pub/Sub.

לדוגמה, סינון באמצעות attributes.event_type = "LICENSE_ASSIGNMENT_CHANGED" מאפשר לעקוב אחרי כל השינויים במספר המושבים ב-Google Workspace.