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

本指南介绍了如何使用网络钩子接收异步通知 了解受众群体导出请求的状态。此功能仅适用于 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 请求。 受众群体名单创建：

  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 示例应用的 JSON 正文，并查看每个 Google Analytics 发送的通知