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

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

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

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

स्कोप देखना

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

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

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

साफ़ तौर पर दायरे सेट करना

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

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

स्क्रिप्ट प्रोजेक्ट के manifest फ़ाइल में बदलाव करके, उन स्कोप को साफ़ तौर पर सेट किया जा सकता है जिनका इस्तेमाल प्रोजेक्ट करता है. मेनिफ़ेस्ट फ़ील्ड 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 क्लाइंट की पुष्टि की जाए. ज़्यादा जानकारी के लिए, ये गाइड देखें:

• Apps Script के लिए OAuth क्लाइंट की पुष्टि करना
• पुष्टि नहीं किए गए ऐप्लिकेशन
• OAuth की पुष्टि से जुड़े अक्सर पूछे जाने वाले सवाल
• Google API सेवा: उपयोगकर्ता के डेटा की नीति

सीमित दायरे

कुछ स्कोप पर पाबंदी होती है. साथ ही, इन पर ऐसे अतिरिक्त नियम लागू होते हैं जिनसे उपयोगकर्ता के डेटा को सुरक्षित रखने में मदद मिलती है. अगर आपको 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 यह अनुमति, खोले गए मैसेज के मेटाडेटा (जैसे, विषय या पाने वाले) का कुछ समय के लिए ऐक्सेस देती है. मैसेज का कॉन्टेंट पढ़ने की अनुमति नहीं देता और इसके लिए ऐक्सेस टोकन की ज़रूरत होती है. अगर ऐड-ऑन, कार्रवाई लिखने के लिए ट्रिगर में मेटाडेटा का इस्तेमाल करता है, तो यह ज़रूरी है. कॉम्पोज़ ऐक्शन के लिए, यह स्कोप तब ज़रूरी है, जब कॉम्पोज़ ट्रिगर को मेटाडेटा का ऐक्सेस चाहिए. आम तौर पर, इस स्कोप की मदद से, जवाब वाले ईमेल ड्राफ़्ट के लिए, रिसीपिएंट की सूचियां (to:, 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 Calendar के साथ काम करने वाले Google Workspace ऐड-ऑन के लिए, अक्सर इस्तेमाल होने वाले स्कोप दिए गए हैं.

दायरा
इवेंट का मेटाडेटा ऐक्सेस करना	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 ऐप्लिकेशन में संसाधन का लिंक डालने की अनुमति भी मिलती है. ज़्यादा जानने के लिए, @ मेन्यू से तीसरे पक्ष के संसाधन बनाना लेख पढ़ें.