ব্যাচিং অনুরোধ

এই ডকুমেন্টটিতে দেখানো হয়েছে কীভাবে একসাথে একাধিক এপিআই কল ব্যাচ করা যায়, যার ফলে আপনার ক্লায়েন্টকে কম সংখ্যক HTTP কানেকশন করতে হয়।

এই ডকুমেন্টটি বিশেষভাবে HTTP রিকোয়েস্ট পাঠিয়ে ব্যাচ রিকোয়েস্ট করার বিষয়ে। এর পরিবর্তে, আপনি যদি ব্যাচ রিকোয়েস্ট করার জন্য কোনো গুগল ক্লায়েন্ট লাইব্রেরি ব্যবহার করেন, তাহলে সেই ক্লায়েন্ট লাইব্রেরির ডকুমেন্টেশন দেখুন।

সংক্ষিপ্ত বিবরণ

আপনার ক্লায়েন্টের প্রতিটি HTTP সংযোগের ফলে একটি নির্দিষ্ট পরিমাণ ওভারহেড তৈরি হয়। গুগল ক্লাসরুম এপিআই ব্যাচিং সমর্থন করে, যা আপনার ক্লায়েন্টকে একটি একক HTTP অনুরোধে একাধিক এপিআই কল অন্তর্ভুক্ত করার সুযোগ দেয়।

যেসব পরিস্থিতিতে আপনি ব্যাচিং ব্যবহার করতে চাইতে পারেন তার কিছু উদাহরণ:

  • বিপুল সংখ্যক কোর্সের তালিকা সংগ্রহ করা হচ্ছে।
  • একসাথে অনেকগুলো কোর্স তৈরি বা আপডেট করা।
  • বিপুল সংখ্যক কোর্সের তালিকা যুক্ত করা হচ্ছে।
  • বহু সংখ্যক ব্যবহারকারীর কোর্স তালিকা পুনরুদ্ধার করা হচ্ছে।

প্রতিটি ক্ষেত্রে, প্রতিটি কল আলাদাভাবে পাঠানোর পরিবর্তে, আপনি সেগুলোকে একত্রিত করে একটি একক HTTP অনুরোধ পাঠাতে পারেন। ভেতরের সমস্ত অনুরোধ অবশ্যই একই গুগল এপিআই-তে পাঠাতে হবে।

একটি একক ব্যাচ অনুরোধে আপনি সর্বোচ্চ ৫০টি কল করতে পারবেন। যদি এর চেয়ে বেশি কল করার প্রয়োজন হয়, তবে একাধিক ব্যাচ অনুরোধ ব্যবহার করুন।

দ্রষ্টব্য : গুগল ক্লাসরুম এপিআই-এর ব্যাচ সিস্টেমটি OData ব্যাচ প্রসেসিং সিস্টেমের মতোই সিনট্যাক্স ব্যবহার করে, কিন্তু এর অর্থগত তাৎপর্য ভিন্ন।

ব্যাচের বিবরণ

একটি ব্যাচ রিকোয়েস্ট হলো একাধিক এপিআই কলকে একত্রিত করে একটিমাত্র HTTP রিকোয়েস্ট, যা এপিআই ডিসকভারি ডকুমেন্টে নির্দিষ্ট করা batchPath এ পাঠানো যায়। ডিফল্ট পাথ হলো /batch/ api_name / api_version । এই অংশে ব্যাচ সিনট্যাক্স বিস্তারিতভাবে বর্ণনা করা হয়েছে; পরে একটি উদাহরণ রয়েছে।

দ্রষ্টব্য : একসাথে ব্যাচ করা n সংখ্যক অনুরোধ আপনার ব্যবহারের সীমার মধ্যে n অনুরোধ হিসাবে গণনা করা হয়, একটি অনুরোধ হিসাবে নয়। প্রক্রিয়াকরণের আগে ব্যাচ অনুরোধটি একাধিক অনুরোধে বিভক্ত করা হয়।

ব্যাচ অনুরোধের ফরম্যাট

ব্যাচ রিকোয়েস্ট হলো একটি একক স্ট্যান্ডার্ড HTTP রিকোয়েস্ট, যাতে multipart/mixed কন্টেন্ট টাইপ ব্যবহার করে একাধিক গুগল ক্লাসরুম এপিআই কল থাকে। সেই মূল HTTP রিকোয়েস্টের প্রতিটি অংশের মধ্যে একটি নেস্টেড HTTP রিকোয়েস্ট থাকে।

