เข้าถึง API ตัวอย่าง

หน้านี้อธิบายวิธีเข้าถึงฟีเจอร์เวอร์ชันตัวอย่างของ Classroom API และ ระบุเวอร์ชันตัวอย่าง

ข้อควรพิจารณา 3 ประการเมื่อใช้ฟีเจอร์เวอร์ชันตัวอย่างเทียบกับ API v1 ที่เสถียร มีดังนี้

1. โปรเจ็กต์ Google Cloud ที่เรียกใช้ต้องลงทะเบียนเข้าร่วมโปรแกรมตัวอย่างสำหรับนักพัฒนาซอฟต์แวร์ของ Google Workspace และได้รับอนุญาตจาก Google
2. ระบบจะไม่แสดงฟีเจอร์ API ในโปรแกรมทดลองใช้ก่อนเปิดตัวหรือโปรแกรมตัวอย่างใน ไลบรารีของไคลเอ็นต์มาตรฐาน และอาจเข้าถึงผ่าน HTTP ไม่ได้โดยค่าเริ่มต้น
3. ในแต่ละครั้งอาจมีสถานะหรือเวอร์ชันของ API หลายรายการใน รุ่นตัวอย่าง

เปิดใช้ฟีเจอร์เวอร์ชันตัวอย่างในไลบรารีของไคลเอ็นต์

ตัวเลือกทั่วไปสำหรับการใช้ Classroom API คือการใช้ไลบรารีของไคลเอ็นต์ ไลบรารีของไคลเอ็นต์มี 3 ประเภท ดังนี้

1. ไลบรารีของไคลเอ็นต์ที่สร้างขึ้นแบบไดนามิก
2. ไลบรารีของไคลเอ็นต์แบบคงที่ที่ Google มีให้
3. ไลบรารีของไคลเอ็นต์ที่กำหนดเอง

การใช้ไลบรารีแบบคงที่ที่สร้างขึ้นแบบไดนามิกหรือที่ Google จัดเตรียมให้เป็นวิธีที่แนะนําในการใช้ API ดูสร้างไลบรารีของไคลเอ็นต์หากต้องการสร้างไลบรารีของคุณเอง การสร้างคลังของคุณเองอยู่นอกขอบเขตของคำแนะนำนี้ แต่คุณควรตรวจสอบส่วนคลังแบบไดนามิกเพื่อดูข้อมูลเกี่ยวกับป้ายกำกับตัวอย่างและบทบาทของป้ายกำกับใน Discovery

ไลบรารีแบบไดนามิก

ไลบรารีในภาษาต่างๆ เช่น Python จะสร้างไลบรารีของไคลเอ็นต์ในรันไทม์โดยใช้เอกสารการค้นพบจากบริการค้นพบ

เอกสารการค้นหาเป็นข้อกำหนดที่เครื่องอ่านได้สำหรับการอธิบายและการใช้ REST API โดยใช้เพื่อสร้างไลบรารีของไคลเอ็นต์ ปลั๊กอิน IDE และ เครื่องมืออื่นๆ ที่โต้ตอบกับ Google API บริการหนึ่งๆ อาจมีเอกสารการค้นหาหลายรายการ

เอกสารการค้นหาสำหรับบริการ Classroom API (classroom.googleapis.com) อยู่ที่ปลายทางต่อไปนี้

https://classroom.googleapis.com/$discovery/rest?labels=PREVIEW_LABEL&version=v1&key=API_KEY

ความแตกต่างที่สำคัญในการทำงานกับ API เวอร์ชันตัวอย่างคือการระบุlabelที่เหมาะสม สำหรับเวอร์ชันตัวอย่างแบบสาธารณะของ Classroom ป้ายกำกับนั้นคือ DEVELOPER_PREVIEW

หากต้องการสร้างไลบรารี Python และสร้างอินสแตนซ์บริการ Classroom ด้วยเมธอดเวอร์ชันตัวอย่าง คุณสามารถระบุ Discovery URL ด้วยบริการ ข้อมูลเข้าสู่ระบบ และป้ายกำกับที่เหมาะสมได้

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)'

ดูรายละเอียดเกี่ยวกับแต่ละภาษาได้ที่เอกสารประกอบของไลบรารีของไคลเอ็นต์ของ Google API แต่ละรายการ

ไลบรารีแบบคงที่

