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

เอกสารนี้แสดงวิธีจัดกลุ่มการเรียก 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 มาตรฐานเดียวที่มีการเรียก 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- นำหน้าค่าเดิม ดังที่แสดงในตัวอย่างต่อไปนี้

หมายเหตุ: เซิร์ฟเวอร์อาจดำเนินการเรียกใช้ตามลำดับใดก็ได้ อย่าคาดหวังว่าระบบจะดำเนินการตามลำดับที่คุณระบุ หากต้องการให้การเรียกใช้ 2 รายการเกิดขึ้นตามลำดับที่กำหนด คุณจะส่งการเรียกใช้ทั้ง 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:[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)