इस दस्तावेज़ में, एपीआई कॉल को एक साथ बैच में भेजने का तरीका बताया गया है. इससे क्लाइंट के बनाए जाने वाले एचटीटीपी कनेक्शन कम हो जाते हैं.
यह दस्तावेज़, खास तौर पर एचटीटीपी अनुरोध भेजकर बैच अनुरोध करने के बारे में है. अगर बैच अनुरोध करने के लिए, Google की क्लाइंट लाइब्रेरी का इस्तेमाल किया जा रहा है, तो क्लाइंट लाइब्रेरी का दस्तावेज़ देखें.
खास जानकारी
क्लाइंट के हर एचटीटीपी कनेक्शन से कुछ हद तक ओवरहेड होता है. Google Classroom API में बैच में अनुरोध भेजने की सुविधा काम करती है. इससे आपका क्लाइंट, कई एपीआई कॉल को एक एचटीटीपी अनुरोध में शामिल कर सकता है.
बैचिंग का इस्तेमाल करने की स्थितियों के उदाहरण:
- ज़्यादा संख्या में कोर्स के लिए रोस्टर वापस पाना.
- एक साथ कई कोर्स बनाना या अपडेट करना.
- कोर्स की कई सूचियां जोड़ना.
- ज़्यादा उपयोगकर्ताओं के लिए कोर्स की सूचियां वापस पाना.
हर मामले में, हर कॉल को अलग-अलग भेजने के बजाय, उन्हें एक साथ एक एचटीटीपी अनुरोध में ग्रुप किया जा सकता है. सभी इनर अनुरोध, एक ही Google API पर जाने चाहिए.
एक बैच अनुरोध में ज़्यादा से ज़्यादा 50 कॉल किए जा सकते हैं. अगर आपको इससे ज़्यादा कॉल करने हैं, तो एक से ज़्यादा बैच अनुरोधों का इस्तेमाल करें.
ध्यान दें: Google Classroom API के लिए बैच सिस्टम, OData बैच प्रोसेसिंग सिस्टम के जैसा ही सिंटैक्स इस्तेमाल करता है. हालांकि, सिमैंटिक अलग-अलग होते हैं.
बैच की जानकारी
बैच अनुरोध में, कई एपीआई कॉल शामिल होते हैं. इन सभी को एक एचटीटीपी अनुरोध में शामिल करके, एपीआई की खोज से जुड़े दस्तावेज़ में बताए गए batchPath को भेजा जाता है. डिफ़ॉल्ट पाथ /batch/api_name/api_version है. इस सेक्शन में, बैच सिंटैक्स के बारे में पूरी जानकारी दी गई है. इसके बाद, एक उदाहरण दिया गया है.
ध्यान दें: एक साथ बैच किए गए n अनुरोधों के सेट को, इस्तेमाल की सीमा में n अनुरोधों के तौर पर गिना जाता है, न कि एक अनुरोध के तौर पर. बैच में भेजे गए अनुरोध को प्रोसेस करने से पहले, अनुरोधों के सेट में अलग किया जाता है.
एक साथ ग्रुप या बैच में भेजे गए अनुरोध का फ़ॉर्मैट
बैच अनुरोध, एक स्टैंडर्ड एचटीटीपी अनुरोध होता है. इसमें multipart/mixed कॉन्टेंट टाइप का इस्तेमाल करके, Google Classroom API के कई कॉल शामिल होते हैं. मुख्य एचटीटीपी अनुरोध में, हर हिस्से में नेस्ट किया गया एचटीटीपी अनुरोध होता है.
हर हिस्से की शुरुआत, उसके Content-Type: application/http एचटीटीपी हेडर से होती है. इसमें Content-ID हेडर भी हो सकता है. हालांकि, ऐसा करना ज़रूरी नहीं है. हालांकि, पार्ट हेडर सिर्फ़ पार्ट की शुरुआत को मार्क करने के लिए होते हैं. ये नेस्ट किए गए अनुरोध से अलग होते हैं. सर्वर, बैच अनुरोध को अलग-अलग अनुरोधों में बदलने के बाद, पार्ट हेडर को अनदेखा कर देता है.
हर हिस्से का कोड अपने-आप में एक अलग एचटीटीपी अनुरोध होता है. हर अनुरोध का अपना वर्ब, यूआरएल, हेडर, और कोड होता है. एचटीटीपी अनुरोध में, यूआरएल का सिर्फ़ पाथ वाला हिस्सा होना चाहिए. बैच अनुरोधों में पूरे यूआरएल इस्तेमाल करने की अनुमति नहीं है.
आउटर बैच अनुरोध के लिए एचटीटीपी हेडर, बैच में मौजूद हर अनुरोध पर लागू होते हैं. हालांकि, Content- हेडर, जैसे कि Content-Type, लागू नहीं होते. अगर आपने किसी एचटीटीपी हेडर को बाहरी अनुरोध और अलग-अलग कॉल, दोनों में शामिल किया है, तो अलग-अलग कॉल हेडर की वैल्यू, बाहरी बैच अनुरोध हेडर की वैल्यू को बदल देगी. किसी कॉल के हेडर, सिर्फ़ उसी कॉल पर लागू होते हैं.
उदाहरण के लिए, अगर आपने किसी कॉल के लिए Authorization हेडर दिया है, तो वह हेडर सिर्फ़ उस कॉल पर लागू होगा. अगर आपने बाहरी अनुरोध के लिए Authorization हेडर दिया है, तो वह हेडर सभी अलग-अलग कॉल पर लागू होता है. हालांकि, ऐसा तब तक होता है, जब तक वे अपने Authorization हेडर से इसे बदल नहीं देते.
जब सर्वर को बैच किया गया अनुरोध मिलता है, तो वह बाहरी अनुरोध के क्वेरी पैरामीटर और हेडर (ज़रूरत के मुताबिक) को हर हिस्से पर लागू करता है. इसके बाद, हर हिस्से को इस तरह से प्रोसेस करता है जैसे वह एक अलग एचटीटीपी अनुरोध हो.
बैच अनुरोध का जवाब
सर्वर का जवाब, multipart/mixed कॉन्टेंट टाइप वाला एक स्टैंडर्ड एचटीटीपी रिस्पॉन्स होता है. हर हिस्सा, बैच किए गए अनुरोध में शामिल किसी एक अनुरोध का जवाब होता है. यह जवाब, अनुरोधों के क्रम में ही होता है.
अनुरोध के हिस्सों की तरह, जवाब के हर हिस्से में एक पूरा एचटीटीपी जवाब होता है. इसमें स्टेटस कोड, हेडर, और कोड शामिल होता है. अनुरोध में शामिल हिस्सों की तरह, जवाब के हर हिस्से से पहले Content-Type हेडर होता है. इससे हिस्से की शुरुआत का पता चलता है.
अगर अनुरोध के किसी हिस्से में Content-ID हेडर मौजूद है, तो रिस्पॉन्स के उस हिस्से में भी Content-ID हेडर मौजूद होगा. इसमें ओरिजनल वैल्यू से पहले response- स्ट्रिंग मौजूद होगी. इसे यहां दिए गए उदाहरण में दिखाया गया है.
ध्यान दें: सर्वर, आपके कॉल किसी भी क्रम में कर सकता है. यह ज़रूरी नहीं है कि उन्हें उसी क्रम में लागू किया जाए जिस क्रम में आपने उन्हें तय किया है. अगर आपको यह पक्का करना है कि दो कॉल एक तय क्रम में हों, तो उन्हें एक ही अनुरोध में नहीं भेजा जा सकता. इसके बजाय, पहले कॉल को अलग से भेजें. इसके बाद, दूसरे कॉल को भेजने से पहले, पहले कॉल के जवाब का इंतज़ार करें.
उदाहरण
यहां दिए गए उदाहरण में, Google Classroom API के साथ बैचिंग का इस्तेमाल दिखाया गया है.
एक साथ ग्रुप या बैच में भेजे गए अनुरोध का उदाहरण
POST https://classroom.googleapis.com/batch HTTP/1.1
Authorization: Bearer your_auth_token
Content-Type: multipart/mixed; boundary=batch_foobarbaz
Content-Length: total_content_length
--batch_foobarbaz
Content-Type: application/http
Content-Transfer-Encoding: binary
MIME-Version: 1.0
Content-ID: <item1:12930812@classroom.example.com>
PATCH /v1/courses/134529639?updateMask=name HTTP/1.1
Content-Type: application/json; charset=UTF-8
Authorization: Bearer your_auth_token
{
"name": "Course 1"
}
--batch_foobarbaz
Content-Type: application/http
Content-Transfer-Encoding: binary
MIME-Version: 1.0
Content-ID: <item2:12930812@classroom.example.com>
PATCH /v1/courses/134529901?updateMask=section HTTP/1.1
Content-Type: application/json; charset=UTF-8
Authorization: Bearer your_auth_token
{
"section": "Section 2"
}
--batch_foobarbaz--
बैच रिस्पॉन्स का उदाहरण
यह पिछले सेक्शन में दिए गए उदाहरण के अनुरोध का जवाब है.
HTTP/1.1 200
Content-Length: response_total_content_length
Content-Type: multipart/mixed; boundary=batch_foobarbaz
--batch_foobarbaz
Content-Type: application/http
Content-ID: <response-item1:12930812@classroom.example.com>
HTTP/1.1 200 OK
Content-Type application/json
Content-Length: response_part_1_content_length
{
"id": "134529639",
"name": "Course 1",
"section": "Section 1",
"ownerId": "116269102540619633451",
"creationTime": "2015-06-25T14:23:56.535Z",
"updateTime": "2015-06-25T14:33:06.583Z",
"enrollmentCode": "6paeflo",
"courseState": "PROVISIONED",
"alternateLink": "http://classroom.google.com/c/MTM0NTI5NjM5"
}
--batch_foobarbaz
Content-Type: application/http
Content-ID: <response-item2:12930812@classroom.example.com>
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: response_part_2_content_length
{
"id": "134529901",
"name": "Course 1",
"section": "Section 2",
"ownerId": "116269102540619633451",
"creationTime": "2015-06-25T14:23:08.761Z",
"updateTime": "2015-06-25T14:33:06.490Z",
"enrollmentCode": "so75ha5",
"courseState": "PROVISIONED",
"alternateLink": "http://classroom.google.com/c/MTM0NTI5OTAx"
}
--batch_foobarbaz--
क्लाइंट लाइब्रेरी का इस्तेमाल करना
यहां दिए गए कोड के उदाहरणों में, Google APIs क्लाइंट लाइब्रेरी का इस्तेमाल करके बैच अनुरोध भेजने का तरीका बताया गया है. लाइब्रेरी इंस्टॉल करने और उन्हें सेट अप करने के बारे में ज़्यादा जानने के लिए, उनसे जुड़ी क्विकस्टार्ट गाइड देखें.
.NET
Java
PHP
Python
course_id = '123456' student_emails = ['alice@example.edu', 'bob@example.edu'] def callback(request_id, response, exception): if exception is not None: print 'Error adding user "{0}" to the course course: {1}'.format( request_id, exception) else: print 'User "{0}" added as a student to the course.'.format( response.get('profile').get('name').get('fullName')) batch = service.new_batch_http_request(callback=callback) for student_email in student_emails: student = { 'userId': student_email } request = service.courses().students().create(courseId=course_id, body=student) batch.add(request, request_id=student_email) batch.execute(http=http)