طلبات مجمّعة

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

يتعلق هذا المستند تحديدًا بتقديم طلب مُجمَّع عن طريق إرسال طلب HTTP. بدلاً من ذلك، إذا كنت تستخدم مكتبة برامج Google لإجراء طلب مُجمَّع، راجِع مستندات مكتبة البرامج.

نظرة عامة

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

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

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

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

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

ملاحظة: يستخدم النظام المجمّع لواجهة برمجة تطبيقات Google Classroom البنية نفسها التي يستخدمها نظام المعالجة المجمّعة لبيانات OData، ولكن تختلف المعنى.

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

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

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

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

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

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

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

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

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

عندما يتلقى الخادم الطلب المجمّع، فإنه يطبّق معلمات الاستعلام ورؤوس الطلب الخارجي (حسب الاقتضاء) على كل جزء، ثم يتعامل مع كل جزء كما لو كان طلب 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: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.

Classroom/snippets/Classroomمقتطفs/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();
  }
}

‫2,999

Classroom/snippets/src/ClassroomBatchAddStudents.php

العرض على GitHub

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 = ['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)