本頁面由 Cloud Translation API 翻譯而成。

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

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

Webhook 通知是 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 通知，此程式碼都會輸出 Webhook 通知 JSON 主體和管道符記值會傳回 HTTP 代碼 200，表示作業成功。

瀏覽 Cloud Run 快速入門教學課程並完成部署後使用 gcloud run deploy 指令開啟 Webhook 應用程式，然後儲存部署服務的所在網址。

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

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

這是伺服器通知 URI 您的應用程式會從何處監聽 Webhook 通知 Google Analytics

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

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

伺服器通知 URI ，用來接收 Webhook 通知的網址。
(選用) 任意字串 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"
    }
  }
}

如果 Webhook 沒有回應，或是您提供的服務網址有誤，系統會改為傳回錯誤訊息

以下是您可能會收到的錯誤訊息範例：

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

處理 Webhook 通知

對 Webhook 服務的 POST 要求同時包含可長期執行的作業資源並在內文中納入 sentTimestamp 欄位傳送的時間戳記會指定傳送要求的 Unix Epoch 紀元時間 (以微秒為單位)。您可以使用時間戳記，用於識別重播通知。

在載入作業期間，系統會傳送一或兩個 POST 要求給 Webhook 目標對象名單建立方式：

第一個 POST 要求會立即傳送，顯示新建立的目標對象名單處於CREATING狀態。如果對 Webhook 失敗，audienceLists.create 作業會傳回錯誤和 Webhook 失敗詳細資料
目標對象名單完成後，系統會傳送第二個 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 傳送通知。