Bu kılavuzda, kitle dışa aktarma isteklerinizin durumuyla ilgili eşzamansız bildirimler almak için webhook'ların nasıl kullanılacağı açıklanmaktadır. Bu özellik yalnızca Data API'nin v1alpha sürümünde kullanılabilir.
Webhook bildirimleri, Google Analytics Veri API'sinin gelişmiş bir özelliğidir. Kitle dışa aktarma özelliğine giriş için Kitle dışa aktarma oluşturma başlıklı makaleyi inceleyin.
Webhook'lar olmadan, bir isteğin ne zaman tamamlandığını belirlemek için API'yi düzenli olarak yoklamanız gerekir.
Cloud Run'ı kullanarak örnek bir webhook uygulaması oluşturma
Hızlı Başlangıç: Örnek bir hizmeti Cloud Run'a dağıtma başlıklı eğiticideki adımları uygulayarak Google Cloud'u kullanarak örnek bir webhook uygulaması oluşturabilirsiniz.
Örnek hizmetin POST webhook bildirim isteklerini dinlemesi için hızlı başlangıç eğitimindeki index.js dosyasını aşağıdaki kodla değiştirin:
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 isteği olarak gönderilen her gelen webhook bildirimi için bu kod, webhook bildirimi JSON gövdesini ve bir kanal jetonu değerini yazdırır ve başarılı işlemi belirtmek için 200 HTTP kodunu döndürür.
Cloud Run hızlı başlangıç eğitiminin sonuna ulaşıp gcloud run deploy komutunu kullanarak webhook uygulamasını dağıttıktan sonra hizmetinizin dağıtıldığı URL'yi kaydedin.
Hizmet URL'si konsolda gösterilir. Örneğin:
Service URL: https://webhooks-test-abcdef-uc.a.run.app
Bu, uygulamanızın Google Analytics'ten gelen webhook bildirimlerini dinlediği sunucu bildirimi URI'sidir.
Kitle listesi oluşturma ve webhook bildirimlerini etkinleştirme
Webhook bildirimleri istemek için webhookNotification
nesnesinde aşağıdaki değerleri belirtin:
Webhook bildirimlerini alacak web adresini içeren sunucu bildirimi URI'si.
(İsteğe bağlı) İletinin sahteciliğe karşı korunması için rastgele bir dize
channelToken. Webhook POST isteğininX-Goog-Channel-TokenHTTP üstbilgisindechannelTokendeğerini belirtin.
Webhook'ları kullanan örnek bir isteği aşağıda bulabilirsiniz:
HTTP İsteği
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 yönteminden gelen yanıt, belirtilen webhook'un 5 saniyeden kısa sürede başarılı bir şekilde yanıt verdiğini onaylayan webhookNotification değerini içerir.
Aşağıda örnek bir yanıt verilmiştir:
HTTP Yanıtı
{
"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"
}
}
}
Bir webhook yanıt vermezse veya yanlış bir hizmet URL'si sağlarsanız bunun yerine bir hata mesajı döndürülür.
Alabileceğiniz hata örneği:
{
"error": {
"code": 400,
"message": "Expected response code of 200 from webhook URI but instead
'404' was received.",
"status": "INVALID_ARGUMENT"
}
}
Webhook bildirimlerini işleme
Webhook hizmetine yapılan POST isteği, gövdede uzun süreli işlem kaynağının JSON sürümünü ve bir sentTimestamp alanını içerir. Gönderilen zaman damgası, isteğin gönderildiği Unix epoch zamanını mikrosaniye cinsinden belirtir. Yeniden oynatılan bildirimleri belirlemek için bu zaman damgasını kullanabilirsiniz.
Kitle listesi oluşturma sırasında webhook'a bir veya iki POST isteği gönderilir:
- İlk POST isteği hemen gönderilir ve yeni oluşturulan kitle listesi
CREATINGdurumunda gösterilir. Webhook'a yapılan ilk istek başarısız olursaaudienceLists.createişlemi bir hata ve webhook hatası ayrıntılarını döndürür. - İkinci POST isteği, kitle listesi oluşturma işlemi tamamlandıktan sonra gönderilir. Kitle listesi
ACTIVEveyaFAILEDdurumuna ulaştığında oluşturma işlemi tamamlanır.
Aşağıda, CREATING durumundaki bir kitle listesiyle ilgili ilk bildirime dair bir örnek verilmiştir:
{
"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"
}
}
Aşağıda, ACTIVE durumundaki bir kitle listesi için ikinci bildirime dair bir örnek verilmiştir:
{
"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"
}
}
İkinci bildirim, kitle listesinin oluşturulduğunu ve audienceLists.query yöntemi kullanılarak sorgulanmaya hazır olduğunu onaylar.
audienceLists.create yöntemini çağırdıktan sonra webhook'ları test etmek için örnek Cloud Run webhook uygulamanızın günlüklerini inceleyebilir ve Google Analytics tarafından gönderilen her bildirimin JSON gövdesini görebilirsiniz.