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

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

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

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