पुश नोटिफ़िकेशन सेट अप करना और पाना

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

खास जानकारी

Google Forms API की पुश नोटिफ़िकेशन सुविधा की मदद से, ऐप्लिकेशन सूचनाएं पाने के लिए सदस्यता ले सकते हैं. ऐसा तब होता है, जब फ़ॉर्म में डेटा बदलता है. सूचनाएं, Cloud Pub/Sub के विषय पर भेजी जाती हैं. आम तौर पर, बदलाव होने के कुछ मिनटों के अंदर ही सूचनाएं मिल जाती हैं.

पुश नोटिफ़िकेशन पाने के लिए, आपको Cloud Pub/Sub विषय सेट अप करना होगा. साथ ही, इवेंट के सही टाइप के लिए वॉच बनाते समय, उस विषय का नाम देना होगा.

इस दस्तावेज़ में इस्तेमाल किए गए मुख्य कॉन्सेप्ट की परिभाषाएं यहां दी गई हैं:

• टारगेट वह जगह होती है जहां सूचनाएं भेजी जाती हैं. सिर्फ़ Cloud Pub/Sub टॉपिक को टारगेट किया जा सकता है.
• इवेंट टाइप, सूचनाओं की एक कैटगरी होती है. तीसरे पक्ष का कोई ऐप्लिकेशन, इसकी सदस्यता ले सकता है.
• वॉच, Forms API को दिया गया एक निर्देश होता है. इसके तहत, किसी टारगेट को किसी फ़ॉर्म पर होने वाले किसी इवेंट टाइप की सूचनाएं भेजी जाती हैं.

किसी फ़ॉर्म पर किसी इवेंट टाइप के लिए वॉच बनाने के बाद, वॉच के टारगेट (जो Cloud Pub/Sub विषय है) को उस फ़ॉर्म पर होने वाले इवेंट की सूचनाएं मिलती हैं. ये सूचनाएं तब तक मिलती हैं, जब तक वॉच की समयसीमा खत्म नहीं हो जाती. आपकी स्मार्टवॉच एक हफ़्ते तक चलती है. हालांकि, इसे खत्म होने से पहले किसी भी समय बढ़ाया जा सकता है. इसके लिए, watches.renew() पर अनुरोध करें.

आपके Cloud Pub/Sub विषय को सिर्फ़ उन फ़ॉर्म के बारे में सूचनाएं मिलती हैं जिन्हें आपने दिए गए क्रेडेंशियल से देखा है. उदाहरण के लिए, अगर उपयोगकर्ता आपके ऐप्लिकेशन से अनुमति वापस ले लेता है या उसके पास देखे गए फ़ॉर्म में बदलाव करने का ऐक्सेस नहीं रहता है, तो उसे सूचनाएं नहीं भेजी जाएंगी.

उपलब्ध इवेंट टाइप

फ़िलहाल, Google Forms API में दो कैटगरी के इवेंट उपलब्ध हैं:

• EventType.SCHEMA, जो फ़ॉर्म के कॉन्टेंट और सेटिंग में किए गए बदलावों के बारे में सूचना देता है.
• EventType.RESPONSES, यह सूचना तब मिलती है, जब फ़ॉर्म के जवाब सबमिट किए जाते हैं. ये जवाब नए और अपडेट किए गए, दोनों तरह के हो सकते हैं.

सूचनाओं के जवाब

सूचनाओं को JSON के साथ कोड किया जाता है. इनमें यह जानकारी शामिल होती है:

• ट्रिगर करने वाले फ़ॉर्म का आईडी
• ट्रिगर करने वाली स्मार्टवॉच का आईडी
• जिस इवेंट की वजह से सूचना ट्रिगर हुई है उसका टाइप
• Cloud Pub/Sub की ओर से सेट किए गए अन्य फ़ील्ड, जैसे कि messageId और publishTime

सूचनाओं में, फ़ॉर्म या जवाब का पूरा डेटा शामिल नहीं होता. हर सूचना मिलने के बाद, नया डेटा फ़ेच करने के लिए अलग से एपीआई कॉल करना ज़रूरी है. इसे पूरा करने का तरीका जानने के लिए, इस्तेमाल करने का सुझाव देखें.

