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 terdaftar dalam Program Pratinjau Developer Google Workspace dan diizinkan oleh Google.
Fitur API dalam program akses awal atau pratinjau tidak diekspos di library klien standar dan mungkin tidak dapat diakses secara default melalui HTTP.
Setiap saat, 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 membangun library klien jika Anda perlu membangun library Anda sendiri. Membuat 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 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 membuat library klien, plugin IDE, dan alat lainnya yang berinteraksi dengan Google API. Satu layanan dapat menyediakan beberapa dokumen discovery.

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 saat 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 mengetahui detail tentang setiap bahasa.

Library statis

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

Untuk pratinjau publik, library klien Classroom dapat ditemukan bersama dengan library klien Program Pratinjau Developer Workspace lainnya. Untuk pratinjau pribadi, hubungi kontak Google Anda jika Anda memerlukan pembuatan library statis.

Anda mungkin perlu mengubah konfigurasi dependensi umum 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 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 di aplikasi Anda, panggil 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 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 Roadmap Classroom API. Dokumentasi referensi untuk metode dan kolom juga menjelaskan versi tempat metode atau kolom tersedia.

Penentuan versi dilakukan dengan menyetel kolom PreviewVersion dalam permintaan. Misalnya, untuk membuat rubrik dengan Rubrics CRUD Preview API, 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 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

Classroom API juga dapat digunakan secara langsung dengan HTTP.

Jika Anda membuat permintaan HTTP tanpa library klien, Anda tetap perlu mengaktifkan fitur pratinjau dan 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 yang umum.

Anda harus mengonfigurasi skrip untuk menggunakan project Google Cloud mana pun yang Anda daftarkan ke Program Pratinjau Developer.
Layanan Lanjutan tidak mendukung metode pratinjau, jadi Anda harus membuat permintaan secara 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, lalu masukkan project ID Cloud dari project yang Anda daftarkan ke Program Pratinjau Developer (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 apa 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 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 di Editor, tambahkan oauthScopes ke file appscript.json untuk cakupan yang Anda butuhkan. Cakupan untuk metode tertentu tercantum di halaman referensi. Misalnya, lihat halaman metode daftar rubrik courseWork.courses.

File appscript.json yang 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"
  ]
}

Menyediakan label dan versi pratinjau

Kembali ke skrip Anda, 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);
}