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

本指南說明如何使用 webhook 接收目標對象匯出要求狀態的非同步通知。這項功能僅適用於 Data API 的 v1alpha 版。

Webhook 通知是 Google Analytics Data API 的進階功能。如要瞭解目標對象匯出功能，請參閱「建立目標對象匯出」一文。

如果沒有 webhook，您就必須定期輪詢 API，才能判斷要求何時完成。

使用 Cloud Run 建立範例 Webhook 應用程式

您可以參閱快速入門：將範例服務部署至 Cloud Run教學課程，使用 Google Cloud 建立範例 webhook 應用程式。

為了讓範例服務監聽 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 紀元時間。您可以使用這個時間戳記來辨識重播的通知。

建立目標對象清單時，系統會將一或兩個 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 主體。