बंदूक पर लगने वाली दूरबीन

उपयोगकर्ताओं को ऐसे ऐड-ऑन और दूसरे ऐप्लिकेशन को अनुमति देनी होगी जो उनके डेटा को ऐक्सेस करते हैं या उनकी ओर से काम करते हैं. जब कोई उपयोगकर्ता पहली बार कोई ऐड-ऑन चलाता है, तो ऐड-ऑन का यूज़र इंटरफ़ेस (यूआई), अनुमति देने का अनुरोध दिखाता है.

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

यूआरएल स्ट्रिंग का इस्तेमाल करके, manifest में स्कोप का एलान किया जाता है. अनुमति देने के फ़्लो के दौरान, Apps Script उपयोगकर्ता को दायरे के बारे में ऐसी जानकारी दिखाता है जिसे कोई भी पढ़ सकता है. उदाहरण के लिए, आपका Google Workspace ऐड-ऑन, "मौजूदा मैसेज पढ़ें" स्कोप का इस्तेमाल कर सकता है. इसे आपके मेनिफ़ेस्ट में https://www.googleapis.com/auth/gmail.addons.current.message.readonly के तौर पर लिखा गया है. अनुमति देने के फ़्लो के दौरान, इस स्कोप वाला एक ऐड-ऑन, उपयोगकर्ता से इस ऐड-ऑन को अनुमति देने के लिए कहता है: ऐड-ऑन चलने के दौरान अपने ईमेल मैसेज देखना.

स्कोप देखना

अपने स्क्रिप्ट प्रोजेक्ट के लिए ज़रूरी स्कोप देखने के लिए, ये काम करें:

  1. स्क्रिप्ट प्रोजेक्ट खोलें.
  2. बाईं ओर, खास जानकारी पर क्लिक करें.
  3. "प्रोजेक्ट के OAuth दायरे" में जाकर, दायरे देखें.

प्रोजेक्ट मेनिफ़ेस्ट में, स्क्रिप्ट प्रोजेक्ट के मौजूदा स्कोप भी देखे जा सकते हैं. इसके लिए, oauthScopes फ़ील्ड में जाएं. हालांकि, ऐसा सिर्फ़ तब किया जा सकता है, जब आपने उन स्कोप को साफ़ तौर पर सेट किया हो.

अश्लील स्कोप सेट करना

Apps Script, स्क्रिप्ट के कोड को स्कैन करके यह अपने-आप तय करता है कि स्क्रिप्ट को कौनसे स्कोप की ज़रूरत है. इसके लिए, वह उन फ़ंक्शन कॉल के लिए कोड को स्कैन करता है जिनमें स्कोप की ज़रूरत होती है. ज़्यादातर स्क्रिप्ट के लिए यह तरीका काफ़ी होता है और इससे आपका समय बचता है. हालांकि, पब्लिश किए गए ऐड-ऑन के लिए, आपको स्कोप को सीधे तौर पर कंट्रोल करने की कोशिश करनी चाहिए.

उदाहरण के लिए, Apps Script किसी ऐड-ऑन स्क्रिप्ट प्रोजेक्ट को डिफ़ॉल्ट रूप से बहुत ज़्यादा अनुमति वाला स्कोप https://mail.google.com दे सकता है. जब कोई उपयोगकर्ता इस दायरे के साथ स्क्रिप्ट प्रोजेक्ट को अनुमति देता है, तो प्रोजेक्ट को उपयोगकर्ता के Gmail खाते का पूरा ऐक्सेस मिल जाता है. पब्लिश किए गए ऐड-ऑन के लिए, आपको इस स्कोप को ज़्यादा सीमित सेट से बदलना ज़रूरी है. यह सेट, ऐड-ऑन की ज़रूरतों को पूरा करता हो.

