รับการแจ้งเตือนเว็บฮุคสำหรับรายการกลุ่มเป้าหมาย

คู่มือนี้จะอธิบายวิธีใช้เว็บฮุคเพื่อรับการแจ้งเตือนแบบไม่พร้อมกันสำหรับสถานะคำขอส่งออกกลุ่มเป้าหมาย ฟีเจอร์นี้ใช้ได้เฉพาะใน Data API เวอร์ชัน v1alpha เท่านั้น

การแจ้งเตือนเว็บฮุคคือฟีเจอร์ขั้นสูงของ Data API ของ Google Analytics สำหรับข้อมูลเบื้องต้นเกี่ยวกับฟีเจอร์การส่งออกกลุ่มเป้าหมาย โปรดดูสร้างการส่งออกกลุ่มเป้าหมาย

หากไม่มีเว็บฮุค คุณจะต้องสำรวจ API เป็นระยะๆ เพื่อตัดสินว่าคำขอจะเสร็จสมบูรณ์เมื่อใด

สร้างตัวอย่างแอปพลิเคชันเว็บฮุคโดยใช้ Cloud Run

คุณสร้างตัวอย่างแอปพลิเคชันเว็บฮุคได้โดยใช้ Google Cloud โดยทำตามบทแนะนำ การเริ่มต้นอย่างรวดเร็ว: ทำให้บริการตัวอย่างใช้งานได้กับ Cloud Run

หากต้องการให้บริการตัวอย่างฟังคำขอการแจ้งเตือนเว็บฮุค POST ให้แทนที่ไฟล์ 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 โค้ดนี้จะพิมพ์เนื้อหา JSON ของการแจ้งเตือนเว็บฮุคและค่าโทเค็นช่องทาง และแสดงผลรหัส HTTP 200 เพื่อบ่งบอกว่าการดำเนินการสำเร็จ

เมื่ออ่านบทแนะนำการเริ่มต้นอย่างรวดเร็วของ Cloud Run จนสุดแล้วและทำให้แอปพลิเคชันเว็บฮุคใช้งานได้โดยใช้คำสั่ง gcloud run deploy ให้บันทึก URL ที่มีการทำให้บริการใช้งานได้

URL ของบริการจะปรากฏในคอนโซล เช่น

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

นี่คือ URL การแจ้งเตือนของเซิร์ฟเวอร์ ที่แอปพลิเคชันจะฟังการแจ้งเตือนเว็บฮุคจาก Google Analytics

สร้างรายการกลุ่มเป้าหมายและเปิดการแจ้งเตือนเว็บฮุค

หากต้องการขอการแจ้งเตือนเว็บฮุค ให้ระบุค่าต่อไปนี้ในออบเจ็กต์ webhookNotification

  • URL การแจ้งเตือนของเซิร์ฟเวอร์ ที่มีที่อยู่เว็บที่จะได้รับการแจ้งเตือนเว็บฮุค

  • (ไม่บังคับ) สตริงที่กำหนดเอง channelToken เพื่อป้องกันข้อความที่มีการปลอมแปลง ระบุ channelToken ในส่วนหัว HTTP X-Goog-Channel-Token ของคำขอ POST ของเว็บฮุค

ตัวอย่างคำขอที่ใช้เว็บฮุคมีดังนี้

คำขอ 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 ซึ่งยืนยันว่าเว็บฮุคที่ระบุตอบสนองสำเร็จภายใน 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"
    }
  }
}

หากเว็บฮุคไม่ตอบสนองหรือหากคุณระบุ URL บริการที่ไม่ถูกต้อง ระบบจะแสดงข้อความแสดงข้อผิดพลาดแทน

ตัวอย่างข้อผิดพลาดที่คุณอาจได้รับมีดังนี้

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

ประมวลผลการแจ้งเตือนเว็บฮุค

คำขอ POST ไปยังบริการเว็บฮุคจะมีทั้งเวอร์ชัน JSON ของทรัพยากรการดำเนินการที่ใช้เวลานานในตัวเนื้อหา และช่อง sentTimestamp การประทับเวลาที่ส่งจะระบุเวลา Unix Epoch ในหน่วยไมโครวินาทีที่ส่งคำขอ โดยคุณใช้การประทับเวลานี้เพื่อระบุการแจ้งเตือนที่เล่นซ้ำได้

ระบบจะส่งคำขอ POST 1 หรือ 2 รายการไปยังเว็บฮุคในระหว่างการสร้างรายการกลุ่มเป้าหมาย ดังนี้

  1. ระบบจะส่งคำขอ POST แรกทันทีโดยแสดงรายการกลุ่มเป้าหมายที่สร้างขึ้นใหม่ในสถานะ CREATING หากคำขอแรกไปยังเว็บฮุคไม่สำเร็จ การดำเนินการ audienceLists.create จะแสดงข้อผิดพลาดและรายละเอียดความล้มเหลวของเว็บฮุค
  2. ระบบจะส่งคำขอ POST รายการที่ 2 หลังจากสร้างรายการกลุ่มเป้าหมายเสร็จแล้ว การสร้างจะเสร็จสมบูรณ์เมื่อรายการกลุ่มเป้าหมายอยู่ในสถานะ 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"
      }
  }

ต่อไปนี้คือตัวอย่างการแจ้งเตือนครั้งที่ 2 สำหรับรายการกลุ่มเป้าหมายที่อยู่ในสถานะ 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"
      }
  }

การแจ้งเตือนครั้งที่ 2 จะยืนยันว่าได้สร้างรายการกลุ่มเป้าหมายแล้วและพร้อมที่จะค้นหาโดยใช้เมธอด audienceLists.query

หากต้องการทดสอบเว็บฮุคหลังจากเรียกใช้เมธอด audienceLists.create คุณสามารถตรวจสอบบันทึกของแอปพลิเคชันเว็บฮุค Cloud Run ตัวอย่าง และดูส่วนเนื้อหา JSON ของการแจ้งเตือนทุกรายการที่ Google Analytics ส่งได้