คำขอแบบกลุ่ม

เอกสารนี้แสดงวิธีจัดกลุ่มการเรียก API เข้าด้วยกันเพื่อลดจำนวนการเชื่อมต่อ HTTP ที่ไคลเอ็นต์ต้องสร้าง

เอกสารนี้เกี่ยวกับการสร้างคำขอแบบกลุ่มโดยการส่งคำขอ HTTP แต่ถ้าคุณใช้ไลบรารีของไคลเอ็นต์ Google เพื่อส่งคำขอแบบกลุ่มแทน โปรดดูเอกสารประกอบของไลบรารีไคลเอ็นต์

ภาพรวม

การเชื่อมต่อ HTTP แต่ละครั้งที่ไคลเอ็นต์ทำให้เกิดโอเวอร์เฮดจำนวนหนึ่ง Google Classroom API รองรับการทำงานแบบกลุ่ม เพื่อให้ไคลเอ็นต์รวมการเรียก API หลายรายการไว้ในคําขอ HTTP รายการเดียว

ตัวอย่างสถานการณ์ที่คุณอาจต้องใช้การทำงานแบบกลุ่มมีดังนี้

การเรียกข้อมูลบัญชีรายชื่อสำหรับหลักสูตรจำนวนมาก
การสร้างหรืออัปเดตหลักสูตรจำนวนมาก
การเพิ่มบัญชีรายชื่อของหลักสูตรจำนวนมาก
กำลังเรียกข้อมูลรายการหลักสูตรสำหรับผู้ใช้จำนวนมาก

ในแต่ละกรณี คุณจะจัดกลุ่มการโทรเข้าด้วยกันเป็นคำขอ HTTP รายการเดียวได้ แทนที่จะส่งแต่ละสายแยกกัน คำขอภายในทั้งหมดต้องไปยัง Google API เดียวกัน

คุณสามารถเรียกใช้การโทรได้ 50 ครั้งสำหรับคำขอแบบกลุ่มเดียว หากต้องการทำการเรียกมากกว่านั้น ให้ใช้คำขอแบบกลุ่มหลายรายการ

หมายเหตุ: ระบบแบบกลุ่มสำหรับ Google Classroom API จะใช้ไวยากรณ์เดียวกันกับระบบการประมวลผลแบบกลุ่มของข้อมูล OData แต่อรรถศาสตร์จะแตกต่างกัน

รายละเอียดกลุ่ม

คำขอแบบกลุ่มประกอบด้วยการเรียก API หลายรายการรวมกันเป็นคำขอ HTTP รายการเดียว ซึ่งจะส่งไปยัง batchPath ที่ระบุในเอกสารการค้นพบ API ได้ เส้นทางเริ่มต้นคือ /batch/api_name/api_version ส่วนนี้อธิบายไวยากรณ์แบบกลุ่มโดยละเอียด ต่อไปมีตัวอย่าง

หมายเหตุ: คำขอ n ชุดหนึ่งที่จัดกลุ่มไว้ด้วยกันจะนับรวมในขีดจำกัดการใช้งานของคุณเป็นคำขอ n รายการ ไม่ใช่คำขอเดียว ระบบจะแยกคำขอแบบกลุ่มเป็นชุดคำขอก่อนประมวลผล

รูปแบบคำขอแบบกลุ่ม

คำขอแบบกลุ่มคือคำขอ HTTP มาตรฐานรายการเดียวที่มีการเรียก API ของ Google Classroom หลายรายการโดยใช้เนื้อหาประเภท 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- ดังที่แสดงในตัวอย่างต่อไปนี้

หมายเหตุ: เซิร์ฟเวอร์อาจดำเนินการโทรตามลำดับใดก็ได้ อย่ายึดติดกับการดำเนินการตามลำดับที่คุณระบุ หากคุณต้องการแน่ใจว่าการเรียก 2 ครั้งเกิดขึ้นในลำดับที่ระบุ คุณจะไม่สามารถส่งการเรียกในคำขอเดียวได้ แต่ให้ส่งการเรียกแรกด้วยตัวเอง จากนั้นรอการตอบกลับไปยังการเรียกแรกก่อนที่จะส่งการเรียกครั้งที่ 2

ตัวอย่าง

ตัวอย่างต่อไปนี้แสดงการใช้การจัดกลุ่มกับ 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/ClassroomSnippets/BatchAddstudent.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/BatchAddstudent.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

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)