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 stabil adalah:

1. Fitur API dalam program akses awal atau pratinjau tidak diekspos dalam library klien standar dan mungkin tidak dapat diakses secara default melalui HTTP.
2. 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:

1. Library klien yang dibuat secara dinamis
2. Library klien statis yang disediakan Google
3. 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()

Catatan: Versi pratinjau dimaksudkan untuk sementara selagi fitur divalidasi untuk ketersediaan umum di API v1. Perilaku versi pratinjau dapat berubah setelah periode penghentian penggunaan. Lihat Roadmap Classroom API untuk mengetahui informasi selengkapnya.

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",
  ...
}

Catatan: Versi pratinjau yang terkait dengan resource sesuai dengan versi yang digunakan untuk mengambil resource, bukan panggilan untuk membuat resource. Jika Anda membuat panggilan GET, LIST, atau PATCH di masa mendatang dengan versi baru yang ditentukan, versi baru akan ditampilkan.

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.