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

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

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

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

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

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

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

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

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

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

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

เอกสาร Discovery สำหรับบริการ 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 ด้วยวิธีการเวอร์ชันตัวอย่าง คุณสามารถระบุ 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 อื่นๆ สำหรับตัวอย่างเพลงส่วนตัว โปรดติดต่อตัวแทนของ 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,
});

...

ระบุเวอร์ชันของ Preview 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()

หมายเหตุ: เวอร์ชันตัวอย่างมีไว้สำหรับใช้งานชั่วคราวระหว่างที่ฟีเจอร์ได้รับการตรวจสอบเพื่อให้บริการแก่ผู้ใช้ทั่วไปใน API v1 ลักษณะการทํางานของเวอร์ชันตัวอย่างอาจมีการเปลี่ยนแปลงหลังจากกรอบเวลาการเลิกใช้งาน ดูข้อมูลเพิ่มเติมได้ที่แผนพัฒนา Classroom API

ทรัพยากรที่เชื่อมโยงกับการเรียกใช้เมธอดเวอร์ชันตัวอย่างจะมี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",
  ...
}

หมายเหตุ: เวอร์ชันตัวอย่างที่เชื่อมโยงกับทรัพยากรจะสอดคล้องกับเวอร์ชันที่ใช้เรียกทรัพยากร ไม่จำเป็นต้องเป็นคําเรียกสร้างทรัพยากร หากคุณเรียก GET, LIST หรือ PATCH ในอนาคตโดยระบุเวอร์ชันใหม่ ระบบจะแสดงเวอร์ชันใหม่

คำขอ 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 สำหรับขอบเขตที่ต้องการ ขอบเขตของเมธอดหนึ่งๆ จะแสดงอยู่ในหน้าข้อมูลอ้างอิง เช่น ดูหน้า methods ของ courses.courseWork.rubrics list

ไฟล์ 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);
}