यहां दिए गए स्निपेट में, स्कीमा में हुए बदलाव की सूचना का एक उदाहरण दिखाया गया है:

{
  "attributes": {
    "eventType": "SCHEMA",
    "formId": "18Xgmr4XQb-l0ypfCNGQoHAw2o82foMr8J0HPHdagS6g",
    "watchId": "892515d1-a902-444f-a2fe-42b718fe8159"
  },
  "messageId": "767437830649",
  "publishTime": "2021-03-31T01:34:08.053Z"
}

इस स्निपेट में, नए जवाब के लिए सूचना का एक उदाहरण दिखाया गया है:

{
  "attributes": {
    "eventType": "RESPONSES",
    "formId": "18Xgmr4XQb-l0ypfCNGQoHAw2o82foMr8J0HPHdagS6g",
    "watchId": "5d7e5690-b1ff-41ce-8afb-b469912efd7d"
  },
  "messageId": "767467004397",
  "publishTime": "2021-03-31T01:43:57.285Z"
}

Cloud Pub/Sub का विषय सेट अप करना

सूचनाएं, Cloud Pub/Sub के विषयों पर भेजी जाती हैं. Cloud Pub/Sub से, आपको वेब हुक पर सूचनाएं मिल सकती हैं. इसके अलावा, सदस्यता के एंडपॉइंट को पोल करके भी सूचनाएं पाई जा सकती हैं.

Cloud Pub/Sub विषय सेट अप करने के लिए, यह तरीका अपनाएं:

1. Cloud Pub/Sub की ज़रूरी शर्तें पूरी करें.
2. Cloud Pub/Sub क्लाइंट सेट अप करें.
3. Cloud Pub/Sub की कीमत देखें. साथ ही, Google Cloud Console प्रोजेक्ट के लिए बिलिंग चालू करें.

4. Cloud Pub/Sub टॉपिक बनाने के लिए, इनमें से कोई एक तरीका अपनाएं:

   • Google Cloud Console का इस्तेमाल करके
   • कमांड लाइन टूल का इस्तेमाल करके (प्रोग्राम के ज़रिए आसानी से इस्तेमाल करने के लिए) या
   • Cloud Pub/Sub API का इस्तेमाल करके.
   ध्यान दें: Cloud Pub/Sub में विषयों की संख्या सीमित होती है. इसलिए, सभी सूचनाएं पाने के लिए एक ही विषय का इस्तेमाल करने से, यह पक्का किया जा सकता है कि आपका ऐप्लिकेशन लोकप्रिय होने पर, आपको स्केलिंग से जुड़ी समस्याएं न आएं.

5. Cloud Pub/Sub में सदस्यता बनाएं, ताकि Cloud Pub/Sub को यह पता चल सके कि सूचनाएं कैसे डिलीवर करनी हैं.

6. आखिर में, अपने विषय को टारगेट करने वाली वॉच बनाने से पहले, आपको Forms की सूचनाएं पाने वाले सेवा खाते ([e-mail]) को, अपने विषय पर पब्लिश करने की अनुमति देनी होगी.

स्मार्टवॉच बनाना

जब आपके पास कोई ऐसा विषय हो जिस पर Forms API की पुश नोटिफ़िकेशन सेवा खाता पब्लिश कर सकता है, तब watches.create() तरीके का इस्तेमाल करके सूचनाएं बनाई जा सकती हैं. इस तरीके से यह पुष्टि की जाती है कि पुश नोटिफ़िकेशन सेवा खाता, दिए गए Cloud Pub/Sub विषय तक पहुंच सकता है. अगर वह विषय तक नहीं पहुंच पाता है, तो यह तरीका काम नहीं करता. उदाहरण के लिए, अगर विषय मौजूद नहीं है या आपने उसे उस विषय पर पब्लिश करने की अनुमति नहीं दी है.

Python

forms/snippets/create_watch.py

GitHub पर देखें

from apiclient import discovery
from httplib2 import Http
from oauth2client import client, file, tools

SCOPES = "https://www.googleapis.com/auth/drive"
DISCOVERY_DOC = "https://forms.googleapis.com/$discovery/rest?version=v1"

store = file.Storage("token.json")
creds = None
if not creds or creds.invalid:
  flow = client.flow_from_clientsecrets("client_secret.json", SCOPES)
  creds = tools.run_flow(flow, store)

