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

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

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

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

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

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

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

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

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

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

لطلب إشعارات الردّ التلقائي على الويب، حدِّد القيم التالية في الكائن 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"
  }
}

معالجة إشعارات الويب هوك

يحتوي طلب 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".