Add-on Google Classroom kini tersedia secara umum untuk developer. Lihat dokumentasi add-on untuk informasi selengkapnya.

Halaman ini diterjemahkan oleh Cloud Translation API.

Permintaan Pengelompokan

Dokumen ini menunjukkan cara mengelompokkan panggilan API sekaligus untuk mengurangi jumlah koneksi HTTP yang harus dibuat oleh klien Anda.

Dokumen ini secara khusus membahas pembuatan permintaan batch dengan mengirim permintaan HTTP. Jika Anda menggunakan library klien Google untuk membuat permintaan batch, lihat dokumentasi library klien.

Ringkasan

Setiap koneksi HTTP yang dibuat klien Anda akan menghasilkan sejumlah overhead tertentu. Google Classroom API mendukung pengelompokan, sehingga klien Anda dapat menempatkan beberapa panggilan API ke dalam satu permintaan HTTP.

Contoh situasi saat Anda mungkin ingin menggunakan pengelompokan:

Mengambil daftar nama peserta untuk sejumlah besar kursus.
Membuat atau memperbarui kursus secara massal.
Menambahkan daftar nama peserta kursus dalam jumlah besar.
Mengambil daftar kursus untuk sejumlah besar pengguna.

Dalam setiap kasus, daripada mengirim setiap panggilan secara terpisah, Anda dapat mengelompokkannya ke dalam satu permintaan HTTP. Semua permintaan internal harus mengarah ke Google API yang sama.

Anda dibatasi hingga 50 panggilan dalam satu permintaan batch. Jika Anda harus melakukan lebih banyak panggilan dari jumlah tersebut, gunakan beberapa permintaan batch.

Catatan: Sistem batch untuk Google Classroom API menggunakan sintaksis yang sama dengan sistem pemrosesan batch OData, tetapi semantiknya berbeda.

Detail batch

Permintaan batch terdiri dari beberapa panggilan API yang digabungkan menjadi satu permintaan HTTP, yang dapat dikirim ke batchPath yang ditentukan dalam dokumen discovery API. Jalur default-nya adalah /batch/api_name/api_version. Bagian ini menjelaskan sintaksis batch secara mendetail; kemudian, akan muncul contoh.

Catatan: Kumpulan permintaan n yang dikelompokkan bersama-sama dihitung dalam batas penggunaan Anda sebagai permintaan n, bukan sebagai satu permintaan. Permintaan batch dibagi menjadi serangkaian permintaan sebelum diproses.

Format permintaan batch

Permintaan batch adalah satu permintaan HTTP standar yang berisi beberapa panggilan Google Classroom API, menggunakan jenis konten multipart/mixed. Dalam permintaan HTTP utama tersebut, masing-masing bagian berisi permintaan HTTP bertingkat.

Setiap bagian dimulai dengan header HTTP Content-Type: application/http-nya sendiri. Class ini juga dapat memiliki header Content-ID opsional. Namun, header bagian hanya ada untuk menandai awal bagian; terpisah dari permintaan bertingkat. Setelah server membuka permintaan batch menjadi permintaan terpisah, header bagian akan diabaikan.

Isi setiap bagian merupakan permintaan HTTP lengkap, dengan kata kerja, URL, header, dan isinya sendiri. Permintaan HTTP hanya boleh berisi bagian jalur URL; URL lengkap tidak diizinkan dalam permintaan batch.

Header HTTP untuk permintaan batch luar, kecuali untuk header Content- seperti Content-Type, berlaku ke setiap permintaan dalam batch. Jika Anda menentukan header HTTP tertentu dalam permintaan outer dan panggilan individual, nilai header panggilan individual akan menggantikan nilai header permintaan batch luar. Header untuk setiap satu panggilan hanya berlaku untuk panggilan tersebut.

Misalnya, jika Anda memberikan header Otorisasi untuk suatu panggilan, header tersebut hanya akan berlaku untuk panggilan tersebut. Jika Anda memberikan header Otorisasi untuk permintaan luar, header tersebut akan berlaku untuk semua panggilan individual kecuali jika header tersebut menggantinya dengan header Otorisasi sendiri.

Saat menerima permintaan batch, server menerapkan parameter kueri dan header permintaan outer (yang sesuai) ke setiap bagian, lalu memperlakukan setiap bagian seolah-olah merupakan permintaan HTTP terpisah.

Respons terhadap permintaan batch

Respons server adalah satu respons HTTP standar dengan jenis konten multipart/mixed; setiap bagian adalah respons terhadap salah satu permintaan dalam batch permintaan, dalam urutan yang sama dengan permintaan tersebut.

Seperti bagian dalam permintaan, setiap bagian respons berisi respons HTTP lengkap, termasuk kode status, header, dan isi. Dan seperti bagian dalam permintaan, setiap bagian respons didahului oleh header Content-Type yang menandai awal bagian.

Jika bagian tertentu dari permintaan memiliki header Content-ID, maka bagian respons yang sesuai memiliki header Content-ID yang cocok, dengan nilai asli yang diawali dengan string response-, seperti yang ditunjukkan dalam contoh berikut singkat ini.

Catatan: Server dapat melaksanakan panggilan Anda dengan urutan apa pun. Jangan menganggap eksekusinya dilakukan sesuai urutan yang Anda tentukan. Jika Anda ingin memastikan bahwa dua panggilan terjadi dalam urutan tertentu, Anda tidak dapat mengirimkannya dalam satu permintaan; sebagai gantinya, kirim pesan pertama saja, lalu tunggu respons terhadap pesan pertama sebelum mengirim yang kedua.

Contoh

Contoh berikut menunjukkan penggunaan pengelompokan dengan Google Classroom API.

Contoh permintaan batch

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

Contoh respons batch

Ini adalah respons terhadap contoh permintaan di bagian sebelumnya.

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

Menggunakan library klien

Contoh kode berikut menunjukkan cara membuat permintaan batch menggunakan library klien Google API. Lihat panduan memulai cepat masing-masing untuk mengetahui informasi selengkapnya tentang cara menginstal library dan menyiapkannya.

.NET

classroom/snippets/ClassroomSnippets/BatchAddStudents.cs

Lihat di 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

Lihat di 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

Lihat di 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)

Sebelumnya

Meningkatkan performa