تلقّي إشعارات الردّ التلقائي على الويب لقوائم المستخدمين

يوضِّح هذا الدليل كيفية استخدام الردود التلقائية على الويب لتلقّي إشعارات غير متزامنة. لمعرفة حالة طلبات تصدير شرائح الجمهور هذه الميزة متاحة فقط في الإصدار v1alpha من Data API.

إشعارات الرد التلقائي على الويب من الميزات المتقدمة في بيانات "إحصاءات Google" API. للحصول على مقدمة عن تصدير شرائح الجمهور، اطّلِع على إنشاء عملية تصدير شرائح جمهور.

بدون الردود التلقائية على الويب، ستحتاج إلى استطلاع واجهة برمجة التطبيقات بشكل دوري من أجل وتحديد وقت اكتمال الطلب.

إنشاء نموذج لتطبيق ردّ تلقائي على الويب باستخدام Cloud Run

يمكنك إنشاء نموذج لتطبيق ردّ تلقائي على الويب باستخدام Google Cloud من خلال اتّباع الخطوات التالية: الدليل التوجيهي Quickstart: نشر نموذج خدمة على Cloud Run.

لكي يستمع نموذج الخدمة إلى طلبات إشعار الرد التلقائي على الويب POST، استبدل ملف index.js من الدليل التوجيهي الخاص بالبدء السريع بما يلي الرمز:

  import express from 'express';

  const app = express();
  app.use(express.json());

  app.post('/', (req, res) => {
    const channelToken = req.get('X-Goog-Channel-Token');
    const bodyJson = JSON.stringify(req.body);

    console.log(`channel token: ${channelToken}`);
    console.log(`notification body: ${bodyJson}`);

    res.sendStatus(200);
  });

  const port = parseInt(process.env.PORT) || 8080;
  app.listen(port, () => {
    console.log(`helloworld: listening on port ${port}`);
  });

تتم طباعة هذا الرمز عند إرسال كل إشعار ردّ تلقائي وارد على الويب يتم إرساله كطلب POST إزالة نص JSON لإشعار الرد التلقائي على الويب وقيمة الرمز المميّز للقناة عرض رمز HTTP 200 للإشارة إلى العملية الناجحة.

عند الوصول إلى نهاية الدليل التوجيهي حول التشغيل السريع في السحابة الإلكترونية ونشره تطبيق الرد التلقائي على الويب باستخدام الأمر gcloud run deploy، احفظ عنوان URL حيث تم نشر الخدمة.

يتم عرض عنوان URL للخدمة في وحدة التحكّم، على سبيل المثال:

  Service URL: https://webhooks-test-abcdef-uc.a.run.app

هذا هو معرّف الموارد المنتظم (URI) لإشعارات الخادم الذي يستمع إليه التطبيق إلى إشعارات الرد التلقائي على الويب إحصاءات Google

إنشاء قائمة مستخدمين وتفعيل إشعارات الرد التلقائي على الويب

لطلب إشعارات الردّ التلقائي على الويب، حدِّد القيم التالية في webhookNotification الكائن:

• معرّف الموارد المنتظم (URI) لإشعارات الخادم يحتوي على عنوان الويب الذي سيتلقى إشعارات الرد التلقائي على الويب.

• (اختياري) سلسلة عشوائية channelToken للحماية من انتحال هوية الرسالة. تحديد channelToken في عنوان HTTP يتضمّن العنصر X-Goog-Channel-Token طلب POST للردّ التلقائي على الويب.

في ما يلي نموذج طلب باستخدام الردود التلقائية على الويب:

POST https://analyticsdata.googleapis.com/v1alpha/properties/1234567/audienceLists
{
  "webhookNotification": {
    "uri": "https://webhooks-test-abcdef-uc.a.run.app",
    "channelToken": "123456"
  },
  "audience": "properties/1234567/audiences/12345",
  "dimensions": [
    {
      "dimensionName": "deviceId"
    }
  ]
}

تحتوي الاستجابة من طريقة audienceLists.create على webhookNotification، مما يؤكد نجاح الرد التلقائي المحدّد على الويب استجابت في أقل من 5 ثوانٍ.

إليك نموذج الرد:

