Bu kılavuzda, kitle dışa aktarma isteklerinizin durumuyla ilgili eşzamansız bildirimler almak için webhook'ları nasıl kullanacağınız açıklanmaktadır. Bu özellik yalnızca Data API'nin v1alpha sürümünde kullanılabilir.
Webhook bildirimleri, Google Analytics Data API'nin gelişmiş bir özelliğidir. Kitle dışa aktarma özelliğiyle ilgili temel bilgiler için Kitle dışa aktarma işlemi oluşturma bölümüne bakın.
Webhook olmadan, isteğin ne zaman tamamlandığını belirlemek için API'yi düzenli aralıklarla yoklamanız gerekir.
Cloud Run'ı kullanarak örnek bir webhook uygulaması oluşturma
Hızlı Başlangıç: Cloud Run'a örnek bir hizmet dağıtma başlıklı eğiticiyi izleyerek Google Cloud kullanarak örnek bir webhook uygulaması oluşturabilirsiniz.
Örnek hizmetin POST webhook bildirim isteklerini dinlemesi için hızlı başlangıç eğiticisindeki 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}`);
});
Bu kod, POST isteği olarak gönderilen her gelen webhook bildirimi için webhook bildirimi JSON gövdesini ve kanal jetonu değerini yazdırır ve işlemin başarılı olduğunu belirtmek için 200 HTTP kodunu döndürür.
Cloud Run hızlı başlangıç eğiticisinin sonuna geldikten ve 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 bildirim 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 bildirim URI'si.
(İsteğe bağlı) Adres sahteciliğine karşı koruma sağlamak için rastgele bir dize
channelToken. Webhook POST isteğininX-Goog-Channel-TokenHTTP başlığındachannelTokenöğesini belirtin.
Webhook kullanan bir örnek isteği aşağıda görebilirsiniz:
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önteminin yanıtı webhookNotification, belirtilen webhook'un 5 saniyeden daha kısa sürede yanıt verdiğini onaylar.
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"
}
}
}
Webhook yanıt vermezse veya yanlış hizmet URL'si sağlarsanız bunun yerine bir hata mesajı döndürülür.
Aşağıda, alabileceğiniz bir hata örneği verilmiştir:
{
"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 hem uzun çalışan işlem kaynağının JSON sürümünü hem de sentTimestamp alanını içerir. Gönderilen zaman damgası, isteğin gönderildiği Unix sıfır değerini mikrosaniye cinsinden belirtir. Tekrar oynatılan bildirimleri belirlemek için bu zaman damgasını kullanabilirsiniz.
Kitle listesi oluşturma işlemi 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 hata ayrıntılarını döndürür. - İkinci POST isteği, kitle listesinin oluşturulması tamamlandıktan sonra gönderilir. Kitle listesi
ACTIVEveyaFAILEDdurumuna ulaştığında oluşturma işlemi tamamlanır.
Bir kitle listesi için CREATING durumundaki ilk bildirim örneğini aşağıda bulabilirsiniz:
{
"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"
}
}
Bir kitle listesi için ACTIVE durumundaki ikinci bildirim örneğini aşağıda bulabilirsiniz:
{
"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.