डोमेन के सभी उपयोगकर्ताओं के डेटा का ऐक्सेस देने की सुविधा की मदद से अनुमति देना

Mail Admin Quarantine API को सर्वर-साइड ऑटोमेशन के लिए डिज़ाइन किया गया है. जैसे, सुरक्षा पाइपलाइन और एसआईईएम या एसओएआर इंटिग्रेशन. ये ऑटोमेशन, Google Cloud सेवा खाते से पुष्टि करते हैं. यह खाता, पूरे डोमेन के लिए ऐक्सेस देने की सुविधा का इस्तेमाल करता है. इससे, Google Workspace एडमिन की ओर से कार्रवाई की जा सकती है. इसके लिए, एडमिन के पास एडमिन के अधिकार होने चाहिए.

इस पेज पर बताया गया है कि एपीआई को OAuth 2.0 के किन दायरों की ज़रूरत होती है. साथ ही, सेवा खाते को कॉन्फ़िगर करने और ऐक्सेस टोकन पाने का तरीका भी बताया गया है.

OAuth 2.0 के दायरे

Admin Quarantine API, OAuth 2.0 के इन दायरों का इस्तेमाल करता है:

दायरा मतलब
https://www.googleapis.com/auth/gmail.admin.quarantine क्वॉरंटीन किए गए मैसेज देखना और उन्हें मैनेज करना. मैसेज को अलग-अलग या बैच में रिलीज़ करने या अस्वीकार करने के लिए ज़रूरी है.
https://www.googleapis.com/auth/gmail.admin.quarantine.readonly क्वॉरंटीन किए गए मैसेज देखना. मैसेज की सूची देखने, उन्हें खोजने, और पाने के लिए ज़रूरी है. साथ ही, क्वॉरंटीन किए गए मैसेज की सूची देखने और उन्हें पाने के लिए ज़रूरी है. इसके अलावा, बैच ऑपरेशन की स्थिति देखने के लिए भी ज़रूरी है.

नीचे दी गई टेबल में बताया गया है कि हर तरीके के लिए कौनसा स्कोप स्वीकार किया जाता है:

तरीका gmail.admin.quarantine gmail.admin.quarantine.readonly
customers.quarantinedMessages.list ✓ ✓
customers.quarantinedMessages.search ✓ ✓
customers.quarantinedMessages.get ✓ ✓
customers.quarantines.list ✓ ✓
customers.quarantines.get ✓ ✓
customers.operations.get ✓ ✓
customers.quarantinedMessages.release ✓
customers.quarantinedMessages.deny ✓
customers.quarantinedMessages.batchRelease ✓
customers.quarantinedMessages.batchDeny ✓

कम से कम अधिकारों के सिद्धांत का पालन करें: सिर्फ़ क्वॉरंटीन की निगरानी करने वाले इंटिग्रेशन के लिए, रीड-ओनली स्कोप का अनुरोध करें.

अगर किसी अनुरोध में ऐसे टोकन का इस्तेमाल किया जाता है जिसमें स्वीकार किया गया स्कोप शामिल नहीं है, तो एपीआई 403 गड़बड़ी दिखाता है. साथ ही, इसकी वजह ACCESS_TOKEN_SCOPE_INSUFFICIENT बताता है.

सेवा खाता बनाना

  1. Google Cloud Console में, IAM और एडमिन > सेवा खाते पर जाएं. इसके बाद, वह Google Cloud प्रोजेक्ट चुनें जिसमें आपने एपीआई चालू किया है.
  2. सेवा खाता बनाएं पर क्लिक करें. इसके बाद, कोई नाम डालें, जैसे कि quarantine-api-service-account. इसके बाद, बनाएं और जारी रखें पर क्लिक करें. आपको सेवा खाते को कोई भी आईएएम भूमिका देने की ज़रूरत नहीं है. हो गया पर क्लिक करें.
  3. सेवा खाते को खोलें और जानकारी टैब में जाकर, OAuth 2 क्लाइंट आईडी को कॉपी करें. यह 21 अंकों का नंबर होता है. उदाहरण के लिए, 109876543210987654321. आपको अगले सेक्शन में इस आईडी की ज़रूरत होगी.
  4. कुंजियां टैब में, कुंजी जोड़ें > नई कुंजी बनाएं पर क्लिक करें. इसके बाद, JSON चुनें और बनाएं पर क्लिक करें. डाउनलोड की गई JSON कुंजी फ़ाइल को सुरक्षित तरीके से सेव करें.

ज़्यादा जानकारी के लिए, सेवा खाते के लिए क्रेडेंशियल बनाना लेख पढ़ें.

डोमेन के सभी उपयोगकर्ताओं के डेटा का ऐक्सेस देने की अनुमति देना

