Dokumen ini menunjukkan cara mengelompokkan panggilan API untuk mengurangi jumlah koneksi HTTP yang harus dibuat oleh klien Anda.
Dokumen ini secara khusus membahas tentang membuat 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 oleh klien Anda 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 siswa untuk sejumlah besar kursus.
- Membuat atau memperbarui kursus secara massal.
- Menambahkan sejumlah besar daftar nama siswa kursus.
- Mengambil daftar kursus untuk pengguna dalam jumlah besar.
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 perlu melakukan lebih banyak panggilan dari itu, gunakan beberapa permintaan batch.
Catatan: Sistem batch untuk Google Classroom API menggunakan sintaksis yang sama dengan sistem batch processing OData, tetapi semantiknya berbeda.
Detail paket
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; selanjutnya, lihat contohnya.
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, yang 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 di sana untuk menandai awal bagian; header bagian terpisah dari permintaan bertingkat. Setelah server membuka permintaan batch menjadi permintaan terpisah, header bagian akan diabaikan.
Isi setiap bagian itu sendiri 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
, diterapkan 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 panggilan hanya berlaku untuk panggilan tersebut.
Misalnya, jika Anda memberikan header Otorisasi untuk panggilan tertentu, 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 (sebagaimana yang sesuai) ke setiap bagian, lalu memperlakukan setiap bagian seolah-olah merupakan permintaan HTTP terpisah.
Respons terhadap permintaan batch
Respons server adalah respons HTTP standar tunggal dengan jenis konten multipart/mixed
; setiap bagian adalah respons terhadap salah satu permintaan dalam permintaan batch, dalam urutan yang sama dengan permintaan.
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
, bagian respons yang sesuai memiliki header Content-ID
yang cocok, dengan nilai asli yang diawali dengan string response-
, seperti yang ditunjukkan dalam contoh berikut.
Catatan: Server dapat melakukan panggilan Anda dalam urutan apa pun. Jangan mengandalkan eksekusi yang Anda tentukan. Jika Anda ingin memastikan bahwa dua panggilan terjadi dalam urutan tertentu, Anda tidak dapat mengirimnya dalam satu permintaan; sebagai gantinya, kirim panggilan pertama secara mandiri, lalu tunggu respons untuk panggilan 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 terkait untuk mengetahui informasi selengkapnya tentang cara menginstal library dan menyiapkannya.
.NET
Java
PHP
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)