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

Halaman ini diterjemahkan oleh Cloud Translation API.

Mengakses API pratinjau

Halaman ini menjelaskan cara mengakses fitur pratinjau Classroom API dan menentukan versi pratinjau.

Dua pertimbangan saat menggunakan fitur pratinjau jika dibandingkan dengan API v1 adalah:

Fitur API di program akses awal atau pratinjau tidak ditampilkan dalam standar klien dan mungkin tidak dapat diakses secara {i>default<i} melalui HTTP.
Pada waktu tertentu mungkin ada beberapa status API, atau versi, di pratinjau.

Mengaktifkan fitur pratinjau di library klien

Opsi umum untuk menggunakan Classroom API adalah dengan library klien. Ada adalah tiga jenis library klien:

Library klien yang dihasilkan secara dinamis
Library klien statis yang disediakan Google
Library klien kustom Anda sendiri

Menggunakan library statis yang dibuat secara dinamis atau disediakan Google adalah cara yang disarankan untuk menggunakan API. Lihat membuat library klien jika Anda perlu membuat koleksi Anda sendiri. Membuat koleksi Anda sendiri berada di luar cakupan setelan ini panduan, tetapi sebaiknya Anda meninjau bagian library dinamis untuk mempelajari label pratinjau dan perannya dalam Penemuan.

Library dinamis

Library dalam bahasa seperti Python menghasilkan library klien saat runtime menggunakan Dokumen Discovery dari layanan Discovery.

Dokumen Penemuan adalah spesifikasi yang dapat dibaca mesin untuk menggambarkan dan menggunakan REST API. Library ini digunakan untuk membangun library klien, plugin IDE, dan dengan alat lain yang berinteraksi dengan Google API. Satu layanan mungkin menyediakan beberapa dokumen discovery.

Discovery Documents 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 dalam menggunakan API pratinjau adalah menentukan label yang sesuai. Untuk pratinjau publik Classroom yang diberi label DEVELOPER_PREVIEW.

Untuk membuat library Python dan membuat instance layanan Classroom dengan metode pratinjau, Anda dapat menentukan URL Discovery dengan layanan yang sesuai, kredensial, dan label:

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 mengetahui detail tentang setiap informasi tersebut di bahasa target.

Library statis

Library klien dalam bahasa seperti Java, Node.js, PHP, C#, dan Go harus dibangun dari sumber. Library ini disediakan untuk Anda dan memiliki fitur pratinjau yang sudah digabungkan.

Untuk pratinjau publik, library klien Classroom dapat ditemukan Library klien Program Pratinjau Developer Workspace. Untuk pratinjau pribadi, hubungi kontak Google jika Anda memerlukan library statis yang dibuat.

Anda mungkin perlu memodifikasi konfigurasi dependensi umum Anda untuk menggunakan lokal alih-alih mengimpor pustaka klien standar, yang memiliki fitur pratinjau.

Misalnya, untuk menggunakan library klien Go, Anda harus menggunakan replace perintah dalam file go.mod Anda untuk memerlukan 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 klien Node.js download library (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"
  }
}

Kemudian, dalam aplikasi Anda, wajibkan modul classroom-with-preview-features selain dependensi reguler, dan membuat 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 menetapkan versi pratinjau saat melakukan panggilan API ke metode dengan kemampuan pratinjau.

Berbagai versi yang tersedia, dan fiturnya, didokumentasikan dalam Roadmap API Classroom. Dokumentasi referensi untuk metode dan kolom juga menjelaskan versi metode atau kolom yang tersedia.

Menentukan versi dilakukan dengan menyetel kolom PreviewVersion dalam permintaan. Misalnya, untuk membuat rubrik dengan Rubrics CRUD preview API, Anda perlu 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 digunakan dalam panggilan sebagai kolom hanya baca untuk membantu Anda memahami versi yang Anda gunakan. Misalnya, respons dari fungsi CREATE sebelumnya panggilan 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 Anda membuat permintaan HTTP tanpa library klien, Anda masih harus mengaktifkan fitur pratinjau menentukan versi pratinjau. Hal ini dilakukan dengan menyetel label dengan header X-Goog-Visibilities dan versi pratinjau yang disebutkan di atas sebagai parameter kueri atau bidang isi POST (lihat setiap API yang sesuai dokumentasi referensi). Untuk pratinjau publik, labelnya adalah DEVELOPER_PREVIEW.

Misalnya, permintaan curl berikut membuat panggilan LIST ke layanan Rubrik dengan label visibilitas dan versi pratinjau yang sesuai:

curl \
  'https://classroom.googleapis.com/v1/courses/COURSE_ID/courseWork/COURSE_WORK_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_WORK_ID/rubrics/RUBRIC_ID?updateMask=criteria&key=API_KEY&previewVersion=V1_20231110_PREVIEW' \
  --header 'X-Goog-Visibilities: DEVELOPER_PREVIEW' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"criteria":"[...]"}' \
  --compressed

API untuk setiap permintaan HTTP dijelaskan di dokumentasi REST.