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

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

إشعارات Webhook هي ميزة متقدّمة في 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. في حال تعذّر تنفيذ الطلب الأول إلى 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".