स्क्रिप्ट प्रोजेक्ट के मेनिफ़ेस्ट फ़ाइल में बदलाव करके, उन स्कोप को साफ़ तौर पर सेट किया जा सकता है जिनका इस्तेमाल प्रोजेक्ट करता है. मेनिफ़ेस्ट फ़ील्ड oauthScopes, ऐड-ऑन के इस्तेमाल किए गए सभी स्कोप का ऐरे होता है. अपने प्रोजेक्ट के स्कोप सेट करने के लिए, ये काम करें:

  1. उन स्कोप को देखें जिनका इस्तेमाल आपका ऐड-ऑन फ़िलहाल कर रहा है. तय करें कि कौनसे बदलाव करने हैं, जैसे कि छोटा स्कोप इस्तेमाल करके.
  2. अपने ऐड-ऑन की मेनिफ़ेस्ट फ़ाइल खोलें.
  3. oauthScopes लेबल वाले टॉप-लेवल फ़ील्ड का पता लगाएं. अगर यह मौजूद नहीं है, तो उसे जोड़ें.
  4. oauthScopes फ़ील्ड, स्ट्रिंग के कलेक्शन के बारे में बताता है. अपने प्रोजेक्ट में इस्तेमाल किए जाने वाले स्कोप सेट करने के लिए, इस कलेक्शन के कॉन्टेंट को उन स्कोप से बदलें जिनका इस्तेमाल आपको करना है. उदाहरण के लिए, Gmail की सुविधाओं को बढ़ाने वाले Google Workspace ऐड-ऑन के लिए, आपके पास ये विकल्प हो सकते हैं:

    {
      ...
      "oauthScopes": [
        "https://www.googleapis.com/auth/gmail.addons.current.message.metadata",
        "https://www.googleapis.com/auth/userinfo.email"
      ],
      ...
    }
    
  5. मेनिफ़ेस्ट फ़ाइल में किए गए बदलावों को सेव करें.

OAuth की मदद से पुष्टि करना

कुछ संवेदनशील OAuth दायरों का इस्तेमाल करने से पहले, आपको अपने ऐड-ऑन को पब्लिश करने से पहले OAuth क्लाइंट की पुष्टि करनी पड़ सकती है. ज़्यादा जानकारी के लिए, ये गाइड देखें:

पाबंदी वाले दायरे

कुछ स्कोप पर पाबंदी होती है. साथ ही, इन पर ऐसे अतिरिक्त नियम लागू होते हैं जिनसे उपयोगकर्ता के डेटा को सुरक्षित रखने में मदद मिलती है. अगर आपको Gmail या Editor का कोई ऐसा ऐड-ऑन पब्लिश करना है जिसमें एक या उससे ज़्यादा पाबंदी वाले स्कोप का इस्तेमाल किया गया है, तो पब्लिश करने से पहले ऐड-ऑन को बताई गई सभी पाबंदियों का पालन करना होगा.

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

Google Workspace ऐड-ऑन के लिए स्कोप चुनना

यहां दिए गए सेक्शन में, Google Workspace के ऐड-ऑन के लिए आम तौर पर इस्तेमाल होने वाले स्कोप दिए गए हैं.

एडिटर के दायरे

यहां, Google Workspace के उन ऐड-ऑन के लिए अक्सर इस्तेमाल होने वाले स्कोप दिए गए हैं जो Docs, Sheets, और Slides के साथ काम करते हैं.

दायरा
Docs में फ़ाइल का मौजूदा ऐक्सेस https://www.googleapis.com/auth/documents.currentonly

अगर ऐड-ऑन, Apps Script Docs API को ऐक्सेस करता है, तो यह ज़रूरी है. खुले हुए दस्तावेज़ के कॉन्टेंट का कुछ समय के लिए ऐक्सेस देता है.

Sheets की फ़ाइल का मौजूदा ऐक्सेस https://www.googleapis.com/auth/spreadsheets.currentonly

अगर ऐड-ऑन, Apps Script Sheets API को ऐक्सेस करता है, तो यह ज़रूरी है. ओपन स्प्रेडशीट के कॉन्टेंट का कुछ समय के लिए ऐक्सेस देता है.

Slides में फ़ाइल का मौजूदा ऐक्सेस https://www.googleapis.com/auth/presentations.currentonly

अगर ऐड-ऑन, Apps Script Slides API को ऐक्सेस करता है, तो यह ज़रूरी है. ओपन प्रज़ेंटेशन के कॉन्टेंट का कुछ समय के लिए ऐक्सेस देता है.

हर फ़ाइल के लिए ऐक्सेस https://www.googleapis.com/auth/drive.file

ऐड-ऑन के लिए onFileScopeGrantedTrigger का इस्तेमाल करना ज़रूरी है. साथ ही, अगर ऐड-ऑन Docs, Sheets, Slides या Drive API को ऐक्सेस करता है, तो यह भी ज़रूरी है. Apps Script की बेहतर Drive सेवा का इस्तेमाल करके, ऐप्लिकेशन से बनाई गई या खोली गई फ़ाइलों को हर फ़ाइल के हिसाब से ऐक्सेस करने की अनुमति देता है. हालांकि, इससे Drive की बुनियादी सेवा का इस्तेमाल करके, मिलती-जुलती कार्रवाइयां करने की अनुमति नहीं मिलती. हर फ़ाइल के हिसाब से, फ़ाइल की अनुमति दी जाती है और जब उपयोगकर्ता ऐप्लिकेशन से अनुमति हटाता है, तो यह अनुमति रद्द कर दी जाती है.

