این راهنما نحوه استفاده از وبهوکها را برای دریافت اعلانهای ناهمزمان در مورد وضعیت درخواستهای خروجی مخاطبان شما توضیح میدهد. این ویژگی فقط در نسخه v1alpha از Data API در دسترس است.
اعلانهای وبهوک یک ویژگی پیشرفته از API دادههای گوگل آنالیتیکس هستند. برای آشنایی با ویژگی خروجی مخاطب، به بخش «ایجاد خروجی مخاطب» مراجعه کنید.
بدون وبهوکها، شما باید به صورت دورهای از API نظرسنجی کنید تا مشخص شود چه زمانی یک درخواست کامل شده است.
با استفاده از Cloud Run یک برنامه وب هوک نمونه ایجاد کنید
شما میتوانید با دنبال کردن آموزش « شروع سریع: استقرار یک سرویس نمونه در Cloud Run» یک برنامه وبهوک نمونه با استفاده از Google Cloud ایجاد کنید.
برای اینکه سرویس نمونه به درخواستهای اعلان وبهوک 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 جایی که سرویس شما مستقر شده است را ذخیره کنید.
آدرس اینترنتی سرویس در کنسول نمایش داده میشود، برای مثال:
Service URL: https://webhooks-test-abcdef-uc.a.run.app
این آدرس اعلان سرور است که برنامه شما از طریق آن به اعلانهای وبهوک گوگل آنالیتیکس گوش میدهد.
یک لیست مخاطب ایجاد کنید و اعلانهای وبهوک را روشن کنید
برای درخواست اعلانهای وبهوک، مقادیر زیر را در شیء webhookNotification مشخص کنید:
آدرس اینترنتی اعلان سرور که حاوی آدرس وبی است که اعلانهای وبهوک را دریافت خواهد کرد.
(اختیاری) یک رشته دلخواه
channelTokenبرای محافظت در برابر جعل پیام.channelTokenرا در هدر HTTP مربوط بهX-Goog-Channel-Tokenاز درخواست POST وبهوک مشخص کنید.
در اینجا یک نمونه درخواست با استفاده از وبهوکها آورده شده است:
درخواست 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 است که تأیید میکند وبهوک مشخصشده با موفقیت در کمتر از ۵ ثانیه پاسخ داده است.
در اینجا یک نمونه پاسخ آمده است:
پاسخ 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 است. مهر زمانی sent، زمان epoch یونیکس را بر حسب میکروثانیه که درخواست ارسال شده است، مشخص میکند. میتوانید از این مهر زمانی برای شناسایی اعلانهای بازپخششده استفاده کنید.
در طول ایجاد لیست مخاطبان، یک یا دو درخواست POST به وبهوک ارسال میشود:
- اولین درخواست POST بلافاصله ارسال میشود و لیست مخاطبان تازه ایجاد شده را در حالت
CREATINGنشان میدهد. اگر اولین درخواست به webhook با شکست مواجه شود، عملیاتaudienceLists.createیک خطا و جزئیات شکست webhook را برمیگرداند. - دومین درخواست 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 را مشاهده کنید.