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

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

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

  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 APIs บริการหนึ่งอาจมี เอกสารการค้นพบ

เอกสาร 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 หากต้องการสร้างไลบรารีแบบคงที่

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

ตัวอย่างเช่น หากต้องการใช้ไลบรารีของไคลเอ็นต์ 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) เป็นทรัพยากร Dependency ในเครื่องใน 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 ไปยังบริการเกณฑ์การให้คะแนน พร้อมป้ายกำกับระดับการเข้าถึงและเวอร์ชันตัวอย่างที่เหมาะสม

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 การแสดงตัวอย่าง

เปลี่ยนโปรเจ็กต์ที่อยู่ในระบบคลาวด์ที่สคริปต์ใช้

ในการตั้งค่าโปรเจ็กต์ ให้คลิกเปลี่ยนโปรเจ็กต์ แล้วป้อน รหัสโปรเจ็กต์ที่อยู่ในระบบคลาวด์ของโปรเจ็กต์ที่คุณลงทะเบียนเป็นนักพัฒนาแอป โปรแกรมทดลองใช้ (โดยค่าเริ่มต้น สคริปต์ของ 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 คุณต้องทำดังนี้ เพิ่มขอบเขตที่เหมาะสมด้วยตนเอง

ในการตั้งค่าโปรเจ็กต์ ให้เปิดใช้แสดง "appsscript.json" ไฟล์ Manifest ใน Editor กลับไปในส่วนผู้แก้ไข แล้วเพิ่ม oauthScopes ลงในไฟล์ appscript.json สำหรับ ขอบเขตใดก็ได้ที่คุณต้องการ ขอบเขตของเมธอดที่ระบุจะแสดงอยู่ในส่วน หน้าอ้างอิง ตัวอย่างเช่น โปรดดูเมธอดรายการ 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 ถึง บริการเกณฑ์การให้คะแนนจะมีลักษณะดังนี้

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