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

يوضّح هذا الدليل كيفية استخدام خطافات الويب لتلقّي إشعارات غير متزامنة بشأن حالة طلبات تصدير شرائح الجمهور. تتوفّر هذه الميزة فقط في الإصدار 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. يحدّد الطابع الزمني لوقت الإرسال وقت حقبة Unix بالميكروثانية الذي تم فيه إرسال الطلب. يمكنك استخدام هذا الطابع الزمني لتحديد الإشعارات التي تم تشغيلها مرة أخرى.

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

  1. يتم إرسال طلب POST الأول على الفور، ما يؤدي إلى عرض قائمة المستخدمين التي تم إنشاؤها حديثًا في حالتها CREATING. إذا تعذّر تنفيذ الطلب الأول إلى webhook، ستعرض العملية audienceLists.create خطأً وتفاصيل تعذّر تنفيذ webhook.
  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".