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

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

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

بدون خطافات الويب، عليك إجراء استطلاع دوري لواجهة برمجة التطبيقات لتحديد وقت اكتمال الطلب.

إنشاء نموذج لتطبيق webhook باستخدام Cloud Run

يمكنك إنشاء نموذج لتطبيق webhook باستخدام Google Cloud باتّباع البرنامج التعليمي البدء السريع: نشر خدمة نموذجية على 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 ونشر تطبيق webhook باستخدام الأمر gcloud run deploy، احفظ عنوان URL الذي تم نشر خدمتك فيه.

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

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

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

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

لطلب تلقّي إشعارات عبر Webhook، حدِّد القيم التالية في عنصر webhookNotification:

إليك نموذج طلب باستخدام ويب هوك:

طلب 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"
  }
}

معالجة إشعارات Webhook

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

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