{
  "response": {
    "@type": "type.googleapis.com/google.analytics.data.v1alpha.AudienceList",
    "name": "properties/1234567/audienceLists/123",
    "audience": "properties/1234567/audiences/12345",
    "audienceDisplayName": "Purchasers",
    "dimensions": [
      {
        "dimensionName": "deviceId"
      }
    ],
    "state": "ACTIVE",
    "beginCreatingTime": "2024-06-10T04:50:09.119726379Z",
    "creationQuotaTokensCharged": 51,
    "rowCount": 13956,
    "percentageCompleted": 100,
    "webhookNotification": {
      "uri": "https://webhooks-test-abcdef-uc.a.run.app",
      "channelToken": "123456"
    }
  }
}

في حال عدم استجابة الرد التلقائي على الويب، أو في حال تقديم عنوان URL غير صحيح للخدمة، فسيتم إرجاع رسالة خطأ بدلاً من ذلك.

في ما يلي مثال على رسالة الخطأ التي قد تظهر لك:

{
  "error": {
    "code": 400,
    "message": "Expected response code of 200 from webhook URI but instead
    '404' was received.",
    "status": "INVALID_ARGUMENT"
  }
}

معالجة إشعارات الرد التلقائي على الويب

يحتوي طلب POST إلى خدمة الرد التلقائي على الويب على كل من إصدار JSON من مو��د ��ن ال��ملي��ت ال��ي تستغرق وقتًا طويلاً في النص الأساسي، والحقل sentTimestamp. يحدّد الطابع الزمني المُرسَل وقت حقبة يونكس بالميكرو ثانية التي تم فيها إرسال الطلب. يمكنك استخدام هذه الصفحة طابع زمني لتحديد الإشعارات التي تمت إعادة تشغيلها.

يتم إرسال طلب أو طلبين من طلبات POST إلى الرد التلقائي على الويب أثناء إنشاء قائمة المستخدمين:

1. يتم إرسال طلب POST الأول على الفور، مع عرض طلب POST الذي تم إنشاؤه حديثًا قائمة المستخدمين في حالتها CREATING. إذا لم يقدم الطلب الأول إلى تعذّر الرد التلقائي على الويب، تعرض عملية audienceLists.create خطأ وتفاصيل تعذُّر الرد التلقائي على الويب.
2. يتم إرسال طلب POST الثاني بعد اكتمال قائمة المستخدمين الإنشاء. تكتمل عملية الإنشاء عندما تصل قائمة المستخدمين إلى أيّ مما يلي: حالة ACTIVE أو FAILED.

في ما يلي مثال على الإشعار الأول لقائمة مستخدمين، في ولاية CREATING:

  {
    "sentTimestamp":"1718261355692983",
    "name": "properties/1234567/audienceLists/123",
    "audience": "properties/1234567/audiences/12345",
    "audienceDisplayName":"Purchasers",
    "dimensions":[{"dimensionName":"deviceId"}],
    "state":"CREATING",
    "beginCreatingTime": "2024-06-10T04:50:09.119726379Z",
    "creationQuotaTokensCharged":0,
    "rowCount":0,
    "percentageCompleted":0,
    "webhookNotification":
      {
        "uri": "https://webhooks-test-abcdef-uc.a.run.app",
        "channelToken":"123456"
      }
  }

في ما يلي مثال على الإشعار الثاني لقائمة مستخدمين في ولاية ACTIVE:

  {
    "sentTimestamp":"1718261355692983",
    "name": "properties/1234567/audienceLists/123",
    "audience": "properties/1234567/audiences/12345",
    "audienceDisplayName":"Purchasers",
    "dimensions":[{"dimensionName":"deviceId"}],
    "state":"ACTIVE",
    "beginCreatingTime": "2024-06-10T04:50:09.119726379Z",
    "creationQuotaTokensCharged":68,
    "rowCount":13956,
    "percentageCompleted":100,
    "webhookNotification":
      {
        "uri": "https://webhooks-test-abcdef-uc.a.run.app",
        "channelToken":"123456"
      }
  }

يؤكد الإشعار الثاني أنه قد تم إنشاء قائمة المستخدمين وأنها جاهز للاستعلام باستخدام audienceLists.query .

لاختبار الردود التلقائية على الويب بعد طلب طريقة audienceLists.create، يمكنك: فحص السجلات لنموذج تطبيق الردّ التلقائي على الويب في Cloud Run، والاطّلاع على نص JSON لكل إشعار أرسلته "إحصاءات Google"