अपने Google Workspace खाते में, Admin Quarantine API के स्कोप को ऐक्सेस करने के लिए, सेवा खाते को अनुमति दें:

  1. सुपर एडमिन के तौर पर, Google Admin console में साइन इन करें.
  2. सुरक्षा > ऐक्सेस और डेटा कंट्रोल > एपीआई कंट्रोल पर जाएं.
  3. डोमेन के सभी उपयोगकर्ताओं के डेटा का ऐक्सेस दें में जाकर, डोमेन के सभी उपयोगकर्ताओं के डेटा का ऐक्सेस मैनेज करें पर क्लिक करें.
  4. नया जोड़ें पर क्लिक करें.
  5. क्लाइंट आईडी फ़ील्ड में, सेवा खाते का OAuth 2.0 क्लाइंट आईडी डालें. सेवा खाते का ईमेल पता न डालें.

  6. OAuth के दायरे फ़ील्ड में, इनमें से कोई एक दायरा डालें:

    • डेटा को ऐक्सेस करने और उसमें बदलाव करने की अनुमति देने के लिए: https://www.googleapis.com/auth/gmail.admin.quarantine
    • रीड-ओनली ऐक्सेस के लिए: https://www.googleapis.com/auth/gmail.admin.quarantine.readonly

  7. अनुमति दें पर क्लिक करें.

ज़्यादा जानकारी के लिए, पूरे डोमेन के लोगों को डेटा का ऐक्सेस देकर, एपीआई ऐक्सेस को कंट्रोल करना लेख पढ़ें.

ऐक्सेस टोकन पाना

एपीआई को कॉल करने के लिए, सेवा खाता किसी एडमिन के तौर पर काम करता है. इसके लिए, टोकन के अनुरोध के subject (sub) दावे को एडमिन के ईमेल पते पर सेट किया जाता है. एडमिन के पास एडमिन के ज़रूरी अधिकार होने चाहिए.

Python के इस उदाहरण में, ऐक्सेस टोकन पाने के लिए google-auth लाइब्रेरी का इस्तेमाल किया गया है:

from google.oauth2 import service_account
import google.auth.transport.requests

SERVICE_ACCOUNT_FILE = 'service_account.json'
# An administrator with the Access Admin Quarantine privilege.
ADMIN_EMAIL = 'admin@example.com'
SCOPES = ['https://www.googleapis.com/auth/gmail.admin.quarantine']

credentials = service_account.Credentials.from_service_account_file(
    SERVICE_ACCOUNT_FILE,
    scopes=SCOPES,
    subject=ADMIN_EMAIL,
)
credentials.refresh(google.auth.transport.requests.Request())
access_token = credentials.token

हर अनुरोध के Authorization हेडर में टोकन भेजें:

Authorization: Bearer ACCESS_TOKEN

ऐक्सेस टोकन एक घंटे बाद खत्म हो जाते हैं. अनुरोधों के हर बैच से पहले क्रेडेंशियल रीफ़्रेश करें. टोकन को लंबे समय तक कैश मेमोरी में सेव न करें.

अनुमति से जुड़ी गड़बड़ियों को ठीक करना

एचटीटीपी कोड स्थिति कारण रिज़ॉल्यूशन
401 UNAUTHENTICATED Authorization हेडर मौजूद नहीं है या टोकन गलत है या इसकी समयसीमा खत्म हो गई है. नया ऐक्सेस टोकन पाएं और उसे धारक टोकन के तौर पर शामिल करें.
403 ACCESS_TOKEN_SCOPE_INSUFFICIENT टोकन में ऐसा स्कोप शामिल नहीं है जिसे यह तरीका स्वीकार करता है. रिलीज़ और अस्वीकार करने के तरीकों के लिए, https://www.googleapis.com/auth/gmail.admin.quarantine स्कोप का अनुरोध करें. साथ ही, पक्का करें कि Admin console में स्कोप को अनुमति दी गई हो.
403 PERMISSION_DENIED जिस एडमिन की पहचान चुराई गई है उसके पास एडमिन क्वॉरंटीन की सुविधा नहीं है या उसके पास उस क्वॉरंटीन का ऐक्सेस नहीं है जिसमें मैसेज मौजूद है. एडमिन को एडमिन क्वॉरंटीन को ऐक्सेस करें या प्रतिबंधित क्वॉरंटीन को ऐक्सेस करें की अनुमति दें.
हर तरीके पर 403 SERVICE_DISABLED या 404 NOT_FOUND क्लाउड प्रोजेक्ट में एपीआई चालू नहीं है या प्रोजेक्ट को डेवलपर के लिए झलक वाले प्रोग्राम में रजिस्टर नहीं किया गया है. एपीआई चालू करें और Google Workspace डेवलपर के लिए झलक प्रोग्राम में अपने रजिस्ट्रेशन की पुष्टि करें.

अगले चरण