בדף הזה נסביר איך נכנסים לתכונות התצוגה המקדימה של Classroom API ומציינים גרסאות לתצוגה מקדימה.
שני השיקולים שיש להביא בחשבון כשמשתמשים בתכונות של תצוגה מקדימה בהשוואה ל-API היציב v1 הם:
- תכונות API בתוכניות של גישה מוקדמת או של גרסת טרום-השקה (Preview) לא חשופות בספריות הלקוח הרגילות, ויכול להיות שאי אפשר לגשת אליהן כברירת מחדל ב-HTTP.
- בכל רגע נתון יכולים להיות כמה מצבי API או כמה גרסאות בתצוגה מקדימה.
הפעלה של תכונות תצוגה מקדימה בספריות לקוח
אפשרות נפוצה לשימוש ב-Classroom API היא באמצעות ספריית לקוח. יש שלושה סוגים של ספריות לקוח:
- ספריות לקוח שנוצרות באופן דינמי
- ספריות לקוח סטטיות ש-Google מספקת
- ספריית לקוח מותאמת אישית
מומלץ להשתמש ב-API עם ספריות סטטיות שנוצרות באופן דינמי או ש-Google מספקת. אם אתם צריכים ליצור ספרייה משלכם, קראו את המאמר יצירה של ספריות לקוח. המדריך הזה לא עוסק ביצירת ספרייה משלכם, אבל כדאי לעיין בקטע ספריות דינמיות כדי לקבל מידע נוסף על תוויות תצוגה מקדימה ועל התפקיד שלהן ב-Discovery.
ספריות דינמיות
ספריות בשפות כמו Python יוצרות את ספריית הלקוח בזמן הריצה באמצעות מסמך Discovery משירות Discovery.
מסמך Discovery הוא מפרט קריא למחשבים לתיאור ולשימוש בממשקי API ל-REST. הוא משמש ליצירת ספריות לקוח, יישומי פלאגין בסביבת פיתוח משולבת (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 של Discovery עם השירות, פרטי הכניסה והתווית המתאימים:
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 אם אתם צריכים ליצור ספריות סטטיות.
יכול להיות שתצטרכו לשנות את ההגדרה הטיפוסית של יחסי התלות כדי להשתמש בספריות המקומיות האלה במקום לייבא את ספריות הלקוח הרגילות, שאין בהן את התכונות של התצוגה המקדימה.
לדוגמה, כדי להשתמש בספריית הלקוח של 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
בנוסף לתלות הרגולריות, וליצור את השירות 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
יש גם אפשרות לצרוך את ה-API של Classroom ישירות באמצעות HTTP.
גם אם שולחים בקשות HTTP בלי ספריית לקוח, עדיין צריך להפעיל תכונות תצוגה מקדימה ולציין גרסה של תצוגה מקדימה. לשם כך, מגדירים label
עם הכותרת X-Goog-Visibilities
וגרסת התצוגה המקדימה שהוזכרה כפרמטר של שאילתה או כשדה גוף של POST. בתצוגה מקדימה גלויה לכולם, התווית היא DEVELOPER_PREVIEW
.
לדוגמה, בקשת ה-Curl הבאה מבצעת קריאת LIST לשירות Rubrics עם תווית החשיפה וגרסת התצוגה המקדימה המתאימה:
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.