ไลบรารีของไคลเอ็นต์ในภาษาต่างๆ เช่น Java, Node.js, PHP, C# และ Go ต้องสร้างจากแหล่งที่มา เราได้จัดเตรียมไลบรารีเหล่านี้ไว้ให้คุณแล้วและได้รวมฟีเจอร์เวอร์ชันตัวอย่างไว้แล้ว

สำหรับรุ่นตัวอย่างแบบสาธารณะ คุณจะพบไลบรารีของไคลเอ็นต์ Classroom พร้อมกับไลบรารีของไคลเอ็นต์โปรแกรม Workspace Developer Preview อื่นๆ สำหรับรุ่นตัวอย่างแบบส่วนตัว โปรดติดต่อผู้ติดต่อของคุณที่ Google หากต้องการสร้างไลบรารีแบบคงที่

คุณอาจต้องแก้ไขการกำหนดค่าการขึ้นต่อกันตามปกติเพื่อใช้ไลบรารี ในเครื่องเหล่านี้แทนการนำเข้าไลบรารีไคลเอ็นต์มาตรฐานซึ่งไม่มี ฟีเจอร์ตัวอย่าง

เช่น หากต้องการใช้ไลบรารีของไคลเอ็นต์ Go คุณต้องใช้replace คำสั่งในไฟล์ go.mod เพื่อกำหนดให้ใช้โมดูลจากไดเรกทอรีในเครื่อง

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

อีกตัวอย่างหนึ่งคือ หากคุณใช้ Node.js และ npm ให้เพิ่มการดาวน์โหลดไลบรารีไคลเอ็นต์ Node.js (googleapis-classroom-1.0.4.tgz) เป็นการอ้างอิงในเครื่องใน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"
  }
}

จากนั้นในแอปพลิเคชัน ให้กำหนดโมดูล classroom-with-preview-features นอกเหนือจากทรัพยากร Dependency ปกติ และสร้างอินสแตนซ์ของบริการ classroom จากโมดูลนั้น

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,
});

...

ระบุเวอร์ชัน API ของตัวอย่าง

ไม่ว่าคุณจะใช้ไลบรารีแบบคงที่หรือแบบไดนามิก คุณต้องระบุ เวอร์ชันตัวอย่างเมื่อเรียก API ไปยังเมธอดที่มีความสามารถในการแสดงตัวอย่าง

เอกสารเกี่ยวกับเวอร์ชันต่างๆ ที่พร้อมใช้งานและฟีเจอร์ที่รวมไว้จะอยู่ในแผนการพัฒนา Classroom API เอกสารอ้างอิงสำหรับเมธอดและ ฟิลด์ยังอธิบายด้วยว่าเมธอดหรือฟิลด์นั้นใช้ได้ในเวอร์ชันใด

การระบุเวอร์ชันทำได้โดยการตั้งค่าฟิลด์ PreviewVersion ในคำขอ เช่น หากต้องการสร้างเกณฑ์การให้คะแนนด้วย Rubrics CRUD Preview API คุณจะต้องตั้งค่า previewVersion เป็น V1_20231110_PREVIEW ในคำขอ 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()

ทรัพยากรที่เชื่อมโยงกับการเรียกใช้เมธอดแสดงตัวอย่างจะมี previewVersion ที่ใช้ในการเรียกเป็นฟิลด์แบบอ่านอย่างเดียว เพื่อช่วยให้คุณเข้าใจ ว่าคุณกำลังใช้เวอร์ชันใด เช่น การตอบกลับจาก CREATE ที่เรียกก่อนหน้านี้มีค่า 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",
  ...
}

คำขอ HTTP

นอกจากนี้ยังใช้ Classroom API โดยตรงกับ HTTP ได้ด้วย

หากคุณส่งคำขอ HTTP โดยไม่มีไลบรารีของไคลเอ็นต์ คุณยังคงต้องเปิดใช้ ฟีเจอร์เวอร์ชันตัวอย่างระบุเวอร์ชันตัวอย่าง โดยการตั้งค่า label ด้วยส่วนหัว X-Goog-Visibilities และเวอร์ชันตัวอย่างที่กล่าวถึงข้างต้นเป็น พารามิเตอร์การค้นหาหรือฟิลด์เนื้อความ POST (ดูเอกสารอ้างอิง API แต่ละรายการที่เหมาะสม) สำหรับเวอร์ชันตัวอย่างแบบสาธารณะ ป้ายกำกับคือ DEVELOPER_PREVIEW

