دریافت اعلان‌های وب‌قلاب برای فهرست‌های مخاطبان

این راهنما توضیح می‌دهد که چگونه از وب‌قلاب‌ها برای دریافت اعلان‌های ناهمگام برای وضعیت درخواست‌های صادر کردن مخاطب استفاده کنید. این ویژگی فقط در نسخه v1alpha از Data API دردسترس است.

اعلان‌های وب‌قلاب ویژگی پیشرفته‌ای از Google Analytics Data API است. برای آشنایی با ویژگی صادر کردن مخاطب، ایجاد صادر کردن مخاطب را ببینید.

بدون وب‌قلاب‌ها، باید به‌طور دوره‌ای میانای برنامه‌سازی کاربردی را نظرسنجی کنید تا مشخص شود چه زمانی درخواست تکمیل می‌شود.

ایجاد کردن برنامه وب‌قلاب نمونه بااستفاده از Cloud Run

با دنبال کردن آموزش شروع سریع: استقرار سرویس نمونه در Cloud Run می‌توانید بااستفاده از Google Cloud یک برنامه وب‌قلاب نمونه ایجاد کنید.

برای اینکه سرویس نمونه بتواند به درخواست‌های اعلان POST webhook گوش دهد، فایل 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 مستقر کردید، نشانی وبی را که سرویس شما در آن مستقر شده است ذخیره کنید.

نشانی وب سرویس در کنسول نمایش داده می‌شود، برای مثال:

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

این URI اعلان سرور است که برنامه‌تان ازطریق آن به اعلان‌های وب‌قلاب از Google Analytics گوش می‌دهد.

فهرست مخاطبان ایجاد کنید و اعلان‌های وب‌قلاب را روشن کنید

برای درخواست اعلان‌های وب‌هوک، مقادیر زیر را در شیء webhookNotification مشخص کنید:

  • URI اعلان سرور حاوی نشانی وب که اعلان‌های وب‌قلاب را دریافت خواهد کرد.

  • (اختیاری) رشته‌ای دلخواه channelToken برای محافظت دربرابر جعل پیام. channelToken را در سرصفحه HTTP X-Goog-Channel-Token درخواست POST وب‌هوکی مشخص کنید.

در اینجا یک درخواست نمونه بااستفاده از وب‌قلاب‌ها آورده شده است:

درخواست اچ‌تی‌تی‌پی

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 است که تأیید می‌کند وب‌قلاب مشخص‌شده با موفقیت در کمتر از ۵ ثانیه پاسخ داده است.

در اینجا یک پاسخ نمونه آورده شده است:

پاسخ 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"
    }
  }
}

اگر وب‌قلاب پاسخ ندهد یا نشانی وب سرویس نادرستی ارائه دهید، پیام خطا برگردانده می‌شود.

در اینجا نمونه‌ای از خطایی که ممکن است دریافت کنید آورده شده است:

{
  "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 Analytics را ببینید.