接收受众群体名单的网络钩子通知

本指南介绍了如何使用网络钩子接收异步通知 了解受众群体导出请求的状态。此功能仅适用于 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 以防止邮件遭到仿冒。指定 channelTokenX-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 请求。 受众群体名单创建:

  1. 第一个 POST 请求会立即发送,显示新创建的 CREATING 状态的受众群体名单。如果对 webhook 失败,audienceLists.create 操作返回错误 以及 webhook 失败详情。
  2. 第二个 POST 请求在受众群体名单完成后发送 创建过程。当受众群体名单达到以下任一条件时,即表示创建完毕 ACTIVEFAILED 状态。

这是受众群体名单第一条通知的示例 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 发送的通知