Bu kılavuzda, kitle dışa aktarma isteklerinizin durumuyla ilgili asenkron 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 Data API'nin gelişmiş bir özelliğidir. Kitle dışa aktarma özelliğiyle ilgili 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 sorgulamak gerekir.
Cloud Run'u kullanarak örnek bir webhook uygulaması oluşturma
Hızlı Başlangıç: Cloud Run'a örnek hizmet dağıtma eğiticisini 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}`);
});
Bu kod, POST isteği olarak gönderilen her gelen webhook bildirimi için webhook bildirimi JSON gövdesini ve bir kanal jetonu değerini yazdırır ve başarılı işlemi belirtmek için HTTP kodu 200 döndürür.
Cloud Run hızlı başlangıç eğitiminin 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 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ı) Mesajın kimliğe bürünmesine karşı koruma sağlamak için rastgele bir dize
channelToken. Webhook POST isteğininX-Goog-Channel-TokenHTTP başlığındachannelTokendeğerini belirtin.
Webhook'ları kullanan örnek bir isteği aşağıda bulabilirsiniz:
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ıtta, belirtilen webhook'ın 5 saniyeden kısa bir sürede başarıyla yanıt verdiğini onaylayan webhookNotification yer alır.
Aşağıda örnek bir yanıt verilmiştir:
{
"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.
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
Bir webhook hizmetine gönderilen POST isteği, gövdesinde hem uzun süreli işlem kaynağının JSON sürümünü hem de bir sentTimestamp alanı içerir. Gönderilen zaman damgası, isteğin gönderildiği mikrosaniye cinsinden Unix epoch zamanını belirtir. Tekrar oynatılan bildirimleri tanımlamak için bu zaman damgasını kullanabilirsiniz.
Kitle listesi oluşturulurken webhook'a bir veya iki POST isteği gönderilir:
- İlk POST isteği hemen gönderilir ve yeni oluşturulan kitle listesini
CREATINGdurumunda gösterir. 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şturulduktan sonra gönderilir. Oluşturma işlemi, kitle listesi
ACTIVEveyaFAILEDdurumuna ulaştığında tamamlanır.
Aşağıda, CREATING durumundaki bir kitle listesi için ilk bildirim örneği 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.