ऑडियंस की सूचियों के लिए, वेबहुक की सूचनाएं पाएं

इस गाइड में, वेबहुक का इस्तेमाल करके ऑडियंस एक्सपोर्ट करने के अनुरोधों की स्थिति के बारे में एसिंक्रोनस सूचनाएं पाने का तरीका बताया गया है. यह सुविधा सिर्फ़ Data API के v1alpha वर्शन में उपलब्ध है.

वेबहुक सूचनाएं, Google Analytics Data 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}`);
  });

पोस्ट अनुरोध के तौर पर भेजे गए हर वेबहुक नोटिफ़िकेशन के लिए, यह कोड वेबहुक नोटिफ़िकेशन के JSON बॉडी और चैनल टोकन की वैल्यू को प्रिंट करता है. साथ ही, कार्रवाई पूरी होने का संकेत देने के लिए, एचटीटीपी कोड 200 दिखाता है.

Cloud Run के क्विकस्टार्ट ट्यूटोरियल के आखिर में पहुंचने और gcloud run deploy कमांड का इस्तेमाल करके वेबहुक ऐप्लिकेशन को डिप्लॉय करने के बाद, उस यूआरएल को सेव करें जहां आपकी सेवा डिप्लॉय की गई है.

सेवा का यूआरएल, कंसोल में दिखता है. उदाहरण के लिए:

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

यह सर्वर नोटिफ़िकेशन यूआरआई है. यहां आपका ऐप्लिकेशन, Google Analytics से वेबहुक नोटिफ़िकेशन सुनता है.

ऑडियंस की सूची बनाना और वेबहुक सूचनाएं चालू करना

वेबहुक सूचनाओं का अनुरोध करने के लिए, webhookNotification ऑब्जेक्ट में ये वैल्यू डालें:

  • सर्वर की सूचना का यूआरआई, जिसमें वह वेब पता शामिल होता है जिस पर वेबहुक की सूचनाएं मिलेंगी.

  • (ज़रूरी नहीं) मैसेज को स्पूफ़ होने से बचाने के लिए, कोई भी स्ट्रिंग channelToken. वेबहुक के पोस्ट अनुरोध के X-Goog-Channel-Token एचटीटीपी हेडर में, channelToken की जानकारी दें.

यहां वेबहुक का इस्तेमाल करके किए गए अनुरोध का एक सैंपल दिया गया है:

एचटीटीपी अनुरोध

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 शामिल होता है. इससे यह पुष्टि होती है कि तय किए गए वेबहुक ने पांच सेकंड के अंदर जवाब दिया.

यहां जवाब का एक उदाहरण दिया गया है:

एचटीटीपी रिस्पॉन्स

{
  "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"
    }
  }
}

अगर कोई वेबहुक जवाब नहीं देता है या आपने सेवा का गलत यूआरएल दिया है, तो गड़बड़ी का मैसेज दिखता है.

यहां गड़बड़ी का एक उदाहरण दिया गया है, जो आपको मिल सकता है:

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

वेबहुक सूचनाएं प्रोसेस करना

वेबहुक सेवा को भेजे गए पोस्ट अनुरोध के मुख्य हिस्से में, लंबे समय तक चलने वाले ऑपरेशन के संसाधन का JSON वर्शन और sentTimestamp फ़ील्ड, दोनों शामिल होते हैं. भेजे गए टाइमस्टैंप से, अनुरोध भेजे जाने के Unix epoch समय का पता चलता है. यह समय माइक्रोसेकंड में होता है. इस टाइमस्टैंप का इस्तेमाल करके, फिर से भेजी गई सूचनाओं की पहचान की जा सकती है.

ऑडियंस की सूची बनाने के दौरान, वेबहुक को एक या दो पोस्ट अनुरोध भेजे जाते हैं:

  1. पहला POST अनुरोध तुरंत भेजा जाता है. इसमें नई बनाई गई ऑडियंस की सूची को CREATING स्थिति में दिखाया जाता है. अगर वेबहुक को किया गया पहला अनुरोध पूरा नहीं होता है, तो audienceLists.create कार्रवाई एक गड़बड़ी और वेबहुक के काम न करने की जानकारी दिखाती है.
  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"
      }
  }

यहां 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 तरीके को कॉल करने के बाद वेबहुक की जांच करने के लिए, अपने सैंपल Cloud Run वेबहुक ऐप्लिकेशन के लॉग की जांच की जा सकती है. साथ ही, Google Analytics से भेजी गई हर सूचना का JSON मुख्य हिस्सा देखा जा सकता है.