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 Data API'nin ileri seviye 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 sorgulamanız gerekir.
Cloud Run'ı kullanarak örnek bir webhook uygulaması oluşturma
Hızlı başlangıç: Cloud Run'a örnek hizmet dağıtma başlıklı eğitimdeki adımları uygulayarak Google Cloud'u kullanan ö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 işlemin başarılı olduğunu belirtmek için HTTP kodu 200 değerini döndürür.
Cloud Run hızlı başlangıç eğitiminin sonuna gelip webhook uygulamasını gcloud run deploy komutunu kullanarak 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 bildirimi URI'si.
(İsteğe bağlı) Mesajın sahtekarlık amacıyla kullanılmasını önlemek için rastgele bir dize
channelToken. Webhook POST isteğininX-Goog-Channel-TokenHTTP üstbilgisindechannelTokendeğerini belirtin.
Webhook'ları kullanan örnek bir istek aşağıda verilmiştir:
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ıyla yanıt verdiğini onaylayan webhookNotification değerini içerir.
Örnek bir yanıt:
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 mesajına bir örnek:
{
"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 gönderilen 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önderilme zaman damgası, isteğin gönderildiği Unix epoch zamanını mikrosaniye cinsinden belirtir. Tekrar oynatılan bildirimleri tanımlamak 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 gönderilen 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.
CREATING durumundaki bir kitle listesi için ilk bildirimin ö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"
}
}
ACTIVE durumundaki bir kitle listesi için 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.