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

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

वेबहुक सूचनाएं, Google Analytics Data API की बेहतर सुविधा है. ऑडियंस एक्सपोर्ट करने की सुविधा के बारे में जानने के लिए, ऑडियंस एक्सपोर्ट बनाएं लेख पढ़ें.

वेबहुक के बिना, आपको समय-समय पर एपीआई को पोल करना होगा, ताकि यह पता लगाया जा सके कि अनुरोध कब पूरा हुआ.

Cloud Run का इस्तेमाल करके, सैंपल webhook ऐप्लिकेशन बनाना

Google Cloud का इस्तेमाल करके, सैंपल वेबहुक ऐप्लिकेशन बनाया जा सकता है. इसके लिए, क्विकस्टार्ट: Cloud Run पर सैंपल सेवा डिप्लॉय करना ट्यूटोरियल का पालन करें.

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

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

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

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

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