เข้าถึง 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 จะสร้างไลบรารีของไคลเอ็นต์ในรันไทม์โดยใช้เอกสารการค้นพบจากบริการค้นพบ

เอกสารการค้นพบคือข้อกำหนดที่เครื่องอ่านได้สำหรับการอธิบายและ ใช้ API ของ REST โดยใช้เพื่อสร้างไลบรารีของไคลเอ็นต์ ปลั๊กอิน 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 ด้วย เมธอดเวอร์ชันตัวอย่าง คุณสามารถระบุ 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 module นอกเหนือจากทรัพยากร Dependency ปกติ และสร้างอินสแตนซ์ของ classroom service จากโมดูลนั้น

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 สำหรับขอบเขตที่คุณต้องการ ขอบเขตของแต่ละเมธอดจะแสดงอยู่ใน หน้าอ้างอิง เช่น ดูหน้าเมธอด 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);
}