इस दस्तावेज़ में, एपीआई कॉल को बैच में शामिल करने का तरीका बताया गया है. इससे, क्लाइंट को कम से कम एचटीटीपी कनेक्शन बनाने पड़ते हैं.
इस दस्तावेज़ में, एचटीटीपी अनुरोध भेजकर बैच में अनुरोध करने के बारे में बताया गया है. अगर बैच में अनुरोध करने के लिए, 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 पर यह लागू नहीं होता. अगर बाहरी अनुरोध और किसी एक कॉल, दोनों में कोई एचटीटीपी हेडर बताया जाता है, तो एक कॉल के हेडर की वैल्यू, बैच में किए गए बाहरी अनुरोध के हेडर की वैल्यू को बदल देती है. किसी एक कॉल के हेडर, सिर्फ़ उस कॉल पर लागू होते हैं.
उदाहरण के लिए, अगर किसी खास कॉल के लिए अनुमति वाला हेडर दिया जाता है, तो वह हेडर सिर्फ़ उस कॉल पर लागू होता है. अगर बाहरी अनुरोध के लिए अनुमति वाला हेडर दिया जाता है, तो वह हेडर, बैच में शामिल सभी कॉल पर लागू होता है. हालांकि, अगर किसी कॉल के लिए अनुमति वाला अलग हेडर दिया जाता है, तो वह हेडर, बाहरी अनुरोध के हेडर की वैल्यू को बदल देता है.
जब सर्वर को बैच में किया गया अनुरोध मिलता है, तो वह बाहरी अनुरोध के क्वेरी पैरामीटर और हेडर (ज़रूरत के हिसाब से) हर हिस्से पर लागू करता है. इसके बाद, हर हिस्से को एक अलग एचटीटीपी अनुरोध के तौर पर प्रोसेस करता है.
बैच में किए गए अनुरोध का जवाब
सर्वर का जवाब, 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)