本指南說明如何使用 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-TokenHTTP 標頭中指定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 紀元時間 (以微秒為單位)。您可以使用這個時間戳記來識別重播的通知。
建立目標對象名單時,系統會向 Webhook 傳送一或兩項 POST 要求:
- 系統會立即傳送第一個 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 應用程式的記錄,並查看 Google Analytics 傳送的每則通知的 JSON 主體。