این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

وب هوک ها

وب‌هوک یک URL مشخص‌شده توسط شریک است که پلتفرم RCS for Business پیام‌ها و رویدادها را در آن ارسال می‌کند. این URL به عنوان یک نقطه پایانی عمل می‌کند که درخواست‌های HTTPS POST حاوی داده‌های مربوط به رویدادها را دریافت می‌کند. این بدان معناست که داده‌ها به طور ایمن از طریق HTTPS به برنامه شما ارسال می‌شوند.

یک آدرس اینترنتی وب‌هوک ممکن است چیزی شبیه به این باشد: https://[your company name].com/api/rbm-events . پس از پیکربندی وب‌هوک، می‌توانید پیام‌ها و رویدادها را دریافت کنید.

وب‌هوک‌های شریک و وب‌هوک‌های نماینده

شما می‌توانید وب‌هوک خود را در سطح همکار یا در سطح نماینده پیکربندی کنید.

وب‌هوک شریک شما برای هر ایجنتی که نگهداری می‌کنید اعمال می‌شود. اگر ایجنت‌های شما رفتار مشابهی دارند، یا اگر فقط یک ایجنت دارید، از وب‌هوک شریک استفاده کنید.
وب‌هوک‌های عامل برای عامل‌های منفرد اعمال می‌شوند. اگر چندین عامل با رفتار متمایز را مدیریت می‌کنید، می‌توانید برای هر عامل یک وب‌هوک متفاوت تنظیم کنید .

اگر هم وب‌هوک همکار و هم وب‌هوک عامل را پیکربندی کرده باشید، وب‌هوک عامل بر عامل خاص خود اولویت دارد، در حالی که وب‌هوک شریک برای هر عاملی که وب‌هوک مخصوص به خود را ندارد اعمال می‌شود.

پیکربندی وب‌هوک عامل

شما پیام‌های ارسالی به نماینده خود را در وب‌هوک همکارتان دریافت می‌کنید. اگر می‌خواهید پیام‌های یک نماینده خاص به وب‌هوک دیگری ارسال شود، یک وب‌هوک برای نماینده تنظیم کنید.

کنسول توسعه‌دهندگان ارتباطات تجاری را باز کنید و با حساب گوگل شریک RCS for Business خود وارد سیستم شوید.
روی نماینده خود کلیک کنید.
روی ادغام‌ها کلیک کنید.
برای وب‌هوک ، روی پیکربندی کلیک کنید.
برای آدرس اینترنتی نقطه پایانی وب‌هوک ، آدرس اینترنتی وب‌هوک خود را که با "https://" شروع می‌شود، وارد کنید.
مقدار clientToken خود را یادداشت کنید. برای تأیید اینکه پیام‌های دریافتی از Google می‌آیند، به آن نیاز دارید.
وب‌هوک خود را طوری پیکربندی کنید که یک درخواست POST با پارامتر clientToken مشخص شده را بپذیرد و یک پاسخ 200 OK با مقدار متن ساده پارامتر secret به عنوان بدنه پاسخ ارسال کند.
برای مثال، اگر وب‌هوک شما یک درخواست POST با محتوای بدنه زیر دریافت کند
```
{
  "clientToken":"SJENCPGJESMGUFPY",
  "secret":"1234567890"
}
```
سپس وب‌هوک شما باید مقدار clientToken را تأیید کند و اگر clientToken صحیح باشد، یک پاسخ 200 OK با 1234567890 به عنوان بدنه پاسخ برگرداند:
```
// clientToken from Configure
const myClientToken = "SJENCPGJESMGUFPY";

// Example endpoint
app.post("/rbm-webhook", (req, res) => {
  const msg = req.body;
  if (msg.clientToken === myClientToken) {
      res.status(200).send(msg.secret);
      return;
  }
  res.send(400);
});
```
در کنسول توسعه‌دهندگان، روی تأیید کلیک کنید. وقتی RCS for Business وب‌هوک شما را تأیید کرد، پنجره بسته می‌شود.

تأیید پیام‌های دریافتی

از آنجا که وب‌هوک‌ها می‌توانند از هر فرستنده‌ای پیام دریافت کنند، باید قبل از پردازش محتوای پیام، تأیید کنید که گوگل پیام‌های دریافتی را ارسال کرده است.

برای تأیید اینکه گوگل پیامی را که دریافت کرده‌اید ارسال کرده است، این مراحل را دنبال کنید:

هدر X-Goog-Signature پیام را استخراج کنید. این یک کپی هش شده و کدگذاری شده با base64 از محتوای بدنه پیام است.
کد RCS for Business را در عنصر message.body درخواست، با استفاده از Base-64 رمزگشایی کنید.
با استفاده از توکن کلاینت وب‌هوک خود (که هنگام تنظیم وب‌هوک مشخص کرده‌اید) به عنوان کلید، یک SHA512 HMAC از بایت‌های پیام رمزگشایی‌شده‌ی base-64 ایجاد کنید و نتیجه را base64-encode کنید.
هش X-Goog-Signature را با هشی که ایجاد کرده‌اید مقایسه کنید.
- اگر هش‌ها مطابقت داشته باشند، شما تأیید کرده‌اید که گوگل پیام را ارسال کرده است.
- اگر هش‌ها مطابقت ندارند، فرآیند هش کردن خود را روی یک پیام شناخته‌شده و بدون مشکل بررسی کنید.
  اگر فرآیند هش کردن شما به درستی کار می‌کند و پیامی دریافت می‌کنید که معتقدید به صورت جعلی برای شما ارسال شده است، با ما تماس بگیرید .

نود جی اس

  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);