Gmail

कुछ स्कोप खास तौर पर Google Workspace के ऐड-ऑन के लिए बनाए गए हैं. इनकी मदद से, उपयोगकर्ता के Gmail डेटा को सुरक्षित रखा जा सकता है. आपको अपने ऐड-ऑन मेनिफ़ेस्ट में, इन स्कोप को साफ़ तौर पर जोड़ना होगा. साथ ही, आपको उन सभी स्कोप को भी जोड़ना होगा जिनकी ज़रूरत आपके ऐड-ऑन कोड को है.

यहां Gmail के साथ काम करने वाले Google Workspace ऐड-ऑन के लिए, अक्सर इस्तेमाल होने वाले स्कोप दिए गए हैं. अगर आपका ऐड-ऑन Gmail के साथ काम करता है, तो ज़रूरी है लेबल वाले स्कोप को अपने Google Workspace ऐड-ऑन मेनिफ़ेस्ट में जोड़ना होगा.

अपने ऐड-ऑन में, बहुत बड़े https://mail.google.com स्कोप को छोटे स्कोप के सेट से भी बदलना न भूलें. इससे आपके ऐड-ऑन को सिर्फ़ ज़रूरी इंटरैक्शन मिल पाएंगे.

दायरा
नए ड्राफ़्ट बनाना https://www.googleapis.com/auth/gmail.addons.current.action.compose

अगर ऐड-ऑन, कंपोज़ ऐक्शन ट्रिगर का इस्तेमाल करता है, तो यह एट्रिब्यूट ज़रूरी है. इसकी मदद से, ऐड-ऑन कुछ समय के लिए नए ड्राफ़्ट मैसेज और जवाब बना सकता है. ज़्यादा जानकारी के लिए, मैसेज का ड्राफ़्ट लिखना देखें; इस स्कोप का इस्तेमाल अक्सर ऐक्शन लिखने के साथ भी किया जाता है. इसके लिए, ऐक्सेस टोकन की ज़रूरत होती है.

खुले हुए मैसेज का मेटाडेटा पढ़ना https://www.googleapis.com/auth/gmail.addons.current.message.metadata

यह अनुमति, खोले गए मैसेज के मेटाडेटा (जैसे, विषय या पाने वाले) का कुछ समय के लिए ऐक्सेस देती है. मैसेज का कॉन्टेंट पढ़ने की अनुमति नहीं देता और इसके लिए ऐक्सेस टोकन की ज़रूरत होती है.

अगर ऐड-ऑन, कार्रवाई लिखने के ट्रिगर में मेटाडेटा का इस्तेमाल करता है, तो यह ज़रूरी है. कॉम्पोज़ ऐक्शन के लिए, यह स्कोप तब ज़रूरी होता है, जब कॉम्पोज़ ट्रिगर को मेटाडेटा का ऐक्सेस चाहिए. व्यावहारिक तौर पर, इस स्कोप की मदद से कंपोज़ किसी जवाब वाले ईमेल के ड्राफ़्ट की, ऐक्सेस पाने वालों की सूचियों (इन्हें:, cc:, और bcc:) ऐक्सेस ट्रिगर किया जा सकता है.

खुले हुए मैसेज का कॉन्टेंट पढ़ना https://www.googleapis.com/auth/gmail.addons.current.message.action

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

ओपन थ्रेड का कॉन्टेंट पढ़ना https://www.googleapis.com/auth/gmail.addons.current.message.readonly

ओपन मैसेज के मेटाडेटा और कॉन्टेंट का कुछ समय के लिए ऐक्सेस देता है. साथ ही, खुले थ्रेड में मौजूद अन्य मैसेज के कॉन्टेंट का ऐक्सेस देता है. इसके लिए, ऐक्सेस टोकन की ज़रूरत होती है.

किसी भी मैसेज का कॉन्टेंट और मेटाडेटा पढ़ सकता है https://www.googleapis.com/auth/gmail.readonly

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

Google Calendar के स्कोप

यहां Google Workspace ऐड-ऑन के लिए, अक्सर इस्तेमाल किए जाने वाले दायरों के बारे में बताया गया है. इनकी मदद से Google Calendar को बेहतर बनाया जा सकता है.

