הגדרה של Cloud Pub/Sub

שותפים שמשתמשים במודל ה-RBM הקודם יכולים לפעול לפי ההוראות המפורטות בדף הזה כדי להגדיר את המינוי שלהם ל-Cloud Pub/Sub. ההוראות האלה לא רלוונטיות לשותפים שמשתמשים במודל RBM מבוסס-שותפים. במקום זאת, שותפים שמשתמשים במודל מבוסס-שותפים צריכים ללמוד איך להגדיר webhook.

כדי לברר באיזה דגם אתם משתמשים, פותחים את Business Communications Developer Console. אם בדף הבית מופיע ההגדרות של חשבון השותף, סימן שאתם משתמשים במודל RBM שמבוסס על שותף. אם אין לכם גישה להגדרות של חשבון השותף, אתם משתמשים במודל RBM מהדור הקודם.

סוכני RBM מקבלים הודעות ואירועים דרך קשר של פרסום/הרשמה עם Cloud Pub/Sub. כשמשתמש שולח הודעה לנציג או יוצר אירוע, אפליקציית ההודעות שלו שולחת את הפרטים למינוי Pub/Sub של הנציג, שדרכו הוא יכול לגשת להודעה או לאירוע. למידע נוסף, ראו קבלת הודעות.

סוג המינוי ל-Pub/Sub של הנציג קובע איך הנציג יקבל הודעות, ולכן צריך להגדיר את המינוי ל-Pub/Sub כדי שהנציג יוכל לקבל הודעות. סוכני RBM תומכים במינויים לpull וגם בpush.

משיכת מינוי

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

דרישות מוקדמות

לפני שמתחילים, אתם צריכים סוכן RBM.

הגדרה

1. פותחים את Business Communications Developer Console, נכנסים לחשבון Google ב-RBM ולוחצים על הנציג.
2. בחלונית הניווט הימנית, לוחצים על Integrations (שילובים).
3. לוחצים על עריכת המינוי.
4. בוחרים באפשרות Pull (שליפה) ולוחצים על Save (שמירה).
5. מגדירים את הנציג לשימוש במינוי משיכה:
   • אם אתם משתמשים בסוכן לדוגמה עם מינוי משיכה, עליכם לפעול לפי ההוראות בקובץ ה-README של הדוגמה.
   • אם אתם לא משתמשים בסוכן לדוגמה, ראו את המאמר קבלת הודעות באמצעות Pull לקוד כדי לאפשר לסוכן להשתמש במינוי למשיכה. בהתאם לשפת התכנות שלכם, יכול להיות שתצטרכו את מזהה הפרויקט של הסוכן.

איתור מזהה הפרויקט

בחלק ממנגנוני המשיכה של המינויים צריך לציין את מזהה הפרויקט ב-Google Cloud (GCP) של הסוכן. מזהה הפרויקט של הסוכן מוטמע בשם המינוי למשיכה אחרי project/.

1. פותחים את Business Communications Developer Console, נכנסים לחשבון Google ב-RBM ולוחצים על הנציג.
2. בחלונית הניווט הימנית, לוחצים על Integrations (שילובים).
3. מאתרים את שם המינוי של הסוכן.
4. יש לאתר את מקטע הטקסט בין project/ לבין / הבא. זה מזהה הפרויקט של הנציג. לדוגמה, אם שם המינוי הוא projects/rbm-growing-tree-bank-nbdjkl6t/subscriptions/rbm-agent-subscription, מזהה הפרויקט של הנציג הוא rbm-growing-tree-bank-nbdjkl6t.

C#

private async void InitPullMessages(string projectId, string jsonPath)
{
  GoogleCredential googleCredential = null;
  using (var jsonStream = new FileStream(jsonPath, FileMode.Open,
    FileAccess.Read, FileShare.Read))
  {
    googleCredential = GoogleCredential.FromStream(jsonStream)
      .CreateScoped(SubscriberServiceApiClient.DefaultScopes);
  }

  SubscriptionName subscriptionName = new SubscriptionName(projectId, subscriptionId);
  SubscriberClient subscriber = new SubscriberClientBuilder
  {
    SubscriptionName = subscriptionName,
    GoogleCredential = googleCredential

  }.Build();

  // setup listener for pubsub messages
  await subscriber.StartAsync(
    async (PubsubMessage message, CancellationToken cancel) =>
    {
      string text = System.Text.Encoding.UTF8.GetString(message.Data.ToArray());

      JObject jsonObject = JObject.Parse(jsonAsString);

      string userResponse = GetResponseText(jsonObject);
      string eventType = (string)jsonObject["eventType"];
    
      // check if the message is a user response message
      if ((userResponse.Length > 0) && (eventType == null))
      {
        string messageId = (string)jsonObject["messageId"];
        string msisdn = (string)jsonObject["senderPhoneNumber"];
        // let the user know their message has been read
        kitchenSinkBot.SendReadMessage(messageId, msisdn);
        HandleUserResponse(userResponse, msisdn);
      }
      await Console.Out.WriteLineAsync(
        $"Message {message.MessageId}: {jsonAsString}");
      return SubscriberClient.Reply.Ack;
    });
  }
}

הקוד הזה הוא קטע מתוך סוכן לדוגמה של RBM.

מינוי Push

