जब आपको क्वॉरंटीन किए गए कई ईमेल पर एक साथ कार्रवाई करनी हो, तो Mail Admin Quarantine API में customers.quarantinedMessages रिसॉर्स के बैच मेथड का इस्तेमाल करें:
batchReleaseतरीका, ज़्यादा से ज़्यादा 500 मैसेज रिलीज़ करता है.batchDenyतरीके से, ज़्यादा से ज़्यादा 500 मैसेज अस्वीकार किए जा सकते हैं.
दोनों तरीके एसिंक्रोनस हैं. एपीआई, अनुरोध को स्वीकार करता है और ज़्यादा समय तक चलने वाली कार्रवाई दिखाता है. साथ ही, बैकग्राउंड में मैसेज प्रोसेस करता है. इसके बाद, कार्रवाई पूरी होने तक customers.operations संसाधन के get तरीके को पोल करें. साथ ही, जवाब से हर मैसेज के नतीजे पढ़ें.
लूप में सिंगल-मैसेज वाले तरीकों को कॉल करने की तुलना में, बैच वाले तरीकों को आपके कोटे के इस्तेमाल के लिए, एक राइट रिक्वेस्ट के तौर पर गिना जाता है. इससे कोई फ़र्क़ नहीं पड़ता कि उनमें कितने मैसेज हैं.
ज़रूरी शर्तें
- आपने एपीआई सेट अप करें में दिए गए चरणों को पूरा कर लिया हो.
- ऐसा ऐक्सेस टोकन जो एडमिन के तौर पर काम करता है. इसके पास एडमिन के तौर पर, ईमेल को क्वॉरंटीन करने का खास अधिकार होता है. साथ ही, इसमें
https://www.googleapis.com/auth/gmail.admin.quarantineस्कोप शामिल होता है. डोमेन के सभी उपयोगकर्ताओं के डेटा का ऐक्सेस देकर अनुमति दें देखें. PENDING_TRIAGEस्थिति में मौजूद, क्वॉरंटीन किए गए ज़्यादा से ज़्यादा 500 मैसेज के रिसॉर्स नेम. ये नाम आपको क्वॉरंटीन किए गए मैसेज की सूची और उन्हें खोजने की सुविधा से मिलते हैं.
एक साथ कई कार्रवाइयां करना
मैसेज को बैच में रिलीज़ करने के लिए, customers.quarantinedMessages संसाधन पर :batchRelease कस्टम तरीके से POST अनुरोध भेजें. requests कलेक्शन में हर मैसेज के लिए एक ऑब्जेक्ट होता है. हर ऑब्जेक्ट में मैसेज का रिसॉर्स नेम होता है:
POST https://mailadminquarantine.googleapis.com/v1/customers/CUSTOMER_ID/quarantinedMessages:batchRelease
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
{
"requests": [
{"name": "customers/CUSTOMER_ID/quarantinedMessages/user1@example.com:18d3ef45a8b2c1d0"},
{"name": "customers/CUSTOMER_ID/quarantinedMessages/user2@example.com:18d3ef45a8b2c1d1"}
]
}
एक साथ कई मैसेज को अस्वीकार करने के लिए, customers.quarantinedMessages संसाधन पर :batchDeny कस्टम तरीके को अनुरोध का वही मुख्य हिस्सा भेजें:
POST https://mailadminquarantine.googleapis.com/v1/customers/CUSTOMER_ID/quarantinedMessages:batchDeny
हर अनुरोध में एक से 500 एंट्री होनी चाहिए. हर मैसेज, अनुरोध पाथ में मौजूद ग्राहक का होना चाहिए. अगर किसी अनुरोध में 500 से ज़्यादा एंट्री हैं, तो 400 INVALID_ARGUMENT गड़बड़ी का मैसेज दिखता है.
एपीआई तुरंत Operation रिसॉर्स के साथ जवाब देता है:
{
"name": "customers/01abc23de/operations/7f1c2a0e-5b7d-4d3a-9c1e-2f4b6a8d0e13",
"metadata": {
"@type": "type.googleapis.com/google.gmail.mailadminquarantine.v1.BatchReleaseQuarantinedMessagesMetadata",
"state": "PROCESSING",
"processedCount": 0,
"totalCount": 2
},
"done": false
}
कार्रवाई का name सेव करें. ऑपरेशन की प्रोग्रेस देखने के लिए, आपको इसकी ज़रूरत होगी.
बैच ऑपरेशन का स्टेटस देखना
किसी बैच ऑपरेशन की प्रोग्रेस देखने के लिए, ऑपरेशन के रिसॉर्स के नाम पर get तरीके का इस्तेमाल करके, GET अनुरोध भेजें:
GET https://mailadminquarantine.googleapis.com/v1/customers/CUSTOMER_ID/operations/OPERATION_ID
Authorization: Bearer ACCESS_TOKEN
get तरीके में, Admin Quarantine API के स्कोप में से किसी एक को स्वीकार किया जाता है. इसलिए, रीड-ओनली इंटिग्रेशन, किसी दूसरे सिस्टम से शुरू की गई कार्रवाइयों को मॉनिटर कर सकता है.
कार्रवाई के दौरान, done फ़ील्ड को false पर सेट किया जाता है और metadata फ़ील्ड, प्रोग्रेस की जानकारी देता है:
| मेटाडेटा फ़ील्ड | ब्यौरा |
|---|---|
state |
मैसेज प्रोसेस होने के दौरान PROCESSING, फिर SUCCEEDED या FAILED. |
processedCount |
अब तक प्रोसेस किए गए मैसेज की संख्या. |
totalCount |
बैच में मौजूद मैसेज की कुल संख्या. |
कार्रवाई पूरी होने पर, done फ़ील्ड को true पर सेट कर दिया जाता है. साथ ही, response फ़ील्ड में बैच के हर मैसेज का नतीजा दिखता है:
{
"name": "customers/01abc23de/operations/7f1c2a0e-5b7d-4d3a-9c1e-2f4b6a8d0e13",
"metadata": {
"@type": "type.googleapis.com/google.gmail.mailadminquarantine.v1.BatchReleaseQuarantinedMessagesMetadata",
"state": "SUCCEEDED",
"processedCount": 2,
"totalCount": 2
},
"done": true,
"response": {
"@type": "type.googleapis.com/google.gmail.mailadminquarantine.v1.BatchReleaseQuarantinedMessagesResponse",
"results": [
{
"name": "customers/01abc23de/quarantinedMessages/user1@example.com:18d3ef45a8b2c1d0",
"status": {},
"quarantinedMessage": {
"name": "customers/01abc23de/quarantinedMessages/user1@example.com:18d3ef45a8b2c1d0",
"messageId": "18d3ef45a8b2c1d0",
"messageOwner": "user1@example.com",
"state": "RELEASED"
}
},
{
"name": "customers/01abc23de/quarantinedMessages/user2@example.com:18d3ef45a8b2c1d1",
"status": {
"code": 5,
"message": "Quarantined message not found"
}
}
]
}
}
results में मौजूद हर एंट्री, एक मैसेज के नतीजे के बारे में बताती है:
| नतीजे वाला फ़ील्ड | ब्यौरा |
|---|---|
name |
मैसेज के संसाधन का नाम. |
status |
google.rpc.Status. खाली ऑब्जेक्ट (कोड 0, OK) का मतलब है कि कार्रवाई पूरी हो गई है. अगर ऐसा नहीं है, तो code और message से पता चलता है कि मैसेज को क्यों छोड़ा गया. |
quarantinedMessage |
अपडेट किया गया मैसेज, जिसमें नई state शामिल है. यह सिर्फ़ तब मौजूद होता है, जब status, OK हो. |
बैच ऑपरेशन तब भी सफल होता है, जब कुछ मैसेज नहीं भेजे जा पाते. सिर्फ़ ऑपरेशन के state पर भरोसा करने के बजाय, हर नतीजे के status की जांच हमेशा करें.
अगर पूरी कार्रवाई पूरी नहीं हो पाती है, तो उदाहरण के लिए, बैकएंड उपलब्ध न होने की वजह से, done फ़ील्ड को true पर सेट किया जाता है. साथ ही, error फ़ील्ड में response के बजाय google.rpc.Status शामिल होता है.
उदाहरण: बैच रिलीज़ और पूरा होने के लिए पोल
Python के इस उदाहरण में, बैच रिलीज़ शुरू करने और हर कुछ सेकंड में कार्रवाई को पोल करने का तरीका बताया गया है. ऐसा तब तक किया जाता है, जब तक कि कार्रवाई पूरी नहीं हो जाती:
import time
import requests
BASE_URL = 'https://mailadminquarantine.googleapis.com/v1'
CUSTOMER_ID = '01abc23de' # Your customer ID without the leading 'C'.
headers = {
'Authorization': f'Bearer {access_token}',
'Content-Type': 'application/json',
}
# message_names is a list of up to 500 quarantined message resource names.
batch_url = f'{BASE_URL}/customers/{CUSTOMER_ID}/quarantinedMessages:batchRelease'
body = {'requests': [{'name': name} for name in message_names]}
operation = requests.post(batch_url, headers=headers, json=body)
operation.raise_for_status()
operation_name = operation.json()['name']
while True:
status = requests.get(f'{BASE_URL}/{operation_name}', headers=headers)
status.raise_for_status()
operation = status.json()
if operation.get('done'):
break
metadata = operation.get('metadata', {})
print(f"Processed {metadata.get('processedCount', 0)} of "
f"{metadata.get('totalCount', 0)} messages...")
time.sleep(5)
if 'error' in operation:
raise RuntimeError(f"Batch failed: {operation['error']}")
for result in operation['response'].get('results', []):
if result.get('status', {}).get('code', 0) == 0:
print(f"Released: {result['name']}")
else:
print(f"Skipped {result['name']}: {result['status'].get('message')}")