Halaman ini menjelaskan cara mengakses fitur pratinjau Classroom API dan menentukan versi pratinjau.
Dua pertimbangan saat menggunakan fitur pratinjau jika dibandingkan dengan API v1 stabil adalah:
- Fitur API dalam program akses awal atau pratinjau tidak diekspos dalam library klien standar dan mungkin tidak dapat diakses secara default melalui HTTP.
- Pratinjau dapat memiliki beberapa status atau versi API pada waktu tertentu.
Mengaktifkan fitur pratinjau di library klien
Opsi umum untuk menggunakan Classroom API adalah dengan library klien. Ada tiga jenis library klien:
- Library klien yang dibuat secara dinamis
- Library klien statis yang disediakan Google
- Library klien kustom Anda sendiri
Penggunaan library statis yang dibuat secara dinamis atau yang disediakan Google adalah cara yang direkomendasikan untuk menggunakan API. Lihat membangun library klien jika Anda perlu membangun library Anda sendiri. Pembuatan library Anda sendiri berada di luar cakupan panduan ini, tetapi Anda harus meninjau bagian library dinamis untuk mempelajari label pratinjau dan perannya dalam Discovery.
Library dinamis
Library dalam bahasa seperti Python menghasilkan library klien saat runtime menggunakan Dokumen Discovery dari layanan Discovery.
Dokumen Discovery adalah spesifikasi yang dapat dibaca mesin untuk mendeskripsikan dan menggunakan REST API. Alat ini digunakan untuk membuat library klien, plugin IDE, dan alat lain yang berinteraksi dengan Google API. Satu layanan mungkin menyediakan beberapa dokumen penemuan.
Dokumen Penemuan untuk layanan Classroom API (classroom.googleapis.com
)
dapat ditemukan di endpoint berikut:
https://classroom.googleapis.com/$discovery/rest?labels=PREVIEW_LABEL&version=v1&key=API_KEY
Perbedaan penting untuk menggunakan API pratinjau adalah menentukan
label
yang sesuai. Untuk pratinjau publik Classroom, labelnya adalah
DEVELOPER_PREVIEW
.
Untuk membuat library Python dan membuat instance layanan Classroom dengan metode pratinjau, Anda dapat menentukan URL Discovery dengan layanan, kredensial, dan label yang sesuai:
classroom_service_with_preview_features = googleapiclient.discovery.build(
serviceName='classroom',
version='v1',
credentials=credentials,
static_discovery=False,
discoveryServiceUrl='https://classroom.googleapis.com/$discovery/rest?labels=DEVELOPER_PREVIEW&key=API_KEY)'
Lihat dokumentasi library klien Google API individual untuk detail tentang tiap bahasa.
Library statis
Library klien dalam bahasa seperti Java, Node.js, PHP, C#, dan Go harus dibuat dari sumber. Library ini disediakan untuk Anda dan sudah menyertakan fitur pratinjau.
Untuk pratinjau publik, library klien Classroom dapat ditemukan dengan library klien Program Pratinjau Developer Workspace lainnya. Untuk pratinjau pribadi, hubungi kontak Google Anda jika Anda perlu membuat library statis.
Anda mungkin perlu mengubah konfigurasi dependensi standar untuk menggunakan library lokal ini, bukan mengimpor library klien standar yang tidak memiliki fitur pratinjau.
Misalnya, untuk menggunakan library klien Go, Anda harus menggunakan perintah replace
dalam file go.mod
untuk mewajibkan modul dari direktori lokal:
module example.com/app
go 1.21.1
require (
golang.org/x/oauth2 v0.12.0
google.golang.org/api v0.139.0 // Classroom library is in here.
)
require (
...
)
// Use a local copy of the Go client library.
replace google.golang.org/api v0.139.0 => ../google-api-go-client
Sebagai contoh lain, jika Anda menggunakan Node.js dan npm, tambahkan download library klien Node.js (googleapis-classroom-1.0.4.tgz
) sebagai dependensi lokal di package.json
:
{
"name": "nodejs-classroom-example",
"version": "1.0.0",
...
"dependencies": {
"@google-cloud/local-auth": "^2.1.0",
"googleapis": "^95.0.0",
"classroom-with-preview-features": "file:./googleapis-classroom-1.0.4.tgz"
}
}
Selanjutnya, dalam aplikasi Anda, wajibkan modul classroom-with-preview-features
selain dependensi reguler, dan buat instance layanan classroom
dari modul tersebut:
const {authenticate} = require('@google-cloud/local-auth');
const {google} = require('googleapis');
const classroomWithPreviewFeatures = require('classroom-with-preview-features');
...
const classroom = classroomWithPreviewFeatures.classroom({
version: 'v1',
auth: auth,
});
...
Menentukan versi API pratinjau
Terlepas dari apakah menggunakan library statis atau dinamis, Anda harus menentukan versi pratinjau saat membuat panggilan API ke metode dengan kemampuan pratinjau.
Berbagai versi yang tersedia, dan fitur yang disertakan, didokumentasikan dalam Roadmap Classroom API. Dokumentasi referensi untuk metode dan kolom juga menjelaskan versi metode atau kolom yang tersedia.
Menentukan versi dilakukan dengan menetapkan kolom PreviewVersion dalam permintaan.
Misalnya, untuk membuat rubrik dengan API pratinjau CRUD Rubrik, Anda harus menetapkan
previewVersion
ke V1_20231110_PREVIEW
dalam permintaan CREATE:
rubric = service.courses().courseWork().rubrics().create(
courseId=course_id,
courseWorkId=coursework_id,
# Specify the preview version. Rubrics CRUD capabilities are
# supported in V1_20231110_PREVIEW and later.
previewVersion="V1_20231110_PREVIEW",
body=body
).execute()
Resource yang terkait dengan panggilan metode pratinjau juga berisi
previewVersion
yang digunakan dalam panggilan sebagai kolom hanya baca untuk membantu Anda memahami
versi mana yang Anda gunakan. Misalnya, respons dari panggilan CREATE
sebelumnya berisi nilai V1_20231110_PREVIEW
:
print(json.dumps(rubric, indent=4))
{
"courseId": "123",
"courseWorkId": "456",
"creationTime": "2023-10-23T18:18:29.932Z",
"updateTime": "2023-10-23T18:18:29.932Z",
"id": "789",
"criteria": [...],
# The preview version used in the call that returned this resource.
"previewVersion": "V1_20231110_PREVIEW",
...
}
Permintaan HTTP
Anda juga dapat menggunakan Classroom API secara langsung dengan HTTP.
Jika membuat permintaan HTTP tanpa library klien, Anda tetap harus mengaktifkan fitur pratinjau untuk menentukan versi pratinjau. Hal ini dilakukan dengan menetapkan label
dengan header X-Goog-Visibilities
dan versi pratinjau yang disebutkan di atas sebagai
parameter kueri atau kolom isi POST. Untuk pratinjau publik, labelnya adalah
DEVELOPER_PREVIEW
.
Misalnya, permintaan curl berikut melakukan panggilan LIST ke layanan Rubrik dengan label visibilitas dan versi pratinjau yang sesuai:
curl \
'https://classroom.googleapis.com/v1/courses/COURSE_ID/courseWork/COURSE_ID/rubrics?key=API_KEY&previewVersion=V1_20231110_PREVIEW' \
--header 'X-Goog-Visibilities: DEVELOPER_PREVIEW' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'Accept: application/json' \
--compressed
Anda juga dapat menentukan versi pratinjau dalam isi permintaan, misalnya saat membuat permintaan POST:
curl --request PATCH \
'https://classroom.googleapis.com/v1/courses/COURSE_ID/courseWork/COURSE_ID/rubrics/RUBRIC_ID?updateMask=criteria&key=API_KEY' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{"criteria":"[...]", "preview_version": "V1_20231110_PREVIEW"}' \
--compressed
API untuk setiap permintaan HTTP dijelaskan dalam dokumentasi REST.