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

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

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

यूआरएल स्ट्रिंग का इस्तेमाल करके, मेनिफ़ेस्ट में स्कोप की जानकारी दी जाती है. अनुमति देने के दौरान, 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 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 पर सेट किया गया हो.

Drive के स्कोप

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

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

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

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

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

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

Gmail ऐड-ऑन दायरे

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

यहां Google Workspace ऐड-ऑन के लिए अक्सर इस्तेमाल किए जाने वाले ऐसे दायरे दिए गए हैं जो Gmail के साथ काम करते हैं. अगर आपका ऐड-ऑन, 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 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 ऐड-ऑन के लिए अक्सर इस्तेमाल किए जाने वाले दायरे यहां दिए गए हैं. इनमें 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 सेवा का इस्तेमाल करके, इस तरह की कार्रवाइयों के इस्तेमाल की अनुमति नहीं देता. फ़ाइल की अनुमति हर फ़ाइल के आधार पर दी जाती है और जब उपयोगकर्ता ऐप्लिकेशन से अनुमति हटाता है, तो उसे रद्द कर दिया जाता है.

अन्य दायरे

अगर आपका ऐड-ऑन अन्य Apps Script सेवाओं का इस्तेमाल करता है, तो उसके लिए अतिरिक्त दायरों की ज़रूरत पड़ सकती है. ज़्यादातर मामलों में, 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 ऐप्लिकेशन में लिंक देखने की अनुमति मिलती है. ऐसा तब होता है, जब उपयोगकर्ता उस प्रोजेक्ट को Google Workspace ऐप्लिकेशन से इंटरैक्ट कर रहा हो. ज़्यादा जानने के लिए, स्मार्ट चिप की मदद से लिंक की झलक देखना देखें.

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

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