service = discovery.build(
    "forms",
    "v1",
    http=creds.authorize(Http()),
    discoveryServiceUrl=DISCOVERY_DOC,
    static_discovery=False,
)

watch = {
    "watch": {
        "target": {"topic": {"topicName": "<YOUR_TOPIC_PATH>"}},
        "eventType": "RESPONSES",
    }
}

form_id = "<YOUR_FORM_ID>"

# Print JSON response after form watch creation
result = service.forms().watches().create(formId=form_id, body=watch).execute()
print(result)

Node.js

forms/snippets/create_watch.js

GitHub पर देखें

import path from 'node:path';
import {authenticate} from '@google-cloud/local-auth';
import {forms} from '@googleapis/forms';

// TODO: Replace with a valid form ID.
const formID = '<YOUR_FORM_ID>';

/**
 * Creates a watch on a form to get notifications for new responses.
 */
async function createWatch() {
  // Authenticate with Google and get an authorized client.
  const authClient = await authenticate({
    keyfilePath: path.join(__dirname, 'credentials.json'),
    scopes: 'https://www.googleapis.com/auth/drive',
  });

  // Create a new Forms API client.
  const formsClient = forms({
    version: 'v1',
    auth: authClient,
  });

  // The request body to create a watch.
  const watchRequest = {
    watch: {
      target: {
        topic: {
          // TODO: Replace with a valid Cloud Pub/Sub topic name.
          topicName: 'projects/<YOUR_TOPIC_PATH>',
        },
      },
      // The event type to watch for. 'RESPONSES' is the only supported type.
      eventType: 'RESPONSES',
    },
  };

  // Send the request to create the watch.
  const result = await formsClient.forms.watches.create({
    formId: formID,
    requestBody: watchRequest,
  });

  console.log(result.data);
  return result.data;
}

स्मार्टवॉच मिटाना

Python

forms/snippets/delete_watch.py

GitHub पर देखें

from apiclient import discovery
from httplib2 import Http
from oauth2client import client, file, tools

SCOPES = "https://www.googleapis.com/auth/drive"
DISCOVERY_DOC = "https://forms.googleapis.com/$discovery/rest?version=v1"

store = file.Storage("token.json")
creds = None
if not creds or creds.invalid:
  flow = client.flow_from_clientsecrets("client_secret.json", SCOPES)
  creds = tools.run_flow(flow, store)
service = discovery.build(
    "forms",
    "v1",
    http=creds.authorize(Http()),
    discoveryServiceUrl=DISCOVERY_DOC,
    static_discovery=False,
)

form_id = "<YOUR_FORM_ID>"
watch_id = "<YOUR_WATCH_ID>"

# Print JSON response after deleting a form watch
result = (
    service.forms().watches().delete(formId=form_id, watchId=watch_id).execute()
)
print(result)

Node.js

forms/snippets/delete_watch.js

GitHub पर देखें

import path from 'node:path';
import {authenticate} from '@google-cloud/local-auth';
import {forms} from '@googleapis/forms';

// TODO: Replace with a valid form ID.
const formID = '<YOUR_FORM_ID>';
// TODO: Replace with a valid watch ID.
const watchID = '<YOUR_FORMS_WATCH_ID>';

/**
 * Deletes a watch from a form.
 */
async function deleteWatch() {
  // Authenticate with Google and get an authorized client.
  const authClient = await authenticate({
    keyfilePath: path.join(__dirname, 'credentials.json'),
    scopes: 'https://www.googleapis.com/auth/drive',
  });

  // Create a new Forms API client.
  const formsClient = forms({
    version: 'v1',
    auth: authClient,
  });

  // Send the request to delete the watch.
  const result = await formsClient.forms.watches.delete({
    formId: formID,
    watchId: watchID,
  });

  console.log(result.data);
  return result.data;
}

अनुमति देना

Forms API को किए गए सभी कॉल की तरह, watches.create() को किए गए कॉल को भी अनुमति वाले टोकन से अनुमति दी जानी चाहिए. टोकन में एक स्कोप शामिल होना चाहिए. इससे उस डेटा को पढ़ने का ऐक्सेस मिलता है जिसके बारे में सूचनाएं भेजी जा रही हैं.