दायरा
इवेंट का मेटाडेटा ऐक्सेस करना https://www.googleapis.com/auth/calendar.addons.execute

अगर ऐड-ऑन, Calendar इवेंट का मेटाडेटा ऐक्सेस करता है, तो यह ज़रूरी है. इससे ऐड-ऑन को इवेंट का मेटाडेटा ऐक्सेस करने की अनुमति मिलती है.

उपयोगकर्ता से जनरेट हुए इवेंट का डेटा पढ़ना https://www.googleapis.com/auth/calendar.addons.current.event.read

अगर ऐड-ऑन को उपयोगकर्ता से जनरेट किया गया इवेंट डेटा पढ़ना है, तो यह ज़रूरी है. इससे, ऐड-ऑन को उपयोगकर्ता से जनरेट हुए इवेंट डेटा को ऐक्सेस करने की अनुमति मिलती है. यह डेटा सिर्फ़ तब उपलब्ध होता है, जब addOns.calendar.eventAccess मेनिफ़ेस्ट फ़ील्ड को READ या READ_WRITE पर सेट किया गया हो.

उपयोगकर्ता से जनरेट हुए इवेंट का डेटा सेव करना https://www.googleapis.com/auth/calendar.addons.current.event.write

अगर ऐड-ऑन को उपयोगकर्ता से जनरेट किया गया इवेंट डेटा लिखना है, तो यह ज़रूरी है. उपयोगकर्ता के जनरेट किए गए इवेंट डेटा में बदलाव करने की अनुमति देता है. यह डेटा सिर्फ़ तब उपलब्ध होता है, जब addOns.calendar.eventAccess मेनिफ़ेस्ट फ़ील्ड को WRITE या READ_WRITE पर सेट किया गया हो.

Google Drive के स्कोप

यहां Google Workspace के उन ऐड-ऑन के लिए अक्सर इस्तेमाल होने वाले स्कोप दिए गए हैं जो Google Drive की सुविधाओं को बेहतर बनाते हैं.

दायरा
चुने गए आइटम का मेटाडेटा पढ़ना https://www.googleapis.com/auth/drive.addons.metadata.readonly

यह तब ज़रूरी है, जब उपयोगकर्ता के Drive में आइटम चुनने पर, ऐड-ऑन काम के इंटरफ़ेस को लागू करता हो. इससे, ऐड-ऑन को उन आइटम का सीमित मेटाडेटा पढ़ने की अनुमति मिलती है जिन्हें उपयोगकर्ता ने Google Drive में चुना है. मेटाडेटा में आइटम का आईडी, टाइटल, एमआईएम टाइप, आइकॉन का यूआरएल, और यह जानकारी शामिल होती है कि ऐड-ऑन के पास आइटम को ऐक्सेस करने की अनुमति है या नहीं.

हर फ़ाइल के लिए ऐक्सेस https://www.googleapis.com/auth/drive.file

अगर ऐड-ऑन को अलग-अलग Drive फ़ाइलों को ऐक्सेस करना है, तो इसका सुझाव दिया जाता है. Apps Script की बेहतर Drive सेवा का इस्तेमाल करके, ऐप्लिकेशन से बनाई गई या खोली गई फ़ाइलों को हर फ़ाइल के लिए ऐक्सेस देता है. हालांकि, इससे Drive की बुनियादी सेवा का इस्तेमाल करके, मिलती-जुलती कार्रवाइयां करने की अनुमति नहीं मिलती. फ़ाइल का ऐक्सेस, हर फ़ाइल के हिसाब से दिया जाता है. साथ ही, उपयोगकर्ता के ऐप्लिकेशन से फ़ाइल का ऐक्सेस हटाने पर, यह ऐक्सेस रद्द कर दिया जाता है.

चुनी गई फ़ाइलों के लिए फ़ाइल का ऐक्सेस पाने का अनुरोध करने का उदाहरण देखें.

ऐक्सेस टोकन

उपयोगकर्ता के डेटा को सुरक्षित रखने के लिए, Google Workspace के ऐड-ऑन में इस्तेमाल किए गए Gmail स्कोप, उपयोगकर्ता के डेटा का सिर्फ़ कुछ समय के लिए ऐक्सेस देते हैं. कुछ समय के लिए ऐक्सेस देने की सुविधा चालू करने के लिए, आपको आर्ग्युमेंट के तौर पर ऐक्सेस टोकन का इस्तेमाल करके, फ़ंक्शन GmailApp.setCurrentMessageAccessToken(accessToken) को कॉल करना होगा. आपको ऐक्शन इवेंट ऑब्जेक्ट से ऐक्सेस टोकन लेना होगा.

