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

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

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

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

إنشاء نموذج لتطبيق ردّ تلقائي على الويب باستخدام 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 للإشارة إلى العملية الناجحة.

بعد الوصول إلى نهاية الدليل التوجيهي للبدء السريع في Cloud Run ونشر تطبيق الرد التلقائي على الويب باستخدام الأمر 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 للردّ التلقائي على الويب.

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

طلب HTTP

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 ثوانٍ.

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

استجابة HTTP

{
  "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. يحدّد الطابع الزمني المُرسَل وقت حقبة Unix بالميكرو ثانية التي تم إرسال الطلب فيها. ويمكنك استخدام هذا الطابع الزمني لتحديد الإشعارات التي تمت إعادة تشغيلها

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

  1. يتم إرسال طلب 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".