প্রতিটি পার্ট তার নিজস্ব Content-Type: application/http HTTP হেডার দিয়ে শুরু হয়। এতে একটি ঐচ্ছিক Content-ID হেডারও থাকতে পারে। তবে, পার্ট হেডারগুলো শুধুমাত্র পার্টটির শুরু চিহ্নিত করার জন্য থাকে; এগুলো নেস্টেড রিকোয়েস্ট থেকে আলাদা। সার্ভার যখন ব্যাচ রিকোয়েস্টটিকে আলাদা আলাদা রিকোয়েস্টে বিভক্ত করে ফেলে, তখন পার্ট হেডারগুলো উপেক্ষা করা হয়।

প্রতিটি অংশের বডি হলো একটি সম্পূর্ণ HTTP রিকোয়েস্ট, যার নিজস্ব ভার্ব, ইউআরএল, হেডার এবং বডি থাকে। HTTP রিকোয়েস্টটিতে অবশ্যই ইউআরএল-এর শুধুমাত্র পাথ অংশটি থাকতে হবে; ব্যাচ রিকোয়েস্টে সম্পূর্ণ ইউআরএল অনুমোদিত নয়।

বাইরের ব্যাচ রিকোয়েস্টের HTTP হেডারগুলো, Content-Type মতো Content- হেডারগুলো ছাড়া, ব্যাচের প্রতিটি রিকোয়েস্টের জন্য প্রযোজ্য হয়। যদি আপনি বাইরের রিকোয়েস্ট এবং একটি স্বতন্ত্র কল উভয় ক্ষেত্রেই একটি নির্দিষ্ট HTTP হেডার উল্লেখ করেন, তাহলে স্বতন্ত্র কলের হেডারের মান বাইরের ব্যাচ রিকোয়েস্টের হেডারের মানকে ওভাররাইড করবে। একটি স্বতন্ত্র কলের হেডারগুলো শুধুমাত্র সেই কলের জন্যই প্রযোজ্য হয়।

উদাহরণস্বরূপ, যদি আপনি কোনো নির্দিষ্ট কলের জন্য একটি Authorization হেডার প্রদান করেন, তাহলে সেই হেডারটি শুধুমাত্র সেই কলের ক্ষেত্রেই প্রযোজ্য হবে। যদি আপনি বাইরের অনুরোধের জন্য একটি Authorization হেডার প্রদান করেন, তাহলে সেই হেডারটি সমস্ত স্বতন্ত্র কলের ক্ষেত্রেই প্রযোজ্য হবে, যদি না তারা তাদের নিজস্ব Authorization হেডার দিয়ে সেটিকে ওভাররাইড করে।

সার্ভার যখন ব্যাচ করা অনুরোধটি গ্রহণ করে, তখন এটি বাইরের অনুরোধের কোয়েরি প্যারামিটার এবং হেডারগুলো (প্রয়োজন অনুযায়ী) প্রতিটি অংশে প্রয়োগ করে এবং তারপর প্রতিটি অংশকে একটি পৃথক HTTP অনুরোধ হিসেবে বিবেচনা করে।

ব্যাচ অনুরোধের প্রতিক্রিয়া

সার্ভারের প্রতিক্রিয়াটি হলো multipart/mixed কন্টেন্ট টাইপের একটি একক স্ট্যান্ডার্ড HTTP প্রতিক্রিয়া; এর প্রতিটি অংশ হলো ব্যাচ করা অনুরোধগুলোর যেকোনো একটির প্রতিক্রিয়া, যা অনুরোধগুলোর ক্রমানুসারেই সাজানো থাকে।

রিকোয়েস্টের অংশগুলোর মতোই, প্রতিটি রেসপন্স পার্টে একটি সম্পূর্ণ HTTP রেসপন্স থাকে, যার মধ্যে স্ট্যাটাস কোড, হেডার এবং বডি অন্তর্ভুক্ত। এবং রিকোয়েস্টের অংশগুলোর মতোই, প্রতিটি রেসপন্স পার্টের আগে একটি Content-Type হেডার থাকে যা পার্টটির শুরু নির্দেশ করে।

