بچینگ درخواست ها

این سند نشان می‌دهد که چگونه فراخوانی‌های API را دسته بندی کنید تا تعداد اتصالات HTTP که کلاینت شما باید برقرار کند را کاهش دهید.

این سند به طور خاص در مورد ایجاد درخواست دسته‌ای با ارسال درخواست HTTP است. اگر به جای آن، از یک کتابخانه کلاینت گوگل برای ایجاد درخواست دسته‌ای استفاده می‌کنید، به مستندات کتابخانه کلاینت مراجعه کنید.

نمای کلی

هر اتصال HTTP که کلاینت شما برقرار می‌کند، منجر به مقدار مشخصی سربار می‌شود. API کلاس درس گوگل از دسته‌بندی پشتیبانی می‌کند تا به کلاینت شما اجازه دهد چندین فراخوانی API را در یک درخواست HTTP واحد قرار دهد.

نمونه‌هایی از موقعیت‌هایی که ممکن است بخواهید از دسته‌بندی استفاده کنید:

  • بازیابی فهرست اسامی تعداد زیادی از دوره‌ها.
  • ایجاد یا به‌روزرسانی دوره‌ها به صورت انبوه.
  • اضافه شدن تعداد زیادی از فهرست‌های دوره‌های آموزشی.
  • بازیابی لیست دوره‌ها برای تعداد زیادی از کاربران.

در هر مورد، به جای ارسال جداگانه هر فراخوانی، می‌توانید آنها را در یک درخواست HTTP واحد گروه‌بندی کنید. همه درخواست‌های داخلی باید به یک API گوگل یکسان بروند.

شما در یک درخواست دسته‌ای محدود به ۵۰ تماس هستید. اگر مجبور به برقراری تماس‌های بیشتر از این هستید، از درخواست‌های دسته‌ای چندگانه استفاده کنید.

نکته : سیستم دسته‌ای برای API کلاس درس گوگل از همان سینتکس سیستم پردازش دسته‌ای OData استفاده می‌کند، اما معانی آن متفاوت است.

جزئیات دسته‌ای

یک درخواست دسته‌ای شامل چندین فراخوانی API است که در قالب یک درخواست HTTP ترکیب شده‌اند و می‌توانند به batchPath مشخص شده در سند کشف API ارسال شوند. مسیر پیش‌فرض /batch/ api_name / api_version است. این بخش سینتکس دسته‌ای را با جزئیات شرح می‌دهد؛ بعداً، یک مثال وجود دارد.

توجه : مجموعه‌ای از n درخواست که با هم دسته‌بندی شده‌اند، به عنوان n درخواست در محدودیت استفاده شما محاسبه می‌شوند، نه به عنوان یک درخواست. درخواست دسته‌ای قبل از پردازش به مجموعه‌ای از درخواست‌ها تقسیم می‌شود.

قالب درخواست دسته‌ای

یک درخواست دسته‌ای، یک درخواست HTTP استاندارد واحد است که شامل چندین فراخوانی API کلاس درس گوگل است و از نوع محتوای multipart/mixed استفاده می‌کند. در داخل آن درخواست HTTP اصلی، هر یک از بخش‌ها شامل یک درخواست HTTP تو در تو هستند.

هر بخش با هدر Content-Type: application/http HTTP مخصوص به خود شروع می‌شود. همچنین می‌تواند یک هدر Content-ID اختیاری داشته باشد. با این حال، هدرهای بخش فقط برای مشخص کردن شروع بخش وجود دارند؛ آنها از درخواست تو در تو جدا هستند. پس از اینکه سرور درخواست دسته‌ای را به درخواست‌های جداگانه تجزیه می‌کند، هدرهای بخش نادیده گرفته می‌شوند.

بدنه هر بخش، یک درخواست HTTP کامل است که فعل، URL، هدرها و بدنه مخصوص به خود را دارد. درخواست HTTP فقط باید شامل بخش مسیر URL باشد؛ URL های کامل در درخواست های دسته ای مجاز نیستند.

هدرهای HTTP برای درخواست دسته‌ای بیرونی، به جز هدرهای Content- مانند Content-Type ، برای هر درخواست در دسته اعمال می‌شوند. اگر یک هدر HTTP مشخص را هم در درخواست بیرونی و هم در یک فراخوانی جداگانه مشخص کنید، مقدار هدر فراخوانی جداگانه، مقدار هدر درخواست دسته‌ای بیرونی را لغو می‌کند. هدرهای یک فراخوانی جداگانه فقط برای آن فراخوانی اعمال می‌شوند.

برای مثال، اگر برای یک فراخوانی خاص، یک هدر مجوز (Authorization header) ارائه دهید، آن هدر فقط برای همان فراخوانی اعمال می‌شود. اگر برای درخواست بیرونی، یک هدر مجوز (Authorization header) ارائه دهید، آن هدر برای تمام فراخوانی‌های منفرد اعمال می‌شود، مگر اینکه آنها با هدرهای مجوز (Authorization header) خودشان، آن را لغو کنند.

وقتی سرور درخواست دسته‌ای را دریافت می‌کند، پارامترها و هدرهای درخواست بیرونی (به تناسب) را برای هر بخش اعمال می‌کند و سپس با هر بخش مانند یک درخواست HTTP جداگانه رفتار می‌کند.

پاسخ به درخواست دسته‌ای

پاسخ سرور، یک پاسخ استاندارد HTTP با نوع محتوای multipart/mixed است؛ هر بخش، پاسخ به یکی از درخواست‌های موجود در درخواست دسته‌ای، به همان ترتیب درخواست‌ها، می‌باشد.

مانند بخش‌های درخواست، هر بخش پاسخ شامل یک پاسخ کامل HTTP، شامل کد وضعیت، هدرها و بدنه است. و مانند بخش‌های درخواست، قبل از هر بخش پاسخ، یک هدر Content-Type قرار دارد که ابتدای بخش را مشخص می‌کند.

اگر بخش مشخصی از درخواست دارای سرآیند Content-ID باشد، بخش متناظر پاسخ نیز دارای سرآیند Content-ID منطبق با آن است که مقدار اصلی آن قبل از رشته response- قرار می‌گیرد، همانطور که در مثال زیر نشان داده شده است.

توجه : سرور ممکن است فراخوانی‌های شما را به هر ترتیبی انجام دهد. روی اجرای آنها به ترتیبی که شما مشخص کرده‌اید حساب نکنید. اگر می‌خواهید مطمئن شوید که دو فراخوانی به ترتیب مشخصی انجام می‌شوند، نمی‌توانید آنها را در یک درخواست واحد ارسال کنید. در عوض، اولی را به تنهایی ارسال کنید، سپس قبل از ارسال دومی منتظر پاسخ اولی باشید.

مثال

مثال زیر استفاده از دسته‌بندی با رابط برنامه‌نویسی کاربردی Google Classroom را نشان می‌دهد.

مثال درخواست دسته‌ای

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 را نشان می‌دهند. برای اطلاعات بیشتر در مورد نحوه‌ی نصب و راه‌اندازی کتابخانه‌ها، به راهنماهای شروع سریع مربوطه مراجعه کنید.

دات نت

class/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;
                }
            }
        }
    }
}

جاوا

کلاس/قطعه قطعه/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();
  }
}

پی اچ پی

کلاس/قطعه قطعه کد/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)