• स्कीमा में हुए बदलावों के लिए, इसका मतलब है कि forms.get() का इस्तेमाल करके, फ़ॉर्म को पढ़ने का ऐक्सेस देने वाला कोई भी स्कोप.
• जवाबों के लिए, इसका मतलब है कि कोई भी ऐसा स्कोप जो फ़ॉर्म के जवाबों को पढ़ने का ऐक्सेस देता है. उदाहरण के लिए, forms.responses.list() का इस्तेमाल करना.

सूचनाएं पाने के लिए, ऐप्लिकेशन को ज़रूरी स्कोप के साथ, अनुमति वाले उपयोगकर्ता से OAuth ग्रांट बनाए रखना होगा. अगर उपयोगकर्ता ऐप्लिकेशन को डिसकनेक्ट करता है, तो सूचनाएं मिलना बंद हो जाती हैं. साथ ही, गड़बड़ी की वजह से स्मार्टवॉच निलंबित हो सकती है. अनुमति वापस मिलने के बाद सूचनाएं फिर से पाने के लिए, स्मार्टवॉच को रिन्यू करना लेख पढ़ें.

किसी फ़ॉर्म की घड़ियों की सूची बनाना

Python

forms/snippets/list_watches.py

GitHub पर देखें

from apiclient import discovery
from httplib2 import Http
from oauth2client import client, file, tools

SCOPES = "https://www.googleapis.com/auth/drive"
DISCOVERY_DOC = "https://forms.googleapis.com/$discovery/rest?version=v1"

store = file.Storage("token.json")
creds = None
if not creds or creds.invalid:
  flow = client.flow_from_clientsecrets("client_secrets.json", SCOPES)
  creds = tools.run_flow(flow, store)
service = discovery.build(
    "forms",
    "v1",
    http=creds.authorize(Http()),
    discoveryServiceUrl=DISCOVERY_DOC,
    static_discovery=False,
)

form_id = "<YOUR_FORM_ID>"

# Print JSON list of form watches
result = service.forms().watches().list(formId=form_id).execute()
print(result)

Node.js

forms/snippets/list_watches.js

GitHub पर देखें

import path from 'node:path';
import {authenticate} from '@google-cloud/local-auth';
import {forms} from '@googleapis/forms';

// TODO: Replace with a valid form ID.
const formID = '<YOUR_FORM_ID>';

/**
 * Lists the watches for a given form.
 */
async function listWatches() {
  // Authenticate with Google and get an authorized client.
  const auth = await authenticate({
    keyfilePath: path.join(__dirname, 'credentials.json'),
    scopes: 'https://www.googleapis.com/auth/forms.responses.readonly',
  });

  // Create a new Forms API client.
  const formsClient = forms({
    version: 'v1',
    auth,
  });

  // Get the list of watches for the form.
  const result = await formsClient.forms.watches.list({
    formId: formID,
  });

  console.log(result.data);
  return result.data;
}

स्मार्टवॉच को रिन्यू करना

Python

forms/snippets/renew_watch.py

GitHub पर देखें

from apiclient import discovery
from httplib2 import Http
from oauth2client import client, file, tools

SCOPES = "https://www.googleapis.com/auth/drive"
DISCOVERY_DOC = "https://forms.googleapis.com/$discovery/rest?version=v1"

store = file.Storage("token.json")
creds = None
if not creds or creds.invalid:
  flow = client.flow_from_clientsecrets("client_secrets.json", SCOPES)
  creds = tools.run_flow(flow, store)
service = discovery.build(
    "forms",
    "v1",
    http=creds.authorize(Http()),
    discoveryServiceUrl=DISCOVERY_DOC,
    static_discovery=False,
)

form_id = "<YOUR_FORM_ID>"
watch_id = "<YOUR_WATCH_ID>"

# Print JSON response after renewing a form watch
result = (
    service.forms().watches().renew(formId=form_id, watchId=watch_id).execute()
)
print(result)

Node.js

forms/snippets/renew_watch.js

GitHub पर देखें

import path from 'node:path';
import {authenticate} from '@google-cloud/local-auth';
import {forms} from '@googleapis/forms';

// TODO: Replace with a valid form ID.
const formID = '<YOUR_FORM_ID>';
// TODO: Replace with a valid watch ID.
const watchID = '<YOUR_FORMS_WATCH_ID>';

