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 bila dibandingkan dengan API v1 adalah:

Project Google Cloud yang memanggil harus terdaftar di Google Workspace Program Pratinjau Developer dan diizinkan dicantumkan oleh Google.
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.

Google Apps Script

API pratinjau dapat dipanggil dari Google Apps Script. Namun, ada beberapa perbedaan dari penggunaan Apps Script pada umumnya.

Anda harus mengonfigurasi skrip untuk menggunakan project Google Cloud mana pun yang Anda terdaftar dalam 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, sebagaimana dijelaskan dalam bagian HTTP.

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

Mengubah project Cloud yang digunakan oleh skrip

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

Mengonfigurasi permintaan HTTP

Selanjutnya, konfigurasikan permintaan HTTP dari metode apa pun yang ingin Anda panggil kembali Editor. Misalnya, dalam panduan memulai, mencantumkan kursus dengan Classroom layanannya 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 setara yang 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 melakukan panggilan HTTP langsung ke Google API di Apps Script, Anda harus menambahkan cakupan yang sesuai secara manual.

Di Project Settings, aktifkan Show "appsscript.json" file manifes dalam editor video. Kembali ke Editor, tambahkan oauthScopes ke file appscript.json untuk cakupan mana pun yang Anda butuhkan. Cakupan untuk metode tertentu tercantum dalam halaman referensi. Misalnya, lihat metode daftar courses.courseWork.rubrics halaman kami.

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"
  ]
}

Memberikan label dan versi pratinjau

Kembali ke skrip, pastikan Anda telah menambahkan label dan 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);
}