যদি অনুরোধের কোনো নির্দিষ্ট অংশে একটি Content-ID হেডার থাকে, তাহলে প্রতিক্রিয়ার সংশ্লিষ্ট অংশেও একটি অনুরূপ Content-ID হেডার থাকে, যার মূল মানের আগে response- স্ট্রিংটি যুক্ত থাকে, যেমনটি নিম্নলিখিত উদাহরণে দেখানো হয়েছে।

দ্রষ্টব্য : সার্ভার আপনার কলগুলো যেকোনো ক্রমে সম্পাদন করতে পারে। আপনি যে ক্রমে কলগুলো নির্দিষ্ট করেছেন, সেই ক্রমেই যে সেগুলো সম্পাদিত হবে, তার উপর নির্ভর করবেন না। যদি আপনি নিশ্চিত করতে চান যে দুটি কল একটি নির্দিষ্ট ক্রমে সম্পন্ন হবে, তবে আপনি সেগুলোকে একটিমাত্র অনুরোধে পাঠাতে পারবেন না; এর পরিবর্তে, প্রথমে শুধু প্রথমটি পাঠান, এবং দ্বিতীয়টি পাঠানোর আগে সেটির প্রতিক্রিয়ার জন্য অপেক্ষা করুন।

উদাহরণ

নিম্নলিখিত উদাহরণটিতে গুগল ক্লাসরুম এপিআই-এর সাথে ব্যাচিং-এর ব্যবহার দেখানো হয়েছে।

ব্যাচ অনুরোধের উদাহরণ

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--

ক্লায়েন্ট লাইব্রেরি ব্যবহার করে

নিম্নলিখিত কোড নমুনাগুলি দেখায় কিভাবে গুগল এপিআই ক্লায়েন্ট লাইব্রেরি ব্যবহার করে ব্যাচ রিকোয়েস্ট করতে হয়। লাইব্রেরিগুলি কীভাবে ইনস্টল এবং সেট আপ করতে হয় সে সম্পর্কে আরও তথ্যের জন্য সংশ্লিষ্ট কুইকস্টার্ট গাইডগুলি দেখুন।

.NET

classroom/snippets/ClassroomSnippets/BatchAddStudents.cs
using Google;
using Google.Apis.Auth.OAuth2;
using Google.Apis.Classroom.v1;
using Google.Apis.Classroom.v1.Data;
using Google.Apis.Requests;
using Google.Apis.Services;
using System;
using System.Collections.Generic;
using System.Threading.Tasks;

namespace ClassroomSnippets
{
    // Class to demonstrate the use of Classroom Batch Add Students API
    public class BatchAddStudents
    {
        /// <summary>
        /// Add multiple students in a specified course.
        /// </summary>
        /// <param name="courseId">Id of the course to add students.</param>
        /// <param name="studentEmails">Email address of the students.</param>
        public static void ClassroomBatchAddStudents(string courseId,
            List<string> studentEmails)
        {
            try
            {
                /* Load pre-authorized user credentials from the environment.
                 TODO(developer) - See https://developers.google.com/identity for 
                 guides on implementing OAuth2 for your application. */
                GoogleCredential credential = GoogleCredential.GetApplicationDefault()
                    .CreateScoped(ClassroomService.Scope.ClassroomRosters);

                // Create Classroom API service.
                var service = new ClassroomService(new BaseClientService.Initializer
                {
                    HttpClientInitializer = credential,
                    ApplicationName = "Classroom Snippets"
                });

                var batch = new BatchRequest(service, "https://classroom.googleapis.com/batch");
                BatchRequest.OnResponse<Student> callback = (student, error, i, message) =>
                {
                    if (error != null)
                    {
                        Console.WriteLine("Error adding student to the course: {0}", error.Message);
                    }
                    else
                    {
                        Console.WriteLine("User '{0}' was added as a student to the course.",
                            student.Profile.Name.FullName);
                    }
                };
                foreach (var studentEmail in studentEmails)
                {
                    var student = new Student() {UserId = studentEmail};
                    var request = service.Courses.Students.Create(student, courseId);
                    batch.Queue<Student>(request, callback);
                }

                Task.WaitAll(batch.ExecuteAsync());
            }
            catch (Exception e)
            {
                // TODO(developer) - handle error appropriately
                if (e is AggregateException)
                {
                    Console.WriteLine("Credential Not found");
                }
                else if (e is GoogleApiException)
                {
                    Console.WriteLine("Course does not exist.");
                }
                else
                {
                    throw;
                }
            }
        }
    }
}

