طلبات مجمّعة

يوضّح هذا المستند كيفية تجميع طلبات البيانات من واجهة برمجة التطبيقات معًا لتقليل عدد اتصالات HTTP التي يجب أن يجريها العميل.

يتناول هذا المستند تحديدًا كيفية إرسال طلب مجمّع من خلال إرسال طلب HTTP. إذا كنت تستخدم مكتبة عميل من Google لإجراء طلب مجمّع، يمكنك الاطّلاع على مستندات مكتبة العميل.

نظرة عامة

يؤدي كل اتصال HTTP يجريه العميل إلى حدوث قدر معيّن من الحمل الزائد. تتيح Google Classroom API إمكانية تجميع الطلبات، ما يسمح للعميل بوضع عدة طلبات API في طلب HTTP واحد.

أمثلة على الحالات التي قد تحتاج فيها إلى استخدام التجميع:

• استرداد قوائم الطلاب لعدد كبير من الدورات التدريبية
• إنشاء دورات تدريبية أو تعديلها بشكل مجمّع
• إضافة عدد كبير من قوائم الطلاب في الدورات التدريبية
• استرداد قوائم الدورات التدريبية لعدد كبير من المستخدمين

في كل حالة، بدلاً من إرسال كل طلب على حدة، يمكنك تجميعها معًا في طلب HTTP واحد. يجب أن يتم توجيه جميع الطلبات الداخلية إلى واجهة Google API نفسها.

يقتصر الحد الأقصى لعدد المكالمات على 50 مكالمة في طلب دُفعة واحد. إذا كان عليك إجراء عدد أكبر من المكالمات، استخدِم طلبات مجمّعة متعددة.

ملاحظة: يستخدم نظام الدفعات لواجهة Google Classroom API البنية نفسها المستخدَمة في نظام معالجة الدفعات في OData، ولكن تختلف الدلالات.

تفاصيل الدفعة

يتألف طلب الدُفعة من عدة طلبات للحصول على البيانات من واجهة برمجة التطبيقات مدمجة في طلب HTTP واحد، ويمكن إرسالها إلى batchPath المحدّد في مستند التعرّف على واجهة برمجة التطبيقات. المسار التلقائي هو /batch/api_name/api_version. يوضّح هذا القسم بنية الدُفعات بالتفصيل، وسنقدّم مثالاً لاحقًا.

ملاحظة: يتم احتساب مجموعة طلبات n المجمّعة معًا ضمن الحدّ الأقصى للاستخدام على أنّها n طلبات، وليس طلبًا واحدًا. يتم تقسيم الطلب المجمّع إلى مجموعة من الطلبات قبل معالجته.

تنسيق الطلب المجمّع

طلب مجمَّع هو طلب HTTP عادي واحد يحتوي على طلبات متعددة من Google Classroom API، باستخدام نوع المحتوى multipart/mixed. ضمن طلب HTTP الرئيسي هذا، يحتوي كل جزء على طلب HTTP متداخل.

يبدأ كل جزء Content-Type: application/http ببروتوكول HTTP الخاص به. يمكن أن يحتوي أيضًا على Content-ID عنوان اختياري. ومع ذلك، فإنّ عناوين الأجزاء موجودة فقط لتحديد بداية الجزء، وهي منفصلة عن الطلب المتداخل. بعد أن يفك الخادم حزمة الطلبات إلى طلبات منفصلة، يتم تجاهل عناوين الأجزاء.

يمثّل نص كل جزء طلب HTTP كاملاً، مع ما يخصه من فعل وعنوان URL ورؤوس ونص. يجب أن يحتوي طلب HTTP على جزء المسار فقط من عنوان URL، ولا يُسمح باستخدام عناوين URL كاملة في الطلبات المجمّعة.

تنطبق عناوين HTTP لطلب الدفعة الخارجي، باستثناء عناوين Content- مثل Content-Type، على كل طلب في الدفعة. إذا حدّدت عنوان HTTP معيّنًا في كلّ من الطلب الخارجي والطلب الفردي، ستتجاوز قيمة عنوان الطلب الفردي قيمة عنوان طلب الدفعة الخارجي. تنطبق العناوين الخاصة بمكالمة فردية على تلك المكالمة فقط.

على سبيل المثال، إذا قدّمت عنوان Authorization لطلب معيّن، سيتم تطبيق هذا العنوان على هذا الطلب فقط. إذا قدّمت عنوان Authorization للطلب الخارجي، سينطبق هذا العنوان على جميع المكالمات الفردية ما لم يتم تجاوزه بعناوين Authorization خاصة بها.

عندما يتلقّى الخادم الطلب المجمّع، يطبّق مَعلمات طلب البحث والرؤوس الخاصة بالطلب الخارجي (حسب الاقتضاء) على كل جزء، ثم يعامل كل جزء كما لو كان طلب HTTP منفصلاً.

الردّ على طلب مجمّع

استجابة الخادم هي استجابة HTTP عادية واحدة بنوع محتوى multipart/mixed، وكل جزء هو استجابة لأحد الطلبات في الطلب المجمّع، وبالترتيب نفسه الذي تم به إرسال الطلبات.

وكما هو الحال مع الأجزاء في الطلب، يحتوي كل جزء من الاستجابة على استجابة HTTP كاملة، بما في ذلك رمز الحالة والعناوين والنص. وكما هو الحال مع الأجزاء في الطلب، يسبق كل جزء من الردّ عنوان 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:[e-mail]>

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:[e-mail]>

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:[e-mail]>

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:[e-mail]>

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.

classroom/snippets/ClassroomSnippets/BatchAddStudents.cs

عرض على GitHub

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

Java

classroom/snippets/src/main/java/BatchAddStudents.java

عرض على GitHub

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();
  }
}

PHP

classroom/snippets/src/ClassroomBatchAddStudents.php

عرض على GitHub

<?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;
}

Python

course_id = '123456'
student_emails = ['[e-mail]', '[e-mail]']
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)