ตัวอย่างเช่น คำขอ curl ต่อไปนี้จะเรียกใช้ LIST ไปยังบริการ Rubrics โดยใช้ป้ายกำกับระดับการเข้าถึงและเวอร์ชันตัวอย่างที่เหมาะสม

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

นอกจากนี้ คุณยังระบุเวอร์ชันตัวอย่างในเนื้อความของคำขอได้ด้วย เช่น เมื่อส่งคำขอ 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 สำหรับคำขอ HTTP แต่ละรายการอธิบายไว้ในเอกสารประกอบ REST

Google Apps Script

คุณเรียกใช้ API เวอร์ชันตัวอย่างจาก Google Apps Script ได้ อย่างไรก็ตาม มี ความแตกต่างเล็กน้อยจากการใช้งาน Apps Script ทั่วไป

1. คุณต้องกำหนดค่าสคริปต์ให้ใช้โปรเจ็กต์ Google Cloud ที่คุณลงทะเบียนเข้าร่วมโปรแกรมตัวอย่างสำหรับนักพัฒนาแอป
2. บริการขั้นสูงไม่รองรับวิธีการแสดงตัวอย่าง คุณจึงต้องส่งคำขอโดยตรงด้วย HTTP
3. คุณต้องระบุป้ายกำกับและเวอร์ชันตัวอย่างตามที่อธิบายไว้ในส่วน HTTP ก่อนหน้า

ดูคู่มือเริ่มต้นที่เกี่ยวข้องเพื่อทำความคุ้นเคยกับ Apps Script และตั้งค่าโปรเจ็กต์พื้นฐาน จากนั้นทำตาม วิธีการต่อไปนี้เพื่อเริ่มใช้ API การโทรเวอร์ชันตัวอย่าง

เปลี่ยนโปรเจ็กต์ Cloud ที่สคริปต์ใช้

ในการตั้งค่าโปรเจ็กต์ ให้คลิกเปลี่ยนโปรเจ็กต์ แล้วป้อน รหัสโปรเจ็กต์ Cloud ของโปรเจ็กต์ที่คุณลงทะเบียนเข้าร่วมโปรแกรม ตัวอย่างสำหรับนักพัฒนาแอป (โดยค่าเริ่มต้น สคริปต์ Apps Script จะใช้โปรเจ็กต์ทั่วไป) เฉพาะโปรเจ็กต์ที่ลงทะเบียนเท่านั้นที่เรียกใช้เมธอดเวอร์ชันตัวอย่างได้

กำหนดค่าคำขอ HTTP

จากนั้นกำหนดค่าคำขอ HTTP ของเมธอดที่คุณต้องการเรียกกลับในเอดิเตอร์ ตัวอย่างเช่น ในการเริ่มต้นอย่างรวดเร็ว การแสดงหลักสูตรด้วยบริการ Classroom จะมีลักษณะดังนี้

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);
  }
}

การดำเนินการที่เทียบเท่ากันโดยใช้ HTTP โดยตรงคือ

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);
  }
}

เมื่อใช้บริการขั้นสูง ระบบจะอนุมานขอบเขต OAuth ที่จำเป็น แต่หากต้องการ เรียกใช้ HTTP โดยตรงไปยัง Google APIs ใน Apps Script คุณจะต้อง เพิ่มขอบเขตที่เหมาะสมด้วยตนเอง

ในการตั้งค่าโปรเจ็กต์ ให้เปิดใช้แสดงไฟล์ Manifest "appsscript.json" ใน เครื่องมือแก้ไข กลับไปที่เอดิเตอร์ แล้วเพิ่ม oauthScopes ลงในไฟล์ appscript.json สำหรับ ขอบเขตที่คุณต้องการ ขอบเขตของเมธอดหนึ่งๆ จะแสดงอยู่ในหน้าอ้างอิง เช่น ดูหน้าวิธีการ list courses.courseWork.rubrics

ไฟล์ appscript.json ที่อัปเดตแล้วอาจมีลักษณะดังนี้

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

ส่งป้ายกำกับและเวอร์ชันแสดงตัวอย่าง

กลับไปที่สคริปต์และตรวจสอบว่าคุณได้เพิ่มป้ายกำกับและตัวอย่างที่เหมาะสม ตามที่อธิบายไว้ในส่วน HTTP ก่อนหน้า ตัวอย่างการเรียก LIST ไปยังบริการ Rubrics จะมีลักษณะดังนี้

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);
}