مدیریت پیام

برگرداندن هر چیزی غیر از 200 OK از یک وب‌هوک، به عنوان شکست در تحویل (delivery failure) در نظر گرفته می‌شود.

توسعه‌دهندگان باید توجه داشته باشند که ارسال پیام‌ها با نرخ بالا، اعلان‌های وب‌هوک را با نرخ بالا ایجاد می‌کند و باید کد خود را طوری طراحی کنند که اعلان‌ها را با نرخ مورد انتظار مدیریت کند. برای توسعه‌دهندگان مهم است که موقعیت‌هایی را که ممکن است باعث پاسخ‌های ناموفق شوند - از جمله 500 پاسخ از کانتینر وب، وقفه‌های زمانی یا خرابی‌های بالادستی - در نظر بگیرند. مواردی که باید در نظر گرفته شوند عبارتند از:

تأیید کنید که محافظت‌های DDoS شما برای مدیریت نرخ مورد انتظار اعلان‌های وب‌هوک پیکربندی شده‌اند.
تأیید کنید که منابعی مانند مجموعه‌های اتصال پایگاه داده، تمام نشوند و باعث وقفه یا پاسخ‌های 500 نشوند.

توسعه‌دهندگان باید سیستم‌های خود را طوری طراحی کنند که پردازش رویدادهای RBM به صورت غیرهمزمان انجام شود و مانع از بازگشت 200 OK توسط وب‌هوک نشود.

پردازش ناهمزمان وب هوک

مهم است که رویداد RBM را درون خود وب‌هوک پردازش نکنید . هرگونه خطا یا تأخیر در طول پردازش ممکن است بر کد برگشتی وب‌هوک تأثیر بگذارد:

پردازش وب هوک همزمان

رفتار در هنگام عدم تحویل

اگر وب‌هوک شما چیزی غیر از وضعیت 200 OK را برگرداند، پلتفرم RCS for Business از مکانیزم backoff و retry برای تحویل مجدد داده‌ها استفاده می‌کند. این بدان معناست که سیستم به تدریج تأخیر بین هر تلاش برای تحویل را افزایش می‌دهد و در نهایت به حداکثر فرکانس یک تلاش مجدد هر ۱۰ دقیقه برای هر پیام در حال انتظار می‌رسد. چرخه تلاش مجدد به مدت هفت روز ادامه می‌یابد و پس از آن پیام به طور دائم حذف می‌شود.

پیامدهای وب‌هوک‌های سطح عامل

RCS برای کسب و کار، پیام‌های یک شریک را در یک صف قرار می‌دهد. همه نمایندگان تحت یک حساب کاربری شریک، یک صف مشترک دارند. به همین دلیل، خرابی در یک وب‌هوک می‌تواند کل صف را مسدود کند و از رسیدن رویدادهای کاربری برای همه نمایندگان به شریک جلوگیری کند.

چندین پیام تأیید نشده می‌توانند باعث افزایش شدید رویدادهای تلاش مجدد شوند. برای مثال، اگر یک اپراتور ۱۶۰۰ رسید تحویل را تأیید نکند و فرکانس تلاش مجدد به حد مجاز ۱۰ دقیقه برسد، می‌تواند تقریباً ۲۳۰،۰۰۰ خطای احتمالی در روز ایجاد کند:

۱۶۰۰ پیام × ۶ تلاش مجدد در ساعت × ۲۴ ساعت در روز = تقریباً ۲۳۰۰۰۰ خطا در روز

این حجم از تلاش‌های مجدد می‌تواند صف Pub/Sub مشترک را مسدود کند و باعث تأخیرهای قابل توجهی در دریافت رویدادهای کاربر برای همه کمپین‌های یک شریک شود.

بهترین شیوه‌ها

برای تضمین قابلیت اطمینان ترافیک عملیاتی خود و جلوگیری از مسدود شدن صف، این بهترین شیوه‌ها را دنبال کنید:

فوراً مقدار 200 OK را برگردانید : وب‌هوک باید پیام را دریافت کند، آن را در یک صف محلی ذخیره کند و در کمتر از پنج ثانیه پاسخ 200 OK را برگرداند.
پردازش مجزا : از کارگران پس‌زمینه جداگانه برای پردازش منطق پیام از صف محلی استفاده کنید.
نظارت بر عامل‌های تست : با عامل‌های توسعه مانند عامل‌های تولید رفتار کنید، زیرا آنها نیز می‌توانند در صورت عدم موفقیت، صف مشترک شرکا را مسدود کنند.
حساب‌های کاربری اختصاصی برای آزمایش : ترجیحاً از یک حساب کاربری توسعه‌دهنده برای عوامل تولید و یک حساب کاربری توسعه‌دهنده اختصاصی برای عوامل آزمایش استفاده کنید.
ترافیک گوگل را تأیید کنید : از DNS معکوس یا هدر X-Goog-Signature به جای لیست کردن IP ثابت استفاده کنید، زیرا گوگل از IPهای پویای Anycast استفاده می‌کند. برای اطلاعات بیشتر در مورد تأیید دستی و شناسایی محدوده‌های IP گوگل، به مستندات درخواست‌های Verify Google و به طور خاص فایل‌های JSON برای دریافت‌کننده‌های فعال‌شده توسط کاربر و دریافت‌کننده‌های فعال‌شده توسط کاربر گوگل مراجعه کنید.

مراحل بعدی

پس از پیکربندی وب‌هوک، عامل شما می‌تواند پیام‌هایی را از دستگاه‌های آزمایشی شما دریافت کند. برای تأیید تنظیمات خود، پیامی ارسال کنید .

بعدی

Dialogflow