หน้านี้อธิบายวิธีเข้าถึงฟีเจอร์ตัวอย่างของ Classroom API และระบุเวอร์ชันตัวอย่าง
ข้อควรพิจารณา 2 ประการเมื่อใช้ฟีเจอร์การแสดงตัวอย่างเมื่อเทียบกับ API v1 แบบเสถียรมีดังนี้
- ฟีเจอร์ API ในการทดลองใช้ก่อนเปิดตัวหรือโปรแกรมตัวอย่างจะไม่แสดงในไลบรารีไคลเอ็นต์มาตรฐาน และอาจเข้าถึงไม่ได้โดยค่าเริ่มต้นผ่าน HTTP
- ในช่วงเวลาหนึ่งๆ อาจมีสถานะ API หรือเวอร์ชันหลายรายการในตัวอย่าง
เปิดใช้ฟีเจอร์การแสดงตัวอย่างในไลบรารีของไคลเอ็นต์
ตัวเลือกทั่วไปในการใช้ Classroom API คือการใช้ไลบรารีของไคลเอ็นต์ ไลบรารีของไคลเอ็นต์มี 3 ประเภท ได้แก่
- ไลบรารีของไคลเอ็นต์ที่สร้างแบบไดนามิก
- ไลบรารีของไคลเอ็นต์แบบคงที่ที่ Google มีให้
- ไลบรารีไคลเอ็นต์ที่คุณกำหนดเอง
การใช้ไลบรารีแบบคงที่ที่สร้างแบบไดนามิกหรือที่ 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