यहां, मैसेज के मेटाडेटा को ऐक्सेस करने की अनुमति देने के लिए, ऐक्सेस टोकन सेट करने का उदाहरण दिया गया है. इस उदाहरण के लिए, सिर्फ़ https://www.googleapis.com/auth/gmail.addons.current.message.metadata का स्कोप ज़रूरी है.

function readSender(e) {
  var accessToken = e.gmail.accessToken;
  var messageId = e.gmail.messageId;

  // The following function enables short-lived access to the current
  // message in Gmail. Access to other Gmail messages or data isn't
  // permitted.
  GmailApp.setCurrentMessageAccessToken(accessToken);
  var mailMessage = GmailApp.getMessageById(messageId);
  return mailMessage.getFrom();
}

Google Workspace के अन्य स्कोप

अगर आपका ऐड-ऑन, Google Workspace या Apps Script की अन्य सेवाओं का इस्तेमाल करता है, तो हो सकता है कि उसे अन्य स्कोप की ज़रूरत पड़े. ज़्यादातर मामलों में, Apps Script को इन स्कोप का पता लगाने और मैनिफ़ेस्ट को अपने-आप अपडेट करने की अनुमति दी जा सकती है. अपने मेनिफ़ेस्ट के स्कोप की सूची में बदलाव करते समय, किसी भी स्कोप को तब तक न हटाएं, जब तक कि उसे किसी ज़्यादा सही विकल्प से बदला न जा रहा हो. जैसे, किसी छोटे स्कोप से.

इस टेबल में उन स्कोप की सूची दी गई है जिनका इस्तेमाल Google Workspace के ऐड-ऑन अक्सर करते हैं:

दायरा
उपयोगकर्ता का ईमेल पता पढ़ना https://www.googleapis.com/auth/userinfo.email

इससे प्रोजेक्ट को मौजूदा उपयोगकर्ता का ईमेल पता पढ़ने की अनुमति मिलती है.

बाहरी सेवाओं को कॉल करने की अनुमति दें https://www.googleapis.com/auth/script.external_request

इससे प्रोजेक्ट को UrlFetch अनुरोध करने की अनुमति मिलती है. अगर प्रोजेक्ट में Apps Script के लिए OAuth2 लाइब्रेरी का इस्तेमाल किया जाता है, तो भी यह ज़रूरी है.

उपयोगकर्ता की स्थानीय भाषा और टाइमज़ोन की जानकारी देखना https://www.googleapis.com/auth/script.locale

इससे प्रोजेक्ट को, मौजूदा उपयोगकर्ता की स्थानीय भाषा और टाइमज़ोन के बारे में पता चलता है. ज़्यादा जानकारी के लिए, उपयोगकर्ता की स्थानीय भाषा और टाइमज़ोन को ऐक्सेस करना लेख पढ़ें.

ट्रिगर बनाएं https://www.googleapis.com/auth/script.scriptapp

इससे प्रोजेक्ट को ट्रिगर बनाने की अनुमति मिलती है.

तीसरे पक्ष के लिंक की झलक देखना https://www.googleapis.com/auth/workspace.linkpreview

अगर ऐड-ऑन की झलक, तीसरे पक्ष की सेवा के लिंक दिखाती है, तो यह ज़रूरी है. इससे उपयोगकर्ता, Google Workspace ऐप्लिकेशन में मौजूद लिंक को उस समय देख सकता है, जब उपयोगकर्ता उससे इंटरैक्ट कर रहा हो. ज़्यादा जानने के लिए, स्मार्ट चिप की मदद से लिंक की झलक देखना लेख पढ़ें.

तीसरे पक्ष के संसाधन बनाएं https://www.googleapis.com/auth/workspace.linkcreate

अगर ऐड-ऑन, तीसरे पक्ष की सेवा में संसाधन बनाता है, तो यह ज़रूरी है. इससे प्रोजेक्ट को वह जानकारी पढ़ने की अनुमति मिलती है जो उपयोगकर्ता, संसाधन बनाने वाले फ़ॉर्म में सबमिट करते हैं. साथ ही, इससे प्रोजेक्ट को Google Workspace ऐप्लिकेशन में संसाधन का लिंक डालने की अनुमति भी मिलती है. ज़्यादा जानने के लिए, @ मेन्यू से तीसरे पक्ष के संसाधन बनाना लेख पढ़ें.