באמצעות מינוי ל-Push, מערכת Cloud Pub/Sub מעבירה הודעות, אירועים ובקשות אחרות ל-webhook URL שציינתם.

דרישות מוקדמות

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

• סוכן של RBM
• כתובת URL פעילה של נקודת קצה (webhook) שתומכת ב-
  • HTTPS עם אישור SSL תקף
  • POST בקשות
  • יכולת ליצור הדהוד של פרמטר בתגובה לבקשת אימות

הגדרה

1. פותחים את Business Communications Developer Console, נכנסים לחשבון Google ב-RBM ולוחצים על הנציג.
2. בחלונית הניווט הימנית, לוחצים על Integrations (שילובים).
3. לוחצים על עריכת המינוי.
4. בחר באפשרות Push.
5. בשדה webhook URL של נקודת קצה (webhook), מזינים את כתובת ה-URL של התגובה לפעולה מאתר אחר (webhook) שמתחילה ב-"https://".

6. צריך להגדיר את התגובה לפעולה מאתר אחר (webhook) לקבלת בקשת POST עם הפרמטר clientToken שצוין, ולשליחת תגובת 200 OK עם הערך של הפרמטר secret.

   לדוגמה, אם התגובה לפעולה מאתר אחר (webhook) מקבלת בקשת POST עם התוכן הבא

   {
     "clientToken":"SJENCPGJESMGUFPY",
     "secret":"1234567890"
   }
   

   התגובה לפעולה מאתר אחר (webhook) צריכה לאשר את הערך clientToken, ואם הערך של clientToken תקין, יש להחזיר את התגובה 200 OK בגוף secret: 1234567890.

7. לוחצים על Verify במסוף.

   כשפלטפורמת RBM מאמתת את התגובה לפעולה מאתר אחר (webhook), תיבת הדו-שיח הגדרת התגובה לפעולה מאתר אחר (webhook) נסגרת.

8. לוחצים על שמירה.

9. מגדירים שהנציג יקבל הודעות מה-webhook:

   • אם אתם משתמשים בסוכן לדוגמה עם מינוי Push, עליכם לפעול לפי ההוראות בקובץ ה-README של הדוגמה.
   • אם לא משתמשים בסוכן לדוגמה, אפשר להגדיר את התשתית כדי להעביר הודעות מה-webhook לנציג.

Node.js

let requestBody = req.body;

if ((requestBody.hasOwnProperty('clientToken')) && (requestBody.hasOwnProperty('secret'))) {
  console.log('RBM webhook verification request');

  // Confirm that the clientToken is the one we are seeing in the RBM console
  if (requestBody.clientToken == CLIENT_TOKEN) {
    console.log('Tokens match, returning secret');
    res.status(200).send('secret: ' + requestBody.secret);
  }
  else {
    // Client tokens did not match - sending permission denied
    console.log('Tokens do not match');
    res.sendStatus(403);
  }
}

אימות הודעות נכנסות

מאחר שתגובה לפעולה מאתר אחר (webhook) יכולה לקבל הודעות מכל השולחים, חשוב לוודא ש-Google שלחה את ההודעות הנכנסות לפני עיבוד התוכן של ההודעות.

כדי לוודא ש-Google שלחה הודעה שקיבלת, בצע את השלבים הבאים:

1. חלץ את כותרת ההודעה X-Goog-Signature. זהו עותק מגובב (hash) בקידוד base64 של המטען הייעודי (payload) של גוף ההודעה.
2. פענוח של המטען הייעודי (payload) של RBM באמצעות Base-64 ברכיב message.body של הבקשה.
3. באמצעות אסימון הלקוח של ה-webhook (שציינתם כשהגדרתם את המינוי ל-push) כמפתח, יוצרים HMAC SHA512 של הבייטים של המטען הייעודי (payload) של ההודעה המפוענחת על בסיס 64 ומקודדים את התוצאה באמצעות base64.
4. משווים את הגיבוב X-Goog-Signature לגיבוב שיצרתם.
   • אם הגיבובים תואמים, וידאתם ש-Google שלחה את ההודעה.

   • אם הגיבובים לא תואמים, בדקו את תהליך הגיבוב לגבי הודעה שאתם יודעים שהיא טובה.

     אם תהליך הגיבוב (hashing) פועל כראוי וקיבלתם הודעה שלדעתכם נשלחה אליכם במרמה, תוכלו ליצור איתנו קשר.

Node.js

if ((requestBody.hasOwnProperty('message')) && (requestBody.message.hasOwnProperty('data'))) {
  // Validate the received hash to ensure the message came from Google RBM
  let userEventString = Buffer.from(requestBody.message.data, 'base64');
  let hmac = crypto.createHmac('sha512', CLIENT_TOKEN);
  let data = hmac.update(userEventString);
  let genHash = data.digest('base64');
  let headerHash = req.header('X-Goog-Signature');

  if (headerHash === genHash) {
    let userEvent = JSON.parse(userEventString);

    console.log('userEventString: ' + userEventString);
    handleMessage(userEvent);
  }
  else {
    console.log('hash mismatch - ignoring message');
  }
}

res.sendStatus(200);

השלבים הבאים

אחרי שמגדירים את המינוי ומגדירים את הנציג לתקשורת עם Cloud Pub/Sub, הנציג יכול לקבל הודעות ממכשירי הבדיקה. כדי לאמת את ההגדרה, עליכם לשלוח הודעה.