本指南介绍了如何使用网络钩子接收异步通知 了解受众群体导出请求的状态。此功能仅适用于 Data API v1alpha 版。
网络钩子通知 是 Google Analytics 中的数据 API。有关 受众群��导出功能,请参阅创建受众群体导出。
如果没有 webhook,您将需要定期轮询 API 以 以确定请求何时完成
使用 Cloud Run 创建示例 webhook 应用
您可以使用 Google Cloud 创建示例 webhook 应用,方法如下: 教程:快速入门:将示例服务部署到 Cloud Run。
为了让示例服务能够监听 POST webhook 通知请求,
将快速入门教程中的 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 请求形式发送的每个 Webhook 通知,此代码会输出
系统给出网络钩子通知 JSON 正文和渠道令牌值,
将返回 HTTP 代码 200
,这表示操作成功。
完成 Cloud Run 快速入门教程的学习并完成部署后
使用 gcloud run deploy
命令创建网络钩子应用,保存
部署服务的网址。
服务网址显示在控制台中,例如:
Service URL: https://webhooks-test-abcdef-uc.a.run.app
这是服务器通知 URI 并从中监听 Google Analytics。
创建受众群体名单并开启网络钩子通知
如需请求网络钩子通知,请在 webhookNotification
中指定以下值
对象:
服务器通知 URI 包含将接收网络钩子通知的网址。
(可选)任意字符串
channelToken
以防止邮件遭到仿冒。指定channelToken
的X-Goog-Channel-Token
HTTP 标头中, webhook POST 请求。
以下是使用 webhook 的请求示例:
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
,用于确认指定的 webhook 已成功完成
在 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"
}
}
}
如果网络钩子无法响应,或者您提供的服务网址不正确, 而是会返回一条错误消息。
以下是您可能会收到的错误示例:
{
"error": {
"code": 400,
"message": "Expected response code of 200 from webhook URI but instead
'404' was received.",
"status": "INVALID_ARGUMENT"
}
}
处理网络钩子通知
发送给网络钩子服务的 POST 请求同时包含
长时间运行的操作资源
以及一个 sentTimestamp
字段。发送的时间戳指定
发送请求的 Unix 纪元时间(以微秒为单位)。您可以使用
时间戳以识别重放通知。
在发送请求期间,系统会向网络钩子发送一个或两个 POST 请求。 受众群体名单创建:
- 第一个 POST 请求会立即发送,显示新创建的
CREATING
状态的受众群体名单。如果对 webhook 失败,audienceLists.create
操作返回错误 以及 webhook 失败详情。 - 第二个 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
方法后测试 webhook,您可以执行以下操作:
检查日志
Cloud Run webhook 示例应用的 JSON 正文,并查看每个
Google Analytics 发送的通知