接收目標對象名單的 Webhook 通知

本指南說明如何使用 Webhook 接收非同步通知，以瞭解目標對象匯出要求的狀態。此功能僅適用於 v1 Alpha 版的 Data API。

Webhook 通知是 Google Analytics (分析) Data 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 通知，這個程式碼會輸出 Webhook 通知 JSON 主體和管道符記值，並傳回 HTTP 代碼 200 表示作業成功。

瀏覽到 Cloud Run 快速入門教學課程，並使用 gcloud run deploy 指令部署 Webhook 應用程式後，請將服務部署網址儲存起來。

服務網址會顯示在控制台中，例如：

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

這是伺服器通知 URI，可讓應用程式監聽來自 Google Analytics (分析) 的 Webhook 通知。

建立目標對象名單並啟用 Webhook 通知

如要要求 Webhook 通知，請在 webhookNotification 物件中指定下列值：

  • 伺服器通知 URI，包含用於接收 Webhook 通知的網址。

  • (選用) 任意字串 channelToken，用於防止遭到假冒的郵件。在 Webhook POST 要求的 X-Goog-Channel-Token HTTP 標頭中指定 channelToken。

以下是使用 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"
    }
  }
}

如果 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 Epoch 時間 (以微秒為單位)。您可以用此時間戳記識別已重播的通知。

在目標對象名單建立期間，系統會將一或兩個 POST 要求傳送至 Webhook：

  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 主體。