জাভা

classroom/snippets/src/main/java/BatchAddStudents.java
import com.google.api.client.googleapis.batch.BatchRequest;
import com.google.api.client.googleapis.batch.json.JsonBatchCallback;
import com.google.api.client.googleapis.javanet.GoogleNetHttpTransport;
import com.google.api.client.googleapis.json.GoogleJsonError;
import com.google.api.client.http.HttpHeaders;
import com.google.api.client.http.javanet.NetHttpTransport;
import com.google.api.client.json.gson.GsonFactory;
import com.google.api.services.classroom.Classroom;
import com.google.api.services.classroom.ClassroomScopes;
import com.google.api.services.classroom.model.Student;
import java.io.IOException;
import java.security.GeneralSecurityException;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.List;

/* Class to demonstrate the use of Classroom Batch Add Students API */
public class BatchAddStudents {

  /* Scopes required by this API call. If modifying these scopes, delete your previously saved
  tokens/ folder. */
  static ArrayList<String> SCOPES =
      new ArrayList<>(Arrays.asList(ClassroomScopes.CLASSROOM_ROSTERS));

  /**
   * Add multiple students in a specified course.
   *
   * @param courseId - Id of the course to add students.
   * @param studentEmails - Email address of the students.
   * @throws IOException - if credentials file not found.
   * @throws GeneralSecurityException - if a new instance of NetHttpTransport was not created.
   */
  public static void batchAddStudents(String courseId, List<String> studentEmails)
      throws GeneralSecurityException, IOException {

    // Create the classroom API client.
    final NetHttpTransport HTTP_TRANSPORT = GoogleNetHttpTransport.newTrustedTransport();
    Classroom service =
        new Classroom.Builder(
                HTTP_TRANSPORT,
                GsonFactory.getDefaultInstance(),
                ClassroomCredentials.getCredentials(HTTP_TRANSPORT, SCOPES))
            .setApplicationName("Classroom samples")
            .build();

    BatchRequest batch = service.batch();
    JsonBatchCallback<Student> callback =
        new JsonBatchCallback<>() {
          public void onSuccess(Student student, HttpHeaders responseHeaders) {
            System.out.printf(
                "User '%s' was added as a student to the course.\n",
                student.getProfile().getName().getFullName());
          }

          public void onFailure(GoogleJsonError error, HttpHeaders responseHeaders) {
            System.out.printf("Error adding student to the course: %s\n", error.getMessage());
          }
        };
    for (String studentEmail : studentEmails) {
      Student student = new Student().setUserId(studentEmail);
      service.courses().students().create(courseId, student).queue(batch, callback);
    }
    batch.execute();
  }
}

পিএইচপি

classroom/snippets/src/ClassroomBatchAddStudents.php
<?php
use Google\Client;
use Google\Service\Classroom;
use Google\Service\Classroom\Student;
use Google\Service\Exception;

function batchAddStudents($courseId, $studentEmails)
{
    /* Load pre-authorized user credentials from the environment.
    TODO(developer) - See https://developers.google.com/identity for
     guides on implementing OAuth2 for your application. */
    $client = new Client();
    $client->useApplicationDefaultCredentials();
    $client->addScope("https://www.googleapis.com/auth/classroom.profile.emails");
    $service = new Classroom($client);
    $service->getClient()->setUseBatch(true);
    //create batch
    $batch = $service->createBatch();
    foreach ($studentEmails as $studentEmail) {
        $student = new Student([
            'userId' => $studentEmail
        ]);
        $request = $service->courses_students->create($courseId, $student);
        $requestId = $studentEmail;
        $batch->add($request, $requestId);
    }
    //executing request
    $results = $batch->execute();
    foreach ($results as $responseId => $student) {
        $studentEmail = substr($responseId, strlen('response-') + 1);
        if ($student instanceof Exception) {
            $e = $student;
            printf("Error adding user '%s' to the course: %s\n", $studentEmail,
                $e->getMessage());
        } else {
            printf("User '%s' was added as a student to the course.\n",
                $student->profile->name->fullName, $courseId);
        }
    }
    $service->getClient()->setUseBatch(false);
    return $results;
}

পাইথন

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)