/**
 * Renews a watch on a form.
 */
async function renewWatch() {
  // Authenticate with Google and get an authorized client.
  const authClient = await authenticate({
    keyfilePath: path.join(__dirname, 'credentials.json'),
    scopes: 'https://www.googleapis.com/auth/drive',
  });

  // Create a new Forms API client.
  const formsClient = forms({
    version: 'v1',
    auth: authClient,
  });

  // Send the request to renew the watch.
  const result = await formsClient.forms.watches.renew({
    formId: formID,
    watchId: watchID,
  });

  console.log(result.data);
  return result.data;
}

थ्रॉटलिंग

सूचनाएं भेजने की फ़्रीक्वेंसी कम कर दी जाती है. हर स्मार्टवॉच को हर 30 सेकंड में ज़्यादा से ज़्यादा एक सूचना मिल सकती है. फ़्रीक्वेंसी की इस सीमा में बदलाव किया जा सकता है.

थ्रॉटलिंग की वजह से, एक सूचना कई इवेंट से जुड़ी हो सकती है. दूसरे शब्दों में, सूचना से पता चलता है कि पिछली सूचना के बाद से एक या उससे ज़्यादा इवेंट हुए हैं.

सीमाएं

किसी भी समय, किसी दिए गए फ़ॉर्म और इवेंट टाइप के लिए, हर Cloud Console प्रोजेक्ट में ये हो सकते हैं:

• ज़्यादा से ज़्यादा 20 बार देखा गया
• हर उपयोगकर्ता के लिए, एक बार देखने की सुविधा

इसके अलावा, किसी भी समय, हर फ़ॉर्म में हर इवेंट टाइप के लिए, Cloud Console के सभी प्रोजेक्ट में कुल 50 वॉच तक सीमित होता है.

किसी घड़ी को असली उपयोगकर्ता से तब जोड़ा जाता है, जब उसे उस उपयोगकर्ता के क्रेडेंशियल का इस्तेमाल करके बनाया या रिन्यू किया जाता है. अगर घड़ी से जुड़े एंड यूज़र के पास फ़ॉर्म का ऐक्सेस नहीं रहता है या वह ऐप्लिकेशन के फ़ॉर्म के ऐक्सेस को रद्द कर देता है, तो घड़ी को निलंबित कर दिया जाता है.

विश्वसनीयता

हर स्मार्टवॉच को हर इवेंट के बाद कम से कम एक बार सूचना दी जाती है. हालांकि, कुछ खास मामलों में ऐसा नहीं किया जाता. ज़्यादातर मामलों में, इवेंट होने के कुछ ही मिनटों में सूचना मिल जाती है.

गड़बड़ियां

अगर किसी स्मार्टवॉच पर सूचनाएं लगातार नहीं मिलती हैं, तो स्मार्टवॉच की स्थिति SUSPENDED हो जाती है. साथ ही, स्मार्टवॉच का errorType फ़ील्ड सेट हो जाता है. निलंबित की गई स्मार्टवॉच की स्थिति को ACTIVE पर रीसेट करने और सूचनाएं फिर से पाने के लिए, स्मार्टवॉच का प्लान रिन्यू करें लेख पढ़ें.

इस्तेमाल के सुझाव

• एक ही Cloud Pub/Sub विषय का इस्तेमाल, कई वॉच के टारगेट के तौर पर करें.
• किसी विषय पर सूचना मिलने पर, फ़ॉर्म आईडी को सूचना के पेलोड में शामिल किया जाता है. इसका इस्तेमाल इवेंट टाइप के साथ किया जाता है, ताकि यह पता चल सके कि किस तरह का डेटा फ़ेच करना है और उसे किस फ़ॉर्म से फ़ेच करना है.
• EventType.RESPONSES वाली सूचना मिलने के बाद अपडेट किया गया डेटा पाने के लिए, forms.responses.list() को कॉल करें.
  • अनुरोध पर फ़िल्टर को timestamp > timestamp_of_the_last_response_you_fetched पर सेट करें.
• EventType.SCHEMA वाली सूचना मिलने के बाद, अपडेट किया गया डेटा पाने के लिए, forms.get() को कॉल करें.