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

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

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

หากไม่มีเว็บฮุค คุณจะต้องสำรวจ 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