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.

Tiga pertimbangan saat menggunakan fitur pratinjau jika dibandingkan dengan API v1 yang stabil adalah:

Project Google Cloud yang memanggil harus didaftarkan di Program Pratinjau Developer Google Workspace dan diizinkan dicantumkan oleh Google.
Fitur API dalam program akses awal atau pratinjau tidak ditampilkan di library klien standar dan mungkin tidak dapat diakses secara default melalui HTTP.
Pada waktu tertentu, mungkin ada beberapa status atau versi API dalam pratinjau.

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

Menggunakan library statis yang dibuat secara dinamis atau disediakan Google adalah cara yang direkomendasikan untuk menggunakan API. Lihat membuat library klien jika Anda perlu membuat library 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 Penemuan.

Library dinamis

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

Dokumen Discovery adalah spesifikasi yang dapat dibaca komputer untuk mendeskripsikan dan menggunakan REST API. Dokumen ini digunakan untuk mem-build library klien, plugin IDE, dan alat lainnya 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, label tersebut adalah DEVELOPER_PREVIEW.

Untuk membuat library Python dan membuat instance layanan Classroom dengan metode pratinjau, Anda dapat menentukan URL Penemuan 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 mengetahui detail tentang setiap bahasa.

Library statis

Library klien dalam bahasa seperti Java, Node.js, PHP, C#, dan Go harus di-build 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 memerlukan library statis yang dibuat.

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 perlu menggunakan perintah replace dalam file go.mod 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 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"
  }
}

Kemudian, dalam aplikasi Anda, wajibkan modul classroom-with-preview-features selain dependensi reguler, lalu 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 Anda menggunakan library statis atau dinamis, Anda harus menentukan versi pratinjau saat melakukan panggilan API ke metode dengan kemampuan pratinjau.

Berbagai versi yang tersedia, dan fitur yang disertakan, didokumentasikan dalam Peta Jalan Classroom API. Dokumentasi referensi untuk metode dan kolom juga menjelaskan versi mana yang menyediakan metode atau kolom tersebut.

Menentukan versi dilakukan dengan menetapkan kolom PreviewVersion dalam permintaan. Misalnya, untuk membuat rubrik dengan API pratinjau CRUD Rubrik, Anda akan 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 yang digunakan. 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 perlu mengaktifkan fitur pratinjau yang 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 kolom isi POST (lihat dokumentasi referensi API individual yang sesuai). 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 dalam dokumentasi REST.

Google Apps Script

Anda dapat memanggil API pratinjau dari Google Apps Script. Namun, ada beberapa perbedaan dari penggunaan Apps Script standar.

Anda harus mengonfigurasi skrip untuk menggunakan project Google Cloud yang Anda daftarkan di Program Pratinjau Developer.
Layanan Lanjutan tidak mendukung metode pratinjau, sehingga Anda harus membuat permintaan langsung dengan HTTP.
Anda harus memberikan label dan versi pratinjau, seperti yang dijelaskan di bagian HTTP sebelumnya.

Lihat panduan memulai yang sesuai untuk memahami Apps Script dan menyiapkan project dasar. Kemudian, ikuti petunjuk berikut untuk mulai memanggil API pratinjau:

Mengubah project Cloud yang digunakan oleh skrip

Di Project Settings, klik Change project dan masukkan ID project Cloud dari project mana pun yang Anda daftarkan ke Developer Preview Program (secara default, skrip Apps Script menggunakan project generik). Hanya project yang terdaftar yang dapat memanggil metode pratinjau.

Mengonfigurasi permintaan HTTP

Selanjutnya, konfigurasikan permintaan HTTP dari metode mana pun yang ingin Anda panggil kembali di Editor. Misalnya, dalam panduan memulai, mencantumkan kursus dengan layanan Classroom akan terlihat seperti ini:

function listCourses() {
  try {
    const response = Classroom.Courses.list();
    const courses = response.courses;
    if (!courses || courses.length === 0) {
      console.log('No courses found.');
      return;
    }
    for (const course of courses) {
      console.log('%s (%s)', course.name, course.id);
    }
  } catch (err) {
    // TODO: Developer to handle.
    console.log(err.message);
  }
}

Operasi yang setara menggunakan HTTP secara langsung adalah:

function listCourses() {
  const response = UrlFetchApp.fetch(
        'https://classroom.googleapis.com/v1/courses', {
        method: 'GET',
        headers: {'Authorization': 'Bearer ' + ScriptApp.getOAuthToken()},
        contentType: 'application/json',
      });
  const data = JSON.parse(response.getContentText());
  if (data.error) {
    // TODO: Developer to handle.
    console.log(err.message);
    return;
  }
  if (!data.courses || !data.courses.length) {
    console.log('No courses found.');
    return;
  }
  for (const course of data.courses) {
    console.log('%s (%s)', course.name, course.id);
  }
}

Saat menggunakan layanan Lanjutan, cakupan OAuth yang diperlukan akan disimpulkan, tetapi untuk melakukan panggilan HTTP langsung ke Google API di Apps Script, Anda perlu menambahkan cakupan yang sesuai secara manual.

Di Project Settings, aktifkan Show "appsscript.json" manifest file in editor. Kembali ke Editor, tambahkan oauthScopes ke file appscript.json untuk cakupan apa pun yang Anda perlukan. Cakupan untuk metode tertentu tercantum di halaman referensi. Misalnya, lihat halaman metode daftar kursus.courseWork.rubrics.

File appscript.json yang telah diupdate mungkin terlihat seperti ini:

{
  "timeZone": "America/Los_Angeles",
  "dependencies": {
  },
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "oauthScopes": [
    "https://www.googleapis.com/auth/script.external_request",
    "https://www.googleapis.com/auth/classroom.coursework.students",
    "https://www.googleapis.com/auth/classroom.courses",
    "https://www.googleapis.com/auth/spreadsheets.readonly",
    "https://www.googleapis.com/auth/spreadsheets"
  ]
}

Memberikan label dan versi pratinjau

Kembali ke skrip, pastikan Anda telah menambahkan label dan versi pratinjau yang sesuai seperti yang dijelaskan di bagian HTTP sebelumnya. Contoh panggilan LIST ke layanan Rubrik akan terlihat seperti:

function listRubrics() {
  const courseId = COURSE_ID;
  const courseWorkId = COURSE_WORK_ID;
  const response = UrlFetchApp.fetch(
         `https://classroom.googleapis.com/v1/courses/${courseId}/courseWork/${courseWorkId}/rubrics?previewVersion=V1_20231110_PREVIEW`, {
        method: 'GET',
        headers: {
          'Authorization': 'Bearer ' + ScriptApp.getOAuthToken(),
          'X-Goog-Visibilities': 'DEVELOPER_PREVIEW'
        },
        contentType: 'application/json',
        muteHttpExceptions: true
      });
  const data = JSON.parse(response.getContentText());
  console.log(data)
  if (data.error) {
    // TODO: Developer to handle.
    console.log(error.message);
    return;
  }
  if (!data.rubrics || !data.rubrics.length) {
    console.log('No rubrics for this coursework!');
    return;
  }
  console.log(data.rubrics);
}