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

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

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

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

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

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

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

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

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

ไลบรารีในภาษาต่างๆ เช่น Python จะสร้างไลบรารีของไคลเอ็นต์ขณะรันไทม์โดยใช้เอกสาร Discovery จากบริการ 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 Developer อื่นๆ สำหรับการแสดงตัวอย่างแบบส่วนตัว โปรดติดต่อผู้ติดต่อของ 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 สำหรับตัวอย่างแบบสาธารณะ ป้ายกำกับคือ DEVELOPER_PREVIEW

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

curl \
  'https://classroom.googleapis.com/v1/courses/COURSE_ID/courseWork/COURSE_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_ID//rubrics/RUBRIC_ID?updateMask=criteria&key=API_KEY' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"criteria":"[...]", "preview_version": "V1_20231110_PREVIEW"}' \
  --compressed

โปรดดูคำอธิบาย API สำหรับคำขอ HTTP แต่ละรายการในเอกสารประกอบ REST