В этом руководстве объясняется, как использовать веб-перехватчики для получения асинхронных уведомлений о статусе запросов на экспорт вашей аудитории. Эта функция доступна только в версии v1alpha Data API .
Уведомления Webhook — это расширенная функция API данных Google Analytics. Дополнительные сведения о функции экспорта аудитории см. в разделе Создание экспорта аудитории .
Без веб-перехватчиков вам придется периодически опрашивать API, чтобы определить, когда запрос завершен.
Создайте пример приложения веб-перехватчика с помощью Cloud Run.
Вы можете создать образец приложения веб-перехватчика с помощью Google Cloud, следуя руководству «Краткое руководство: развертывание образца службы в Cloud Run» .
Чтобы пример службы мог прослушивать запросы уведомлений веб-перехватчика 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-адрес, по которому развернута ваша служба.
URL сервиса отображается в консоли, например:
Service URL: https://webhooks-test-abcdef-uc.a.run.app
Это URI уведомлений сервера , где ваше приложение прослушивает уведомления веб-перехватчика из Google Analytics.
Создайте список аудитории и включите уведомления вебхука.
Чтобы запросить уведомления веб-перехватчика, укажите следующие значения в объекте webhookNotification :
URI уведомления сервера, содержащий веб-адрес, который будет получать уведомления веб-перехватчика.
(Необязательно) Произвольная строка
channelTokenдля защиты от подделки сообщения. УкажитеchannelTokenв HTTP-заголовкеX-Goog-Channel-TokenPOST-запроса веб-перехватчика.
Вот пример запроса с использованием веб-перехватчиков:
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 , который подтверждает, что указанный веб-перехватчик успешно ответил менее чем за 5 секунд.
Вот пример ответа:
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 . Отправленная временная метка указывает время эпохи Unix в микросекундах, когда был отправлен запрос. Вы можете использовать эту метку времени для идентификации воспроизводимых уведомлений.
Во время создания списка аудитории на вебхук отправляются один или два POST-запроса:
- Первый запрос POST отправляется немедленно, показывая вновь созданный список аудитории в состоянии
CREATING. Если первый запрос к веб-перехватчику завершается неудачно, операцияaudienceLists.createвозвращает ошибку и сведения о сбое веб-перехватчика. - Второй запрос 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.