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

本指南介绍了如何使用 webhook 接收有关受众群体导出请求状态的异步通知。此功能仅在 Data API 的 v1alpha 版本中提供。

Webhook 通知是 Google Analytics Data API 的一项高级功能。如需了解受众群体导出功能,请参阅创建受众群体导出。

如果没有 webhook,您需要定期轮询 API 以确定请求何时完成。

使用 Cloud Run 创建示例 webhook 应用

您可以按照快速入门:将示例服务部署到 Cloud Run 教程,使用 Google Cloud 创建示例 webhook 应用。

为了让示例服务监听 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 请求发送的每个传入 webhook 通知,此代码会输出 webhook 通知 JSON 正文和渠道令牌值,并返回 HTTP 代码 200 以指示操作成功。

完成 Cloud Run 快速入门教程并使用 gcloud run deploy 命令部署 webhook 应用后,请保存部署服务的网址。

服务网址会显示在控制台中,例如:

  Service URL: https://webhooks-test-abcdef-uc.a.run.app

这是服务器通知 URI,您的应用会在此处监听来自 Google Analytics 的网络钩子通知。

创建受众群体名单并开启网络钩子通知

如需请求 webhook 通知,请在 webhookNotification 对象中指定以下值:

  • 服务器通知 URI,其中包含将接收 webhook 通知的网址。

  • (可选)任意字符串 channelToken,用于防止消息被欺骗。在 webhook POST 请求的 X-Goog-Channel-Token HTTP 标头中指定 channelToken。

以下是使用网络钩子的请求示例:

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"
    }
  }
}

如果 webhook 未能响应,或者您提供的服务网址不正确,系统会返回出错提示。

以下是您可能会收到的错误示例:

{
  "error": {
    "code": 400,
    "message": "Expected response code of 200 from webhook URI but instead
    '404' was received.",
    "status": "INVALID_ARGUMENT"
  }
}

处理 webhook 通知

对 webhook 服务的 POST 请求在正文中包含长时间运行的操作资源的 JSON 版本,以及 sentTimestamp 字段。发送时间戳指定发送请求的 Unix 纪元时间(以微秒为单位)。您可以使用此时间戳来识别重放的通知。

在创建受众群体名单期间,系统会向 webhook 发送一个或两个 POST 请求:

  1. 系统会立即发送第一个 POST 请求,显示处于 CREATING 状态的新创建的受众群体名单。如果对 webhook 的第一个请求失败,则 audienceLists.create 操作会返回错误和 webhook 失败详细信息。
  2. 第二个 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 应用的日志,并查看 Google Analytics 发送的每个通知的 JSON 正文。